safe-kit 0.0.11__py3-none-any.whl

safe_kit/errors.py

@@ -0,0 +1,57 @@
+class SafeKitError(Exception):
+    """Base exception for safe-kit"""
+
+    pass
+
+
+class SafeTransactionError(SafeKitError):
+    """Exception raised when a Safe transaction fails"""
+
+    def __init__(self, message: str, error_code: str | None = None):
+        self.error_code = error_code
+        super().__init__(f"{error_code}: {message}" if error_code else message)
+
+
+class SafeServiceError(SafeKitError):
+    """Exception raised when the Safe Transaction Service returns an error"""
+
+    def __init__(self, message: str, status_code: int | None = None):
+        self.status_code = status_code
+        super().__init__(f"Status {status_code}: {message}" if status_code else message)
+
+
+SAFE_ERRORS = {
+    "GS000": "Could not finish initialization",
+    "GS001": "Threshold needs to be defined",
+    "GS010": "Not enough gas to execute Safe transaction",
+    "GS011": "Could not pay gas costs with ether",
+    "GS012": "Could not pay gas costs with token",
+    "GS013": "Safe transaction failed when gasPrice and safeTxGas were 0",
+    "GS020": "Signatures data too short",
+    "GS021": "Invalid signature provided",
+    "GS022": "Invalid signature provided (duplicate)",
+    "GS023": "Invalid signature provided (not owner)",
+    "GS024": "Invalid signature provided (not sorted)",
+    "GS025": "Invalid signature provided (v is 0)",
+    "GS026": "Invalid signature provided (v > 30)",
+    "GS030": "Only owners can approve a hash",
+    "GS031": "Hash has already been approved",
+    "GS100": "Modules have already been initialized",
+    "GS130": "New owner cannot be the null address",
+}
+
+
+def handle_contract_error(e: Exception) -> Exception:
+    """
+    Parses a web3 exception and returns a more readable SafeKitError if possible.
+    """
+    error_str = str(e)
+
+    # Check for Safe error codes in the exception message
+    for code, message in SAFE_ERRORS.items():
+        if code in error_str:
+            return SafeTransactionError(message, error_code=code)
+
+    # If no specific Safe error is found, return the original exception
+    # or wrap it in a generic SafeKitError
+    return e

safe_kit/factory.py

