safe-kit 0.0.11__py3-none-any.whl

safe_kit/service.py

@@ -0,0 +1,343 @@
+from typing import Any, cast
+
+import requests
+
+from safe_kit.errors import SafeServiceError
+from safe_kit.types import (
+    SafeBalanceResponse,
+    SafeCollectibleResponse,
+    SafeCreationInfoResponse,
+    SafeDataDecoderResponse,
+    SafeDelegateResponse,
+    SafeIncomingTransactionResponse,
+    SafeInfoResponse,
+    SafeModuleTransactionResponse,
+    SafeMultisigTransactionResponse,
+    SafeServiceInfo,
+    SafeTokenResponse,
+    SafeTransactionData,
+)
+
+
+class SafeServiceClient:
+    """
+    Client for interacting with the Safe Transaction Service API.
+    """
+
+    def __init__(self, service_url: str):
+        self.service_url = service_url.rstrip("/")
+
+    def _handle_response(self, response: requests.Response) -> Any:
+        try:
+            response.raise_for_status()
+            if response.content:
+                return response.json()
+            return None
+        except requests.HTTPError as e:
+            raise SafeServiceError(f"Service error: {e}", response.status_code) from e
+        except Exception as e:
+            raise SafeServiceError(f"Unexpected error: {e}") from e
+
+    def get_service_info(self) -> SafeServiceInfo:
+        """
+        Returns information about the Safe Transaction Service.
+        """
+        response = requests.get(f"{self.service_url}/v1/about/")
+        data = self._handle_response(response)
+        return SafeServiceInfo(**data)
+
+    def propose_transaction(
+        self,
+        safe_address: str,
+        safe_tx_data: SafeTransactionData,
+        safe_tx_hash: str,
+        sender_address: str,
+        signature: str,
+        origin: str | None = None,
+    ) -> None:
+        """
+        Proposes a transaction to the Safe Transaction Service.
+        """
+        url = f"{self.service_url}/v1/safes/{safe_address}/multisig-transactions/"
+
+        payload = {
+            "to": safe_tx_data.to,
+            "value": safe_tx_data.value,
+            "data": safe_tx_data.data if safe_tx_data.data else None,
+            "operation": safe_tx_data.operation,
+            "safeTxGas": safe_tx_data.safe_tx_gas,
+            "baseGas": safe_tx_data.base_gas,
+            "gasPrice": safe_tx_data.gas_price,
+            "gasToken": safe_tx_data.gas_token,
+            "refundReceiver": safe_tx_data.refund_receiver,
+            "nonce": safe_tx_data.nonce,
+            "contractTransactionHash": safe_tx_hash,
+            "sender": sender_address,
+            "signature": signature,
+            "origin": origin,
+        }
+
+        response = requests.post(url, json=payload)
+        self._handle_response(response)
+
+    def get_pending_transactions(
+        self, safe_address: str, current_nonce: int | None = None
+    ) -> list[SafeMultisigTransactionResponse]:
+        """
+        Returns the list of pending transactions for a Safe.
+        """
+        return self.get_multisig_transactions(
+            safe_address,
+            executed=False,
+            trust=True,
+            nonce_gte=current_nonce,
+        )
+
+    def get_multisig_transactions(
+        self,
+        safe_address: str,
+        executed: bool | None = None,
+        trust: bool | None = None,
+        nonce_gte: int | None = None,
+        ordering: str | None = None,
+        limit: int | None = None,
+        offset: int | None = None,
+    ) -> list[SafeMultisigTransactionResponse]:
+        """
+        Returns the list of multisig transactions for a Safe.
+        """
+        url = f"{self.service_url}/v1/safes/{safe_address}/multisig-transactions/"
+        params: dict[str, Any] = {}
+
+        if executed is not None:
+            params["executed"] = str(executed).lower()
+        if trust is not None:
+            params["trusted"] = str(trust).lower()
+        if nonce_gte is not None:
+            params["nonce__gte"] = str(nonce_gte)
+        if ordering:
+            params["ordering"] = ordering
+        if limit is not None:
+            params["limit"] = str(limit)
+        if offset is not None:
+            params["offset"] = str(offset)
+
+        response = requests.get(url, params=params)
+        data = self._handle_response(response)
+        results = data.get("results", [])
+        return [SafeMultisigTransactionResponse(**tx) for tx in results]
+
+    def confirm_transaction(self, safe_tx_hash: str, signature: str) -> None:
+        """
+        Adds a confirmation (signature) to a pending transaction.
+        """
+        url = (
+            f"{self.service_url}/v1/multisig-transactions/{safe_tx_hash}/confirmations/"
+        )
+        payload = {"signature": signature}
+
+        response = requests.post(url, json=payload)
+        self._handle_response(response)
+
+    def delete_transaction(self, safe_tx_hash: str, signature: str) -> None:
+        """
+        Deletes a pending transaction from the Safe Transaction Service.
+        Requires the signature of the proposer.
+        """
+        url = f"{self.service_url}/v1/multisig-transactions/{safe_tx_hash}/"
+        payload = {"signature": signature}
+        response = requests.delete(url, json=payload)
+        self._handle_response(response)
+
+    def get_transaction(self, safe_tx_hash: str) -> SafeMultisigTransactionResponse:
+        """
+        Returns the details of a specific Safe transaction.
+        """
+        url = f"{self.service_url}/v1/multisig-transactions/{safe_tx_hash}/"
+        response = requests.get(url)
+        data = self._handle_response(response)
+        return SafeMultisigTransactionResponse(**data)
+
+    def get_safes_by_owner(self, owner_address: str) -> list[str]:
+        """
+        Returns the list of Safes owned by an address.
+        """
+        url = f"{self.service_url}/v1/owners/{owner_address}/safes/"
+        response = requests.get(url)
+        data = self._handle_response(response)
+        return cast(list[str], data.get("safes", []))
+
+    def get_balances(
+        self, safe_address: str, trusted: bool = False, exclude_spam: bool = True
+    ) -> list[SafeBalanceResponse]:
+        """
+        Returns the balances of a Safe (ETH and ERC20).
+        """
+        url = f"{self.service_url}/v1/safes/{safe_address}/balances/"
+        params = {
+            "trusted": str(trusted).lower(),
+            "exclude_spam": str(exclude_spam).lower(),
+        }
+        response = requests.get(url, params=params)
+        data = self._handle_response(response)
+        return [SafeBalanceResponse(**item) for item in data]
+
+    def get_incoming_transactions(
+        self,
+        safe_address: str,
+        executed: bool | None = None,
+        limit: int | None = None,
+        offset: int | None = None,
+    ) -> list[SafeIncomingTransactionResponse]:
+        """
+        Returns the incoming transactions (ETH/ERC20) for a Safe.
+        """
+        url = f"{self.service_url}/v1/safes/{safe_address}/incoming-transfers/"
+        params: dict[str, Any] = {}
+        if executed is not None:
+            params["executed"] = str(executed).lower()
+        if limit is not None:
+            params["limit"] = str(limit)
+        if offset is not None:
+            params["offset"] = str(offset)
+
+        response = requests.get(url, params=params)
+        data = self._handle_response(response)
+        results = data.get("results", [])
+        return [SafeIncomingTransactionResponse(**tx) for tx in results]
+
+    def get_module_transactions(
+        self,
+        safe_address: str,
+        limit: int | None = None,
+        offset: int | None = None,
+    ) -> list[SafeModuleTransactionResponse]:
+        """
+        Returns the module transactions for a Safe.
+        """
+        url = f"{self.service_url}/v1/safes/{safe_address}/module-transactions/"
+        params: dict[str, Any] = {}
+        if limit is not None:
+            params["limit"] = str(limit)
+        if offset is not None:
+            params["offset"] = str(offset)
+
+        response = requests.get(url, params=params)
+        data = self._handle_response(response)
+        results = data.get("results", [])
+        return [SafeModuleTransactionResponse(**tx) for tx in results]
+
+    def get_safe_info(self, safe_address: str) -> SafeInfoResponse:
+        """
+        Returns detailed information about a Safe.
+        """
+        url = f"{self.service_url}/v1/safes/{safe_address}/"
+        response = requests.get(url)
+        data = self._handle_response(response)
+        return SafeInfoResponse(**data)
+
+    def get_creation_info(self, safe_address: str) -> SafeCreationInfoResponse:
+        """
+        Returns information about when and how a Safe was created.
+        """
+        url = f"{self.service_url}/v1/safes/{safe_address}/creation/"
+        response = requests.get(url)
+        data = self._handle_response(response)
+        return SafeCreationInfoResponse(**data)
+
+    def get_collectibles(
+        self,
+        safe_address: str,
+        trusted: bool = False,
+        exclude_spam: bool = True,
+    ) -> list[SafeCollectibleResponse]:
+        """
+        Returns NFTs (ERC721) owned by the Safe.
+        """
+        url = f"{self.service_url}/v1/safes/{safe_address}/collectibles/"
+        params = {
+            "trusted": str(trusted).lower(),
+            "exclude_spam": str(exclude_spam).lower(),
+        }
+        response = requests.get(url, params=params)
+        data = self._handle_response(response)
+        return [SafeCollectibleResponse(**item) for item in data]
+
+    def get_delegates(self, safe_address: str) -> list[SafeDelegateResponse]:
+        """
+        Returns the list of delegates for a Safe.
+        """
+        url = f"{self.service_url}/v1/delegates/"
+        params = {"safe": safe_address}
+        response = requests.get(url, params=params)
+        data = self._handle_response(response)
+        results = data.get("results", [])
+        return [SafeDelegateResponse(**item) for item in results]
+
+    def add_delegate(
+        self,
+        safe_address: str,
+        delegate_address: str,
+        delegator: str,
+        label: str,
+        signature: str,
+    ) -> None:
+        """
+        Adds a delegate to a Safe.
+        """
+        url = f"{self.service_url}/v1/delegates/"
+        payload = {
+            "safe": safe_address,
+            "delegate": delegate_address,
+            "delegator": delegator,
+            "label": label,
+            "signature": signature,
+        }
+        response = requests.post(url, json=payload)
+        self._handle_response(response)
+
+    def remove_delegate(
+        self,
+        delegate_address: str,
+        delegator: str,
+        signature: str,
+    ) -> None:
+        """
+        Removes a delegate.
+        """
+        url = f"{self.service_url}/v1/delegates/{delegate_address}/"
+        payload = {
+            "delegator": delegator,
+            "signature": signature,
+        }
+        response = requests.delete(url, json=payload)
+        self._handle_response(response)
+
+    def get_tokens(self) -> list[SafeTokenResponse]:
+        """
+        Returns the list of ERC20 tokens supported by the Safe Transaction Service.
+        """
+        url = f"{self.service_url}/v1/tokens/"
+        response = requests.get(url)
+        data = self._handle_response(response)
+        results = data.get("results", [])
+        return [SafeTokenResponse(**item) for item in results]
+
+    def get_token(self, token_address: str) -> SafeTokenResponse:
+        """
+        Returns information about a specific token.
+        """
+        url = f"{self.service_url}/v1/tokens/{token_address}/"
+        response = requests.get(url)
+        data = self._handle_response(response)
+        return SafeTokenResponse(**data)
+
+    def decode_data(self, data: str) -> SafeDataDecoderResponse:
+        """
+        Decodes transaction data using the Safe Transaction Service.
+        """
+        url = f"{self.service_url}/v1/data-decoder/"
+        payload = {"data": data}
+        response = requests.post(url, json=payload)
+        data_json = self._handle_response(response)
+        return SafeDataDecoderResponse(**data_json)