@@ -0,0 +1,143 @@
+from typing import cast
+
+from hexbytes import HexBytes
+
+from safe_kit.abis import SAFE_PROXY_FACTORY_ABI
+from safe_kit.adapter import EthAdapter
+from safe_kit.contract_types import (
+    SafeProxyFactoryCreateChainSpecificProxyWithNonceParams,
+    SafeProxyFactoryCreateProxyWithNonceParams,
+)
+from safe_kit.errors import handle_contract_error
+from safe_kit.safe import Safe
+from safe_kit.types import SafeAccountConfig
+
+
+class SafeFactory:
+    """
+    Factory class to deploy new Safe contracts.
+    """
+
+    def __init__(
+        self,
+        eth_adapter: EthAdapter,
+        safe_singleton_address: str,
+        safe_proxy_factory_address: str,
+    ):
+        self.eth_adapter = eth_adapter
+        self.safe_singleton_address = safe_singleton_address
+        self.safe_proxy_factory_address = safe_proxy_factory_address
+        self.proxy_factory_contract = self.eth_adapter.get_contract(
+            address=safe_proxy_factory_address, abi=SAFE_PROXY_FACTORY_ABI
+        )
+
+    def _get_initializer_data(self, config: SafeAccountConfig) -> bytes:
+        safe_singleton = self.eth_adapter.get_safe_contract(self.safe_singleton_address)
+        return cast(
+            bytes,
+            safe_singleton.encodeABI(
+                fn_name="setup",
+                args=[
+                    config.owners,
+                    config.threshold,
+                    config.to,
+                    HexBytes(config.data),
+                    config.fallback_handler,
+                    config.payment_token,
+                    config.payment,
+                    config.payment_receiver,
+                ],
+            ),
+        )
+
+    def predict_safe_address(
+        self, config: SafeAccountConfig, salt_nonce: int = 0
+    ) -> str:
+        """
+        Predicts the address of the Safe that would be deployed with the given
+        configuration.
+        """
+        initializer = self._get_initializer_data(config)
+        params: SafeProxyFactoryCreateProxyWithNonceParams = {
+            "_singleton": self.safe_singleton_address,
+            "initializer": initializer,
+            "saltNonce": salt_nonce,
+        }
+        return cast(
+            str,
+            self.proxy_factory_contract.functions.createProxyWithNonce(**params).call(),
+        )
+
+    def predict_safe_address_v1_4_1(
+        self, config: SafeAccountConfig, salt_nonce: int = 0
+    ) -> str:
+        """
+        Predicts the address of the Safe (v1.4.1) that would be deployed.
+        Uses createChainSpecificProxyWithNonce.
+        """
+        initializer = self._get_initializer_data(config)
+        params: SafeProxyFactoryCreateChainSpecificProxyWithNonceParams = {
+            "_singleton": self.safe_singleton_address,
+            "initializer": initializer,
+            "saltNonce": salt_nonce,
+        }
+        return cast(
+            str,
+            self.proxy_factory_contract.functions.createChainSpecificProxyWithNonce(
+                **params
+            ).call(),
+        )
+
+    def deploy_safe(self, config: SafeAccountConfig, salt_nonce: int = 0) -> Safe:
+        """
+        Deploys a new Safe contract.
+        Returns a Safe instance with the predicted address.
+        """
+        signer = self.eth_adapter.get_signer_address()
+        if not signer:
+            raise ValueError("No signer configured in the adapter")
+
+        initializer = self._get_initializer_data(config)
+        safe_address = self.predict_safe_address(config, salt_nonce)
+
+        try:
+            params: SafeProxyFactoryCreateProxyWithNonceParams = {
+                "_singleton": self.safe_singleton_address,
+                "initializer": initializer,
+                "saltNonce": salt_nonce,
+            }
+            self.proxy_factory_contract.functions.createProxyWithNonce(
+                **params
+            ).transact({"from": signer})
+        except Exception as e:
+            raise handle_contract_error(e) from e
+
+        return Safe(self.eth_adapter, safe_address)
+
+    def deploy_safe_v1_4_1(
+        self, config: SafeAccountConfig, salt_nonce: int = 0
+    ) -> Safe:
+        """
+        Deploys a new Safe contract (v1.4.1).
+        Returns a Safe instance with the predicted address.
+        """
+        signer = self.eth_adapter.get_signer_address()
+        if not signer:
+            raise ValueError("No signer configured in the adapter")
+
+        initializer = self._get_initializer_data(config)
+        safe_address = self.predict_safe_address_v1_4_1(config, salt_nonce)
+
+        try:
+            params: SafeProxyFactoryCreateChainSpecificProxyWithNonceParams = {
+                "_singleton": self.safe_singleton_address,
+                "initializer": initializer,
+                "saltNonce": salt_nonce,
+            }
+            self.proxy_factory_contract.functions.createChainSpecificProxyWithNonce(
+                **params
+            ).transact({"from": signer})
+        except Exception as e:
+            raise handle_contract_error(e) from e
+
+        return Safe(self.eth_adapter, safe_address)

safe_kit/managers/__init__.py

@@ -0,0 +1,15 @@
+"""
+Safe manager mixins for modular functionality.
+"""
+
+from safe_kit.managers.guard_manager import GuardManagerMixin
+from safe_kit.managers.module_manager import ModuleManagerMixin
+from safe_kit.managers.owner_manager import OwnerManagerMixin
+from safe_kit.managers.token_manager import TokenManagerMixin
+
+__all__ = [
+    "OwnerManagerMixin",
+    "ModuleManagerMixin",
+    "TokenManagerMixin",
+    "GuardManagerMixin",
+]

safe_kit/managers/guard_manager.py