safe_kit/types.py

@@ -0,0 +1,239 @@
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class SafeAccountConfig(BaseModel):
+    """
+    Configuration for deploying a new Safe.
+    """
+
+    owners: list[str]
+    threshold: int
+    to: str = "0x0000000000000000000000000000000000000000"
+    data: str = "0x"
+    fallback_handler: str = "0x0000000000000000000000000000000000000000"
+    payment_token: str = "0x0000000000000000000000000000000000000000"
+    payment: int = 0
+    payment_receiver: str = "0x0000000000000000000000000000000000000000"
+
+
+class SafeTransactionData(BaseModel):
+    """
+    Model representing the data of a Safe transaction.
+    """
+
+    to: str
+    value: int
+    data: str
+    operation: int = 0
+    safe_tx_gas: int = 0
+    base_gas: int = 0
+    gas_price: int = 0
+    gas_token: str = "0x0000000000000000000000000000000000000000"
+    refund_receiver: str = "0x0000000000000000000000000000000000000000"
+    nonce: int | None = None
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    def get_eip712_data(self, chain_id: int, safe_address: str) -> dict[str, Any]:
+        from hexbytes import HexBytes
+
+        return {
+            "types": {
+                "EIP712Domain": [
+                    {"name": "chainId", "type": "uint256"},
+                    {"name": "verifyingContract", "type": "address"},
+                ],
+                "SafeTx": [
+                    {"name": "to", "type": "address"},
+                    {"name": "value", "type": "uint256"},
+                    {"name": "data", "type": "bytes"},
+                    {"name": "operation", "type": "uint8"},
+                    {"name": "safeTxGas", "type": "uint256"},
+                    {"name": "baseGas", "type": "uint256"},
+                    {"name": "gasPrice", "type": "uint256"},
+                    {"name": "gasToken", "type": "address"},
+                    {"name": "refundReceiver", "type": "address"},
+                    {"name": "nonce", "type": "uint256"},
+                ],
+            },
+            "primaryType": "SafeTx",
+            "domain": {
+                "chainId": chain_id,
+                "verifyingContract": safe_address,
+            },
+            "message": {
+                "to": self.to,
+                "value": self.value,
+                "data": HexBytes(self.data),
+                "operation": self.operation,
+                "safeTxGas": self.safe_tx_gas,
+                "baseGas": self.base_gas,
+                "gasPrice": self.gas_price,
+                "gasToken": self.gas_token,
+                "refundReceiver": self.refund_receiver,
+                "nonce": self.nonce if self.nonce is not None else 0,
+            },
+        }
+
+
+class SafeTransaction(BaseModel):
+    """
+    Model representing a complete Safe transaction including signatures.
+    """
+
+    data: SafeTransactionData
+    signatures: dict[str, str] = Field(default_factory=dict)
+
+    def add_signature(self, owner: str, signature: str) -> None:
+        self.signatures[owner] = signature
+
+    @property
+    def sorted_signatures_bytes(self) -> bytes:
+        from hexbytes import HexBytes
+
+        # Sort by owner address
+        sorted_owners = sorted(self.signatures.keys(), key=lambda x: int(x, 16))
+        signature_bytes = b""
+        for owner in sorted_owners:
+            signature_bytes += HexBytes(self.signatures[owner])
+        return signature_bytes
+
+
+class SafeServiceInfo(BaseModel):
+    name: str
+    version: str
+    api_version: str
+    secure: bool
+    settings: dict[str, Any]
+
+
+class SafeMultisigTransactionResponse(BaseModel):
+    safe: str
+    to: str
+    value: str
+    data: str | None
+    operation: int
+    gas_token: str = Field(alias="gasToken")
+    safe_tx_gas: int = Field(alias="safeTxGas")
+    base_gas: int = Field(alias="baseGas")
+    gas_price: str = Field(alias="gasPrice")
+    refund_receiver: str = Field(alias="refundReceiver")
+    nonce: int
+    execution_date: str | None = Field(alias="executionDate")
+    submission_date: str = Field(alias="submissionDate")
+    modified: str
+    block_number: int | None = Field(alias="blockNumber")
+    transaction_hash: str | None = Field(alias="transactionHash")
+    safe_tx_hash: str = Field(alias="safeTxHash")
+    executor: str | None
+    is_executed: bool = Field(alias="isExecuted")
+    is_successful: bool | None = Field(alias="isSuccessful")
+    eth_gas_price: str | None = Field(alias="ethGasPrice")
+    max_fee_per_gas: str | None = Field(alias="maxFeePerGas")
+    max_priority_fee_per_gas: str | None = Field(alias="maxPriorityFeePerGas")
+    gas_used: int | None = Field(alias="gasUsed")
+    fee: str | None
+    origin: str | None
+    data_decoded: dict[str, Any] | None = Field(alias="dataDecoded")
+    confirmations_required: int = Field(alias="confirmationsRequired")
+    confirmations: list[dict[str, Any]] | None
+    trusted: bool
+    signatures: str | None
+
+
+class SafeBalanceResponse(BaseModel):
+    token_address: str | None = Field(alias="tokenAddress")
+    token: dict[str, Any] | None
+    balance: str
+
+
+class SafeIncomingTransactionResponse(BaseModel):
+    execution_date: str = Field(alias="executionDate")
+    transaction_hash: str = Field(alias="transactionHash")
+    to: str
+    value: str
+    token_address: str | None = Field(alias="tokenAddress")
+    from_: str = Field(alias="from")
+
+
+class SafeModuleTransactionResponse(BaseModel):
+    created: str
+    execution_date: str = Field(alias="executionDate")
+    block_number: int = Field(alias="blockNumber")
+    is_successful: bool = Field(alias="isSuccessful")
+    transaction_hash: str = Field(alias="transactionHash")
+    safe: str
+    module: str
+    to: str
+    value: str
+    data: str | None
+    operation: int
+    data_decoded: dict[str, Any] | None = Field(alias="dataDecoded")
+
+
+class SafeInfoResponse(BaseModel):
+    """Information about a Safe from the Transaction Service."""
+
+    address: str
+    nonce: int
+    threshold: int
+    owners: list[str]
+    master_copy: str = Field(alias="masterCopy")
+    modules: list[str]
+    fallback_handler: str = Field(alias="fallbackHandler")
+    guard: str
+    version: str | None
+
+
+class SafeCreationInfoResponse(BaseModel):
+    """Information about Safe creation."""
+
+    created: str
+    creator: str
+    transaction_hash: str = Field(alias="transactionHash")
+    factory_address: str = Field(alias="factoryAddress")
+    master_copy: str = Field(alias="masterCopy")
+    setup_data: str | None = Field(alias="setupData")
+
+
+class SafeCollectibleResponse(BaseModel):
+    """NFT/Collectible owned by a Safe."""
+
+    address: str
+    token_name: str = Field(alias="tokenName")
+    token_symbol: str = Field(alias="tokenSymbol")
+    logo_uri: str = Field(alias="logoUri")
+    id: str
+    uri: str | None
+    name: str | None
+    description: str | None
+    image_uri: str | None = Field(alias="imageUri")
+    metadata: dict[str, Any] | None
+
+
+class SafeDelegateResponse(BaseModel):
+    """Delegate for a Safe."""
+
+    safe: str | None
+    delegate: str
+    delegator: str
+    label: str
+
+
+class SafeTokenResponse(BaseModel):
+    """Information about a Token."""
+
+    address: str
+    name: str
+    symbol: str
+    decimals: int
+    logo_uri: str | None = Field(alias="logoUri")
+
+
+class SafeDataDecoderResponse(BaseModel):
+    """Decoded data from the Safe Transaction Service."""
+
+    method: str
+    parameters: list[dict[str, Any]] | None