@@ -0,0 +1,61 @@
+"""
+Guard and fallback handler management functionality for Safe.
+"""
+
+from typing import TYPE_CHECKING
+
+from safe_kit.types import SafeTransaction, SafeTransactionData
+
+if TYPE_CHECKING:
+    from safe_kit.safe import Safe
+
+
+class GuardManagerMixin:
+    """
+    Mixin class providing guard and fallback handler management functionality.
+    """
+
+    def get_guard(self: "Safe") -> str:  # type: ignore[misc]
+        """
+        Returns the guard address of the Safe.
+        """
+        # keccak256("guard_manager.guard.address")
+        slot = 0x4A204F620C8C5CCDCA3FD54D003B6D13435454A733A569F8E4A6426EA62BF7A0
+        data = self.eth_adapter.get_storage_at(self.safe_address, slot)
+        # Convert bytes to address (last 20 bytes)
+        return "0x" + data.hex()[-40:]
+
+    def create_set_guard_transaction(  # type: ignore[misc]
+        self: "Safe", guard_address: str
+    ) -> SafeTransaction:
+        """
+        Creates a transaction to set the guard of the Safe.
+        """
+        data = self.contract.encodeABI(fn_name="setGuard", args=[guard_address])
+
+        return self.create_transaction(
+            SafeTransactionData(to=self.safe_address, value=0, data=data, operation=0)
+        )
+
+    def get_fallback_handler(self: "Safe") -> str:  # type: ignore[misc]
+        """
+        Returns the fallback handler address of the Safe.
+        """
+        # keccak256("fallback_manager.handler.address")
+        slot = 0x6C9A6C4A39284E37ED1CF53D337577D14212A4870FB976A4366C693B939918D5
+        data = self.eth_adapter.get_storage_at(self.safe_address, slot)
+        return "0x" + data.hex()[-40:]
+
+    def create_set_fallback_handler_transaction(  # type: ignore[misc]
+        self: "Safe", handler_address: str
+    ) -> SafeTransaction:
+        """
+        Creates a transaction to set the fallback handler of the Safe.
+        """
+        data = self.contract.encodeABI(
+            fn_name="setFallbackHandler", args=[handler_address]
+        )
+
+        return self.create_transaction(
+            SafeTransactionData(to=self.safe_address, value=0, data=data, operation=0)
+        )

safe_kit/managers/module_manager.py

@@ -0,0 +1,85 @@
+"""
+Module management functionality for Safe.
+"""
+
+from typing import TYPE_CHECKING, cast
+
+from safe_kit.types import SafeTransaction, SafeTransactionData
+
+if TYPE_CHECKING:
+    from safe_kit.safe import Safe
+
+
+class ModuleManagerMixin:
+    """
+    Mixin class providing module management functionality.
+    """
+
+    def get_modules(self: "Safe") -> list[str]:  # type: ignore[misc]
+        """
+        Returns the modules enabled on the Safe.
+        """
+        # Sentinel address for modules
+        start = "0x0000000000000000000000000000000000000001"
+        page_size = 10
+        modules = []
+
+        while True:
+            array, next_module = self.contract.functions.getModulesPaginated(
+                start, page_size
+            ).call()
+            modules.extend(array)
+
+            if (
+                next_module == "0x0000000000000000000000000000000000000001"
+                or next_module == "0x0000000000000000000000000000000000000000"
+            ):
+                break
+            start = next_module
+
+        return modules
+
+    def is_module_enabled(self: "Safe", module_address: str) -> bool:  # type: ignore[misc]
+        """
+        Checks if a module is enabled on the Safe.
+        """
+        return cast(
+            bool, self.contract.functions.isModuleEnabled(module_address).call()
+        )
+
+    def create_enable_module_transaction(  # type: ignore[misc]
+        self: "Safe", module_address: str
+    ) -> SafeTransaction:
+        """
+        Creates a transaction to enable a Safe module.
+        """
+        data = self.contract.encodeABI(fn_name="enableModule", args=[module_address])
+
+        return self.create_transaction(
+            SafeTransactionData(to=self.safe_address, value=0, data=data, operation=0)
+        )
+
+    def create_disable_module_transaction(  # type: ignore[misc]
+        self: "Safe", module_address: str
+    ) -> SafeTransaction:
+        """
+        Creates a transaction to disable a Safe module.
+        """
+        modules = self.get_modules()
+        try:
+            index = modules.index(module_address)
+        except ValueError:
+            raise ValueError(f"Module {module_address} is not enabled") from None
+
+        if index == 0:
+            prev_module = "0x0000000000000000000000000000000000000001"
+        else:
+            prev_module = modules[index - 1]
+
+        data = self.contract.encodeABI(
+            fn_name="disableModule", args=[prev_module, module_address]
+        )
+
+        return self.create_transaction(
+            SafeTransactionData(to=self.safe_address, value=0, data=data, operation=0)
+        )

safe_kit/managers/owner_manager.py

@@ -0,0 +1,94 @@
+"""
+Owner management functionality for Safe.
+"""
+
+from typing import TYPE_CHECKING
+
+from safe_kit.types import SafeTransaction, SafeTransactionData
+
+if TYPE_CHECKING:
+    from safe_kit.safe import Safe
+
+
+class OwnerManagerMixin:
+    """
+    Mixin class providing owner management functionality.
+    """
+
+    def _get_previous_owner(self: "Safe", owner: str) -> str:  # type: ignore[misc]
+        """
+        Get the previous owner in the linked list for removal/swap operations.
+        """
+        owners = self.get_owners()
+        try:
+            index = owners.index(owner)
+        except ValueError:
+            raise ValueError(f"Address {owner} is not an owner") from None
+
+        if index == 0:
+            return "0x0000000000000000000000000000000000000001"  # Sentinel
+        return owners[index - 1]
+
+    def create_add_owner_transaction(  # type: ignore[misc]
+        self: "Safe", owner: str, threshold: int | None = None
+    ) -> SafeTransaction:
+        """
+        Creates a transaction to add a new owner to the Safe.
+        """
+        if threshold is None:
+            threshold = self.get_threshold()
+
+        data = self.contract.encodeABI(
+            fn_name="addOwnerWithThreshold", args=[owner, threshold]
+        )
+
+        return self.create_transaction(
+            SafeTransactionData(to=self.safe_address, value=0, data=data, operation=0)
+        )
+
+    def create_remove_owner_transaction(  # type: ignore[misc]
+        self: "Safe", owner: str, threshold: int | None = None
+    ) -> SafeTransaction:
+        """
+        Creates a transaction to remove an owner from the Safe.
+        """
+        if threshold is None:
+            threshold = self.get_threshold()
+
+        prev_owner = self._get_previous_owner(owner)
+
+        data = self.contract.encodeABI(
+            fn_name="removeOwner", args=[prev_owner, owner, threshold]
+        )
+
+        return self.create_transaction(
+            SafeTransactionData(to=self.safe_address, value=0, data=data, operation=0)
+        )
+
+    def create_swap_owner_transaction(  # type: ignore[misc]
+        self: "Safe", old_owner: str, new_owner: str
+    ) -> SafeTransaction:
+        """
+        Creates a transaction to replace an existing owner with a new one.
+        """
+        prev_owner = self._get_previous_owner(old_owner)
+
+        data = self.contract.encodeABI(
+            fn_name="swapOwner", args=[prev_owner, old_owner, new_owner]
+        )
+
+        return self.create_transaction(
+            SafeTransactionData(to=self.safe_address, value=0, data=data, operation=0)
+        )
+
+    def create_change_threshold_transaction(  # type: ignore[misc]
+        self: "Safe", threshold: int
+    ) -> SafeTransaction:
+        """
+        Creates a transaction to change the threshold of the Safe.
+        """
+        data = self.contract.encodeABI(fn_name="changeThreshold", args=[threshold])
+
+        return self.create_transaction(
+            SafeTransactionData(to=self.safe_address, value=0, data=data, operation=0)
+        )

safe_kit/managers/token_manager.py

@@ -0,0 +1,100 @@
+"""
+Token transfer functionality for Safe.
+"""
+
+from typing import TYPE_CHECKING
+
+from safe_kit.types import SafeTransaction, SafeTransactionData
+
+if TYPE_CHECKING:
+    from safe_kit.safe import Safe
+
+
+class TokenManagerMixin:
+    """
+    Mixin class providing token transfer functionality.
+    """
+
+    def create_erc20_transfer_transaction(  # type: ignore[misc]
+        self: "Safe", token_address: str, to: str, amount: int
+    ) -> SafeTransaction:
+        """
+        Creates a transaction to transfer ERC20 tokens.
+        """
+        from safe_kit.abis import ERC20_ABI
+
+        token_contract = self.eth_adapter.get_contract(token_address, ERC20_ABI)
+
+        data = token_contract.encodeABI(fn_name="transfer", args=[to, amount])
+
+        return self.create_transaction(
+            SafeTransactionData(to=token_address, value=0, data=data, operation=0)
+        )
+
+    def create_erc721_transfer_transaction(  # type: ignore[misc]
+        self: "Safe", token_address: str, to: str, token_id: int
+    ) -> SafeTransaction:
+        """
+        Creates a transaction to transfer ERC721 tokens.
+        """
+        from safe_kit.abis import ERC721_ABI
+
+        token_contract = self.eth_adapter.get_contract(token_address, ERC721_ABI)
+
+        data = token_contract.encodeABI(
+            fn_name="safeTransferFrom", args=[self.safe_address, to, token_id]
+        )
+
+        return self.create_transaction(
+            SafeTransactionData(to=token_address, value=0, data=data, operation=0)
+        )
+
+    def create_native_transfer_transaction(  # type: ignore[misc]
+        self: "Safe", to: str, amount: int
+    ) -> SafeTransaction:
+        """
+        Creates a transaction to transfer native tokens (ETH).
+        """
+        return self.create_transaction(
+            SafeTransactionData(to=to, value=amount, data="0x", operation=0)
+        )
+
+    def create_rejection_transaction(self: "Safe", nonce: int) -> SafeTransaction:  # type: ignore[misc]
+        """
+        Creates a transaction to reject a pending transaction (by reusing the nonce).
+        """
+        return self.create_transaction(
+            SafeTransactionData(
+                to=self.safe_address, value=0, data="0x", operation=0, nonce=nonce
+            )
+        )
+
+    def create_multi_send_transaction(  # type: ignore[misc]
+        self: "Safe",
+        transactions: list[SafeTransactionData],
+        multi_send_address: str,
+    ) -> SafeTransaction:
+        """
+        Creates a MultiSend transaction.
+        """
+        from safe_kit.abis import MULTI_SEND_ABI
+        from safe_kit.multisend import MultiSend
+
+        encoded_txs = MultiSend.encode_transactions(transactions)
+
+        multi_send_contract = self.eth_adapter.get_contract(
+            multi_send_address, MULTI_SEND_ABI
+        )
+
+        data = multi_send_contract.encodeABI(fn_name="multiSend", args=[encoded_txs])
+
+        # MultiSend transactions are DelegateCalls (operation=1)
+        # to the MultiSend contract
+        return self.create_transaction(
+            SafeTransactionData(
+                to=multi_send_address,
+                value=0,
+                data=data,
+                operation=1,  # DelegateCall
+            )
+        )

safe_kit/multisend.py

@@ -0,0 +1,41 @@
+from hexbytes import HexBytes
+
+from safe_kit.types import SafeTransactionData
+
+
+class MultiSend:
+    """
+    Utilities for encoding MultiSend transactions.
+    """
+
+    @staticmethod
+    def encode_transactions(transactions: list[SafeTransactionData]) -> bytes:
+        """
+        Encodes a list of SafeTransactionData into a single byte string
+        compatible with the MultiSend contract.
+
+        Format:
+        operation (1 byte) + to (20 bytes) + value (32 bytes) +
+        data_length (32 bytes) + data (bytes)
+        """
+        encoded_data = b""
+        for tx in transactions:
+            # operation: 1 byte
+            operation = int(tx.operation).to_bytes(1, byteorder="big")
+
+            # to: 20 bytes
+            # Ensure it's bytes and 20 bytes long
+            to_address = HexBytes(tx.to)
+            if len(to_address) != 20:
+                raise ValueError(f"Invalid address length for {tx.to}")
+
+            # value: 32 bytes
+            value = int(tx.value).to_bytes(32, byteorder="big")
+
+            # data
+            data = HexBytes(tx.data)
+            data_length = len(data).to_bytes(32, byteorder="big")
+
+            encoded_data += operation + to_address + value + data_length + data
+
+        return encoded_data