safe_eth.safe package

Subpackages

Submodules

safe_eth.safe.addresses module

Contains information about Safe contract addresses deployed in every chain

Every entry contains a tuple with address, deployment block number and version

safe_eth.safe.addresses.get_default_addresses_with_version(filter_contract_names: List | None = None) → List[Tuple[ChecksumAddress, str]]

Get the default addresses and versions from contract names. The version is the extended one with L2 in case of L2 contract.

Returns:: list of Safe deployment contract addresses with version

safe_eth.safe.constants module

safe_eth.safe.enums module

class safe_eth.safe.enums.SafeOperationEnum(value)

Bases: IntEnum

CALL = 0

CREATE = 2

DELEGATE_CALL = 1

safe_eth.safe.exceptions module

exception safe_eth.safe.exceptions.CannotEstimateGas: Bases: SafeServiceException

exception safe_eth.safe.exceptions.CannotRetrieveSafeInfoException: Bases: SafeServiceException

exception safe_eth.safe.exceptions.CouldNotFinishInitialization: Bases: InvalidMultisigTx

exception safe_eth.safe.exceptions.CouldNotPayGasWithEther: Bases: InvalidMultisigTx

exception safe_eth.safe.exceptions.CouldNotPayGasWithToken: Bases: InvalidMultisigTx

exception safe_eth.safe.exceptions.HashHasNotBeenApproved: Bases: InvalidMultisigTx

exception safe_eth.safe.exceptions.InvalidChecksumAddress: Bases: SafeServiceException

exception safe_eth.safe.exceptions.InvalidContractSignatureLocation: Bases: InvalidMultisigTx

exception safe_eth.safe.exceptions.InvalidERC20Token: Bases: Exception

exception safe_eth.safe.exceptions.InvalidInternalTx: Bases: InvalidMultisigTx

exception safe_eth.safe.exceptions.InvalidMultisigTx: Bases: SafeServiceException

exception safe_eth.safe.exceptions.InvalidOwnerProvided: Bases: InvalidMultisigTx

exception safe_eth.safe.exceptions.InvalidPaymentToken: Bases: SafeServiceException

exception safe_eth.safe.exceptions.InvalidSignaturesProvided: Bases: InvalidMultisigTx

exception safe_eth.safe.exceptions.MethodCanOnlyBeCalledFromThisContract: Bases: InvalidMultisigTx

exception safe_eth.safe.exceptions.ModuleManagerException: Bases: InvalidMultisigTx

exception safe_eth.safe.exceptions.NotEnoughSafeTransactionGas: Bases: InvalidMultisigTx

exception safe_eth.safe.exceptions.OnlyOwnersCanApproveAHash: Bases: InvalidMultisigTx

exception safe_eth.safe.exceptions.OwnerManagerException: Bases: InvalidMultisigTx

exception safe_eth.safe.exceptions.SafeServiceException: Bases: Exception

exception safe_eth.safe.exceptions.SafeTransactionFailedWhenGasPriceAndSafeTxGasEmpty: Bases: InvalidMultisigTx

exception safe_eth.safe.exceptions.SignatureNotProvidedByOwner: Bases: InvalidMultisigTx

exception safe_eth.safe.exceptions.SignaturesDataTooShort: Bases: InvalidMultisigTx

exception safe_eth.safe.exceptions.ThresholdNeedsToBeDefined: Bases: InvalidMultisigTx

safe_eth.safe.multi_send module

class safe_eth.safe.multi_send.MultiSend(ethereum_client: EthereumClient | None = None, address: ChecksumAddress | None = None, call_only: bool = True)

Bases: object

MULTISEND_ADDRESSES = ('0x218543288004CD07832472D464648173c77D7eB7', '0x38869bf66a61cF6bDB996A6aE40D5853Fd43B526', '0xA238CBeb142c10Ef7Ad8442C6D1f9E89e07e7761', '0x998739BFdAAdde7C933B942a68053933098f9EDa')

MULTISEND_CALL_ONLY_ADDRESSES = ('0xA83c336B20401Af773B6219BA5027174338D1836', '0x9641d764fc13c8B624c04430C7356C1C7C8102e2', '0x40A2aCCbd92BCA938b02010E17A5b8929b49130D', '0xA1dabEF33b3B82c7814B6D82A79e50F4AC44102B')

build_tx(multi_send_txs: List[MultiSendTx], tx_params: TxParams | None = None) → TxParams

Txs don’t need to be valid to get through

Parameters:

multi_send_txs
tx_params

Returns:

build_tx_data(multi_send_txs: List[MultiSendTx]) → HexBytes

Txs don’t need to be valid to get through

Parameters:: multi_send_txs
Returns:

static deploy_contract(ethereum_client: EthereumClient, deployer_account: LocalAccount) → EthereumTxSent

Deploy proxy factory contract

Parameters:

ethereum_client
deployer_account – Ethereum Account

Returns:

EthereumTxSent with the deployed contract address

dummy_w3 = <web3.main.Web3 object>

classmethod from_bytes(encoded_multisend_txs: str | bytes) → List[MultiSendTx]

Decodes one or more multisend transactions from bytes transactions (Abi decoded)

Parameters:: encoded_multisend_txs
Returns:: List of MultiSendTxs

classmethod from_transaction_data(multisend_data: str | bytes) → List[MultiSendTx]

Decodes multisend transactions from transaction data (ABI encoded with selector)

Returns:

get_contract()

property w3

class safe_eth.safe.multi_send.MultiSendOperation(value)

Bases: Enum

CALL = 0

DELEGATE_CALL = 1

class safe_eth.safe.multi_send.MultiSendTx(operation: MultiSendOperation, to: ChecksumAddress, value: int, data: bytes | HexStr, old_encoding: bool = False)

Bases: object

Wrapper for a single MultiSendTx

property data_length: int

property encoded_data

classmethod from_bytes(encoded_multisend_tx: str | bytes) → MultiSendTx: Decoded one MultiSend transaction. ABI must be used to get the transactions parameter and use that data for this function :param encoded_multisend_tx: :return:

safe_eth.safe.proxy_factory module

class safe_eth.safe.proxy_factory.ProxyFactory(*args, version: str = '1.5.0', **kwargs)

Bases: ContractBase

calculate_proxy_address(master_copy: ChecksumAddress, initializer: bytes, salt_nonce: int, chain_specific: bool = False) → ChecksumAddress

Calculate proxy address for calling deploy_proxy_contract_with_nonce

Parameters:

master_copy
initializer
salt_nonce
chain_specific – Calculate chain specific address (to prevent same address in other chains)

Returns:

check_proxy_code(address: ChecksumAddress) → bool

Check if proxy bytecode matches any of the deployed by the supported Proxy Factories

Parameters:: address – Ethereum address to check
Returns:: True if proxy is valid, False otherwise

classmethod deploy_contract(ethereum_client: EthereumClient, deployer_account: LocalAccount) → EthereumTxSent

Deploy Proxy Factory contract

Parameters:

ethereum_client
deployer_account – Ethereum Account

Returns:

EthereumTxSent with the deployed contract address

deploy_proxy_contract(deployer_account: LocalAccount, master_copy: ChecksumAddress, initializer: bytes = b'', gas: int | None = None, gas_price: int | None = None, nonce: int | None = None) → EthereumTxSent

Deploy proxy contract via ProxyFactory using createProxy function (CREATE opcode)

Parameters:

deployer_account – Ethereum account
master_copy – Address the proxy will point at
initializer – Initializer for the deployed proxy
gas – Gas
gas_price – Gas Price
nonce – Nonce

Returns:

EthereumTxSent

deploy_proxy_contract_with_nonce(deployer_account: LocalAccount, master_copy: ChecksumAddress, initializer: bytes = b'', salt_nonce: int | None = None, gas: int | None = None, gas_price: int | None = None, nonce: int | None = None, chain_specific: bool = False, is_l2: bool = False) → EthereumTxSent

Deploy proxy contract via Proxy Factory using createProxyWithNonce (CREATE2 opcode)

Parameters:

deployer_account – Ethereum account
master_copy – Address the proxy will point at
initializer – Initializer for the deployed proxy
salt_nonce – Uint256 for CREATE2 salt. If not provided, a random one will be used
gas – Gas
gas_price – Gas Price
nonce – Nonce
chain_specific – Calculate chain specific address (to prevent same address in other chains)
is_l2 – L2 deployment function

Returns:

EthereumTxSent

static detect_version_from_address(factory_address: ChecksumAddress) → str

Detect ProxyFactory version from a deployed address.

Parameters:: factory_address – The address of the ProxyFactory contract
Returns:: Version string (e.g., “1.5.0”)
Raises:: ValueError – If factory address is not found in safe_deployments

classmethod from_address(factory_address: ChecksumAddress, ethereum_client: EthereumClient) → ProxyFactory

Create a ProxyFactory instance from a deployed factory address. Automatically detects the correct version based on the address.

Parameters:

factory_address – The address of the deployed ProxyFactory contract
ethereum_client – Ethereum client instance

Returns:

ProxyFactory instance of the appropriate version (e.g., ProxyFactoryV141, ProxyFactoryV150)

Raises:

ValueError – If factory address is not found in safe_deployments

get_deploy_function(chain_specific: bool, is_l2: bool = False) → ContractFunction

get_proxy_creation_code() → bytes

Returns:: Creation code used for the Proxy deployment. With this it is easily possible to calculate predicted address.

get_proxy_runtime_code() → bytes

Returns:: Runtime code of a deployed Proxy. For v1.4.1 onwards the method is not available, so None will be returned

class safe_eth.safe.proxy_factory.ProxyFactoryCompatibilityAdapter(*args, version: str = '1.5.0', **kwargs)

Bases: ProxyFactory, ABC

Adapter for Safe Proxy Factory contracts v1.4.1 and later. Overrides some methods to handle API changes in newer contract versions.

deploy_proxy_contract(*args, **kwargs)

Deprecated since version ``createProxy``: function was deprecated in v1.4.1, use deploy_proxy_contract_with_nonce

Parameters:

args
kwargs

Returns:

get_proxy_runtime_code() → bytes

Returns:: From v1.4.1 onwards the method is not available
Raises:: NotImplementedError

class safe_eth.safe.proxy_factory.ProxyFactoryV100(*args, version: str = '1.5.0', **kwargs)

Bases: ProxyFactory

get_contract_fn() → Callable[[Web3, ChecksumAddress | None], Contract]

Returns:: Contract function to get the proper contract

class safe_eth.safe.proxy_factory.ProxyFactoryV111(*args, version: str = '1.5.0', **kwargs)

Bases: ProxyFactory

get_contract_fn() → Callable[[Web3, ChecksumAddress | None], Contract]

Returns:: Contract function to get the proper contract

class safe_eth.safe.proxy_factory.ProxyFactoryV130(*args, version: str = '1.5.0', **kwargs)

Bases: ProxyFactory

get_contract_fn() → Callable[[Web3, ChecksumAddress | None], Contract]

Returns:: Contract function to get the proper contract

class safe_eth.safe.proxy_factory.ProxyFactoryV141(*args, version: str = '1.5.0', **kwargs)

Bases: ProxyFactoryCompatibilityAdapter

get_contract_fn() → Callable[[Web3, ChecksumAddress | None], Contract]

Returns:: Contract function to get the proper contract

get_deploy_function(chain_specific: bool, is_l2: bool = False) → ContractFunction

class safe_eth.safe.proxy_factory.ProxyFactoryV150(*args, version: str = '1.5.0', **kwargs)

Bases: ProxyFactoryCompatibilityAdapter

get_contract_fn() → Callable[[Web3, ChecksumAddress | None], Contract]

Returns:: Contract function to get the proper contract

get_deploy_function(chain_specific: bool, is_l2: bool = False) → ContractFunction

safe_eth.safe.safe module

class safe_eth.safe.safe.Safe(address: ChecksumAddress, ethereum_client: EthereumClient, version: str | None = None, *args, **kwargs)

Bases: SafeCreator, ContractBase

Collection of methods and utilities to handle a Safe

FALLBACK_HANDLER_STORAGE_SLOT = 49122629484629529244014240937346711770925847994644146912111677022347558721749

MODULE_GUARD_STORAGE_SLOT = 80067992571439485785405894129641280630172609254213753706009264638304931322183

SAFE_MESSAGE_TYPEHASH = b'`\xb3\xcb\xf8\xb4\xa2#\xd6\x8dd\x1b;m\xdf\x9a)\x8e\x7f3q\x0c\xf3\xd3\xa9\xd1\x14kZaP\xfb\xca'

TRANSACTION_GUARD_STORAGE_SLOT = 33528237782592280163068556224972516439282563014722366175641814928123294921928

classmethod available_versions() → List[str]

Helpful utility for tooling that needs to know which Safe versions are bundled.

Returns:: List of semantic versions, sorted ascending.

build_multisig_tx(to: ChecksumAddress, value: int, data: bytes, operation: SafeOperationEnum | int = 0, safe_tx_gas: int = 0, base_gas: int = 0, gas_price: int = 0, gas_token: ChecksumAddress = '0x0000000000000000000000000000000000000000', refund_receiver: ChecksumAddress = '0x0000000000000000000000000000000000000000', signatures: bytes = b'', safe_nonce: int | None = None) → SafeTx

Allows to execute a Safe transaction confirmed by required number of owners and then pays the account that submitted the transaction. The fees are always transferred, even if the user transaction fails

Parameters:

to – Destination address of Safe transaction
value – Ether value of Safe transaction
data – Data payload of Safe transaction
operation – Operation type (SafeOperationEnum or matching integer value)
safe_tx_gas – Gas that should be used for the Safe transaction
base_gas – Gas costs for that are independent of the transaction execution (e.g. base transaction fee, signature check, payment of the refund)
gas_price – Gas price that should be used for the payment calculation
gas_token – Token address (or 0x000..000 if ETH) that is used for the payment
refund_receiver – Address of receiver of gas payment (or 0x000..000 if tx.origin).
signatures – Packed signature data ({bytes32 r}{bytes32 s}{uint8 v})
safe_nonce – Nonce of the safe (to calculate hash)

Returns:

SafeTx

property chain_id: int

check_funds_for_tx_gas(safe_tx_gas: int, base_gas: int, gas_price: int, gas_token: str) → bool

Check safe has enough funds to pay for a tx

Parameters:

safe_tx_gas – Safe tx gas
base_gas – Data gas
gas_price – Gas Price
gas_token – Gas Token, to use token instead of ether for the gas

Returns:

True if enough funds, False otherwise

classmethod deploy_contract(ethereum_client: EthereumClient, deployer_account: LocalAccount) → EthereumTxSent

Deploy master contract. Takes deployer_account (if unlocked in the node) or the deployer private key Safe with version > v1.1.1 doesn’t need to be initialized as it already has a constructor

Parameters:

ethereum_client
deployer_account – Ethereum account

Returns:

EthereumTxSent with the deployed contract address

Return the Safe semantic version reported by the contract. None is returned if the read fails.

Parameters:

address – Safe proxy address
ethereum_client – Client wrapper used to interact with the node
block_identifier – Optional block identifier for the call

Returns:

Semantic version string or None if it cannot be detected

property domain_separator: bytes | None

Returns:: EIP721 DomainSeparator for the Safe. Returns None if not supported (for Safes < 1.0.0)

estimate_tx_base_gas(to: ChecksumAddress, value: int, data: bytes, operation: SafeOperationEnum | int, gas_token: ChecksumAddress, estimated_tx_gas: int) → int

Calculate gas costs that are independent of the transaction execution(e.g. base transaction fee, signature check, payment of the refund…)

Parameters:

to
value
data
operation
gas_token
estimated_tx_gas – gas calculated with estimate_tx_gas

Returns:

estimate_tx_gas(to: ChecksumAddress, value: int, data: bytes, operation: SafeOperationEnum | int) → int

Estimate tx gas. Use requiredTxGas on the Safe contract and fallbacks to eth_estimateGas if that method fails. Note: eth_estimateGas cannot estimate delegate calls

Parameters:

to
value
data
operation

Returns:

Estimated gas for Safe inner tx

Raises:

CannotEstimateGas

estimate_tx_gas_by_trying(to: ChecksumAddress, value: int, data: bytes | str, operation: SafeOperationEnum | int) → int

Try to get an estimation with Safe’s requiredTxGas. If estimation is successful, try to set a gas limit and estimate again. If gas estimation is ok, same gas estimation should be returned, if it’s less than required estimation will not be completed, so estimation was not accurate and gas limit needs to be increased.

Parameters:

to
value
data
operation

Returns:

Estimated gas calling requiredTxGas setting a gas limit and checking if eth_call is successful

Raises:

CannotEstimateGas

Estimate tx gas using safe requiredTxGas method

Returns:: int: Estimated gas
Raises:: CannotEstimateGas: If gas cannot be estimated
Raises:: ValueError: Cannot decode received data

estimate_tx_gas_with_web3(to: ChecksumAddress, value: int, data: bytes | HexStr) → int

Parameters:

to
value
data

Returns:

Estimation using web3 estimate_gas

classmethod from_version(version: str, address: ChecksumAddress, ethereum_client: EthereumClient, *args, **kwargs) → Safe

Build a Safe without querying the chain for VERSION(). Existing call sites keep working but integrators that already know the version can bypass the RPC lookup.

Parameters:

version – Semantic version to instantiate
address – Safe proxy address
ethereum_client – Client wrapper used to interact with the node
args – Extra args forwarded to the concrete Safe class
kwargs – Extra kwargs forwarded to the concrete Safe class

Returns:

Instance of the requested Safe subclass

get_message_hash(message: str | bytes) → Hash32

Return hash of a message that can be signed by owners.

Parameters:: message – Message that should be hashed. A Hash32 must be provided for EIP191 or EIP712 messages
Returns:: Message hash

get_message_hash_and_preimage(message: str | bytes) → tuple[Hash32, bytes]

Return hash of a message and its preimage that can be signed by owners.

Parameters:: message – Message that should be hashed. A Hash32 must be provided for EIP191 or EIP712 messages
Returns:: Tuple of message hash and preimage for the provided message

get_message_preimage(message: str | bytes) → bytes

Return preimage for a message that can be signed by owners.

Parameters:: message – Message that should be hashed. A Hash32 must be provided for EIP191 or EIP712 messages
Returns:: Preimage for the provided message

abstractmethod get_version() → str

Returns:: String with Safe Master Copy semantic version, must match retrieve_version()

Get all Safe info in the same batch call.

Parameters:: block_identifier
Returns:
Raises:: CannotRetrieveSafeInfoException

retrieve_code() → HexBytes

retrieve_domain_separator(block_identifier: Literal['latest', 'earliest', 'pending', 'safe', 'finalized'] | BlockNumber | Hash32 | HexStr | HexBytes | int | None = 'latest') → bytes | None

retrieve_fallback_handler(block_identifier: Literal['latest', 'earliest', 'pending', 'safe', 'finalized'] | BlockNumber | Hash32 | HexStr | HexBytes | int | None = 'latest') → ChecksumAddress

retrieve_is_hash_approved(owner: ChecksumAddress, safe_hash: bytes, block_identifier: Literal['latest', 'earliest', 'pending', 'safe', 'finalized'] | BlockNumber | Hash32 | HexStr | HexBytes | int | None = 'latest') → bool

retrieve_is_message_signed(message_hash: Hash32, block_identifier: Literal['latest', 'earliest', 'pending', 'safe', 'finalized'] | BlockNumber | Hash32 | HexStr | HexBytes | int | None = 'latest') → bool

retrieve_is_owner(owner: ChecksumAddress, block_identifier: Literal['latest', 'earliest', 'pending', 'safe', 'finalized'] | BlockNumber | Hash32 | HexStr | HexBytes | int | None = 'latest') → bool

Parameters:: block_identifier
Returns:: Returns the implementation address. Multiple types of proxies are supported

Retrieve the module guard address from storage. Module guard was introduced in Safe v1.5.0.

Parameters:: block_identifier
Returns:: Module guard address or NULL_ADDRESS if not set

Get modules enabled on the Safe From v1.1.1:

getModulesPaginated is available

getModules returns only 10 modules

Parameters:

pagination – Number of modules to get per request
max_modules_to_retrieve – Maximum number of modules to retrieve
block_identifier

Returns:

List of module addresses

retrieve_nonce(block_identifier: Literal['latest', 'earliest', 'pending', 'safe', 'finalized'] | BlockNumber | Hash32 | HexStr | HexBytes | int | None = 'latest') → int

retrieve_owners(block_identifier: Literal['latest', 'earliest', 'pending', 'safe', 'finalized'] | BlockNumber | Hash32 | HexStr | HexBytes | int | None = 'latest') → List[ChecksumAddress]

retrieve_threshold(block_identifier: Literal['latest', 'earliest', 'pending', 'safe', 'finalized'] | BlockNumber | Hash32 | HexStr | HexBytes | int | None = 'latest') → int

Retrieve the transaction guard address from storage. Transaction guard (previously just “guard”) was implemented in v1.1.1.

Parameters:: block_identifier
Returns:: Transaction guard address or NULL_ADDRESS if not set

retrieve_version(block_identifier: Literal['latest', 'earliest', 'pending', 'safe', 'finalized'] | BlockNumber | Hash32 | HexStr | HexBytes | int | None = 'latest') → str

send_multisig_tx(to: ChecksumAddress, value: int, data: bytes, operation: SafeOperationEnum | int, safe_tx_gas: int, base_gas: int, gas_price: int, gas_token: ChecksumAddress, refund_receiver: ChecksumAddress, signatures: bytes, tx_sender_private_key: HexStr, tx_gas=None, tx_gas_price=None, block_identifier: Literal['latest', 'earliest', 'pending', 'safe', 'finalized'] | BlockNumber | Hash32 | HexStr | HexBytes | int | None = 'latest') → EthereumTxSent

Build and send Safe tx

Parameters:

to
value
data
operation – Operation type (SafeOperationEnum or matching integer value)
safe_tx_gas
base_gas
gas_price
gas_token
refund_receiver
signatures
tx_sender_private_key
tx_gas – Gas for the external tx. If not, (safe_tx_gas + data_gas) * 2 will be used
tx_gas_price – Gas price of the external tx. If not, gas_price will be used
block_identifier

Returns:

EthereumTxSent

Raises:

InvalidMultisigTx: If user tx cannot go through the Safe

property simulate_tx_accessor_address: ChecksumAddress: Address of the SimulateTxAccessor contract. Can be overridden via SAFE_SIMULATE_TX_ACCESSOR_ADDRESS env var.

class safe_eth.safe.safe.SafeCompatibilityAdapter(address: ChecksumAddress, ethereum_client: EthereumClient, version: str | None = None, *args, **kwargs)

Bases: Safe, ABC

Adapter for Safe contracts v1.4.1 and later. Overrides some methods to handle API changes in newer contract versions.

Estimate tx gas. Use SimulateTxAccessor and simulate on the CompatibilityFallHandler

Parameters:

to
value
data
operation
gas_limit
block_identifier

Returns:

class safe_eth.safe.safe.SafeInfo(address: eth_typing.evm.ChecksumAddress, fallback_handler: eth_typing.evm.ChecksumAddress, guard: eth_typing.evm.ChecksumAddress, master_copy: eth_typing.evm.ChecksumAddress, modules: List[eth_typing.evm.ChecksumAddress], nonce: int, owners: List[eth_typing.evm.ChecksumAddress], threshold: int, version: str, module_guard: eth_typing.evm.ChecksumAddress)

Bases: object

address: ChecksumAddress

fallback_handler: ChecksumAddress

guard: ChecksumAddress

master_copy: ChecksumAddress

module_guard: ChecksumAddress

modules: List[ChecksumAddress]

nonce: int

owners: List[ChecksumAddress]

threshold: int

version: str

class safe_eth.safe.safe.SafeV001(address: ChecksumAddress, ethereum_client: EthereumClient, version: str | None = None, *args, **kwargs)

Bases: Safe

classmethod deploy_contract(ethereum_client: EthereumClient, deployer_account: LocalAccount) → EthereumTxSent

Deploy master contract. Takes deployer_account (if unlocked in the node) or the deployer private key

Parameters:

ethereum_client
deployer_account – Ethereum account

Returns:

EthereumTxSent with the deployed contract address

get_contract_fn() → Callable[[Web3, ChecksumAddress | None], Contract]

Returns:: Contract function to get the proper contract

get_version() → str

Returns:: String with Safe Master Copy semantic version, must match retrieve_version()

class safe_eth.safe.safe.SafeV100(address: ChecksumAddress, ethereum_client: EthereumClient, version: str | None = None, *args, **kwargs)

Bases: Safe

classmethod deploy_contract(ethereum_client: EthereumClient, deployer_account: LocalAccount) → EthereumTxSent

Deploy master contract. Takes deployer_account (if unlocked in the node) or the deployer private key

Parameters:

ethereum_client
deployer_account – Ethereum account

Returns:

EthereumTxSent with the deployed contract address

get_contract_fn() → Callable[[Web3, ChecksumAddress | None], Contract]

Returns:: Contract function to get the proper contract

get_version() → str

Returns:: String with Safe Master Copy semantic version, must match retrieve_version()

class safe_eth.safe.safe.SafeV111(address: ChecksumAddress, ethereum_client: EthereumClient, version: str | None = None, *args, **kwargs)

Bases: Safe

get_contract_fn() → Callable[[Web3, ChecksumAddress | None], Contract]

Returns:: Contract function to get the proper contract

get_version() → str

Returns:: String with Safe Master Copy semantic version, must match retrieve_version()

class safe_eth.safe.safe.SafeV120(address: ChecksumAddress, ethereum_client: EthereumClient, version: str | None = None, *args, **kwargs)

Bases: Safe

get_contract_fn() → Callable[[Web3, ChecksumAddress | None], Contract]

Returns:: Contract function to get the proper contract

get_version() → str

Returns:: String with Safe Master Copy semantic version, must match retrieve_version()

class safe_eth.safe.safe.SafeV130(address: ChecksumAddress, ethereum_client: EthereumClient, version: str | None = None, *args, **kwargs)

Bases: Safe

get_contract_fn() → Callable[[Web3, ChecksumAddress | None], Contract]

Returns:: Contract function to get the proper contract

get_version() → str

Returns:: String with Safe Master Copy semantic version, must match retrieve_version()

class safe_eth.safe.safe.SafeV141(address: ChecksumAddress, ethereum_client: EthereumClient, version: str | None = None, *args, **kwargs)

Bases: SafeCompatibilityAdapter

get_contract_fn() → Callable[[Web3, ChecksumAddress | None], Contract]

Returns:: Contract function to get the proper contract

get_version() → str

Returns:: String with Safe Master Copy semantic version, must match retrieve_version()

class safe_eth.safe.safe.SafeV150(address: ChecksumAddress, ethereum_client: EthereumClient, version: str | None = None, *args, **kwargs)

Bases: SafeCompatibilityAdapter

get_contract_fn() → Callable[[Web3, ChecksumAddress | None], Contract]

Returns:: Contract function to get the proper contract

get_version() → str

Returns:: String with Safe Master Copy semantic version, must match retrieve_version()

safe_eth.safe.safe_create2_tx module

class safe_eth.safe.safe_create2_tx.SafeCreate2Tx(salt_nonce, owners, threshold, fallback_handler, master_copy_address, proxy_factory_address, payment_receiver, payment_token, payment, gas, gas_price, payment_token_eth_value, fixed_creation_cost, safe_address, safe_setup_data)

Bases: NamedTuple

fallback_handler: str: Alias for field number 3

fixed_creation_cost: int | None: Alias for field number 12

gas: int: Alias for field number 9

gas_price: int: Alias for field number 10

master_copy_address: str: Alias for field number 4

owners: List[str]: Alias for field number 1

payment: int: Alias for field number 8

property payment_ether

payment_receiver: str: Alias for field number 6

payment_token: str: Alias for field number 7

payment_token_eth_value: float: Alias for field number 11

proxy_factory_address: str: Alias for field number 5

safe_address: str: Alias for field number 13

safe_setup_data: bytes: Alias for field number 14

salt_nonce: int: Alias for field number 0

threshold: int: Alias for field number 2

class safe_eth.safe.safe_create2_tx.SafeCreate2TxBuilder(w3: Web3, master_copy_address: ChecksumAddress, proxy_factory_address: ChecksumAddress)

Bases: object

Helper to create Safes using Safe’s Proxy Factory with CREATE2

build(owners: Sequence[ChecksumAddress], threshold: int, salt_nonce: int, gas_price: int, fallback_handler: ChecksumAddress | None = None, payment_receiver: ChecksumAddress | None = None, payment_token: ChecksumAddress | None = None, payment_token_eth_value: float = 1.0, fixed_creation_cost: int | None = None) → SafeCreate2Tx

Parameters:

owners – Owners of the Safe
threshold – Minimum number of users required to operate the Safe
fallback_handler – Handler for fallback calls to the Safe
salt_nonce – Web3 instance
gas_price – Gas Price
payment_receiver – Address to refund when the Safe is created. Address(0) if no need to refund
payment_token – Payment token instead of paying the funder with ether. If None Ether will be used
payment_token_eth_value – Value of payment token per 1 Ether
fixed_creation_cost – Fixed creation cost of Safe (Wei)

Returns:

SafeCreate2Tx with all the data for execution

calculate_create2_address(safe_setup_data: bytes, salt_nonce: int)

safe_eth.safe.safe_creator module

class safe_eth.safe.safe_creator.SafeCreationEstimate(gas, gas_price, payment, payment_token)

Bases: NamedTuple

gas: int: Alias for field number 0

gas_price: int: Alias for field number 1

payment: int: Alias for field number 2

payment_token: str | None: Alias for field number 3

class safe_eth.safe.safe_creator.SafeCreator

Bases: object

Deploy required Safe contracts and Safes

static build_safe_create2_tx(ethereum_client: EthereumClient, master_copy_address: ChecksumAddress, proxy_factory_address: ChecksumAddress, salt_nonce: int, owners: Sequence[ChecksumAddress], threshold: int, gas_price: int, payment_token: ChecksumAddress | None, payment_receiver: ChecksumAddress | None = None, fallback_handler: ChecksumAddress | None = '0x0000000000000000000000000000000000000000', payment_token_eth_value: float = 1.0, fixed_creation_cost: int | None = None) → SafeCreate2Tx: Prepare safe proxy deployment for being relayed. It calculates and sets the costs of deployment to be returned to the sender of the tx. If you are an advanced user you may prefer to use create function

static create(ethereum_client: EthereumClient, deployer_account: LocalAccount, master_copy_address: ChecksumAddress, owners: List[ChecksumAddress], threshold: int, fallback_handler: ChecksumAddress | None = '0x0000000000000000000000000000000000000000', proxy_factory_address: ChecksumAddress | None = None, payment_token: ChecksumAddress | None = '0x0000000000000000000000000000000000000000', payment: int = 0, payment_receiver: ChecksumAddress | None = '0x0000000000000000000000000000000000000000') → EthereumTxSent

Deploy new Safe proxy pointing to the specified master_copy address and configured with the provided owners and threshold. By default, payment for the deployer of the tx will be 0. If proxy_factory_address is set deployment will be done using the proxy factory instead of calling the constructor of a new DelegatedProxy Using proxy_factory_address is recommended

Parameters:

ethereum_client
deployer_account
master_copy_address
owners
threshold
fallback_handler
proxy_factory_address
payment_token
payment
payment_receiver

Returns:

static deploy_simulate_tx_accessor(ethereum_client: EthereumClient, deployer_account: LocalAccount) → EthereumTxSent

Deploy Last compatibility Fallback handler

Parameters:

ethereum_client
deployer_account – Ethereum account

Returns:

EthereumTxSent with the deployed contract address

static estimate_safe_creation_2(ethereum_client: EthereumClient, master_copy_address: ChecksumAddress, proxy_factory_address: ChecksumAddress, number_owners: int, gas_price: int, payment_token: ChecksumAddress | None, payment_receiver: ChecksumAddress = '0x0000000000000000000000000000000000000000', fallback_handler: ChecksumAddress | None = None, payment_token_eth_value: float = 1.0, fixed_creation_cost: int | None = None) → SafeCreationEstimate

Parameters:

ethereum_client
master_copy_address
proxy_factory_address
number_owners
gas_price
payment_token
payment_receiver
fallback_handler
payment_token_eth_value
fixed_creation_cost

Returns:

An estimation for creating a Safe with the provided parameters

safe_eth.safe.safe_deployments module

safe_eth.safe.safe_signature module

exception safe_eth.safe.safe_signature.CannotCheckEIP1271ContractSignature: Bases: SafeSignatureException

class safe_eth.safe.safe_signature.SafeSignature(signature: bytes | str, safe_hash: bytes | str)

Bases: SafeSignatureBase

approved_hash_cls: alias of SafeSignatureApprovedHash

contract_signature_cls: alias of SafeSignatureContract

eoa_cls: alias of SafeSignatureEOA

eth_sign_cls: alias of SafeSignatureEthSign

abstractmethod is_valid(ethereum_client: EthereumClient | None = None, safe_address: str | None = None) → bool

Parameters:

ethereum_client – Required for Contract Signature and Approved Hash check
safe_address – Required for Approved Hash check

Returns:

True if signature is valid, False otherwise

class safe_eth.safe.safe_signature.SafeSignatureApprovedHash(signature: bytes | str, safe_hash: bytes | str)

Bases: SafeSignatureApprovedHashMixin, SafeSignature

is_valid(ethereum_client: EthereumClient | None = None, safe_address: str | None = None) → bool

Parameters:

ethereum_client – Required for Contract Signature and Approved Hash check
safe_address – Required for Approved Hash check

Returns:

True if signature is valid, False otherwise

class safe_eth.safe.safe_signature.SafeSignatureApprovedHashAsync(signature: bytes | str, safe_hash: bytes | str)

Bases: SafeSignatureApprovedHashMixin, SafeSignatureAsync

async is_valid(web3: AsyncWeb3 | None = None, safe_address: str | None = None) → bool

class safe_eth.safe.safe_signature.SafeSignatureApprovedHashMixin(signature: bytes | str, safe_hash: bytes | str)

Bases: SafeSignatureBase

classmethod build_for_owner(owner: str, safe_hash: str) → Self

property owner: ChecksumAddress

Returns:: Decode owner from signature, without any further validation (signature can be not valid)

property signature_type: SafeSignatureType

class safe_eth.safe.safe_signature.SafeSignatureAsync(signature: bytes | str, safe_hash: bytes | str)

Bases: SafeSignatureBase

approved_hash_cls: alias of SafeSignatureApprovedHashAsync

contract_signature_cls: alias of SafeSignatureContractAsync

eoa_cls: alias of SafeSignatureEOAAsync

eth_sign_cls: alias of SafeSignatureEthSignAsync

abstractmethod async is_valid(web3: AsyncWeb3 | None = None, safe_address: str | None = None) → bool

class safe_eth.safe.safe_signature.SafeSignatureBase(signature: bytes | str, safe_hash: bytes | str)

Bases: ABC

approved_hash_cls: ClassVar[Type[SafeSignatureBase] | None] = None

contract_signature_cls: ClassVar[Type[SafeSignatureBase] | None] = None

eoa_cls: ClassVar[Type[SafeSignatureBase] | None] = None

eth_sign_cls: ClassVar[Type[SafeSignatureBase] | None] = None

export_signature() → HexBytes

Exports signature in a format that’s valid individually. That’s important for contract signatures, as it will fix the offset

Returns:

classmethod export_signatures(safe_signatures: Sequence[SafeSignatureBase]) → HexBytes

Takes a list of SafeSignature objects and exports them as a valid signature for the contract

Parameters:: safe_signatures
Returns:: Valid signature for the Safe contract

abstract property owner: ChecksumAddress

Returns:: Decode owner from signature, without any further validation (signature can be not valid)

classmethod parse_signature(signatures: bytes | str, safe_hash: bytes | str, safe_hash_preimage: bytes | str | None = None, ignore_trailing: bool = True) → List[TSafeSignature]

Parameters:

signatures – One or more signatures appended. EIP1271 data at the end is supported.
safe_hash – Signed hash for the Safe (message or transaction)
safe_hash_preimage – safe_hash preimage for EIP1271 validation
ignore_trailing – Ignore trailing data on the signature. Some libraries pad it and add some zeroes at the end

Returns:

List of SafeSignatures decoded

abstract property signature_type: SafeSignatureType

class safe_eth.safe.safe_signature.SafeSignatureContract(signature: bytes | str, safe_hash: bytes | str, safe_hash_preimage: bytes | str, contract_signature: bytes | str)

Bases: SafeSignatureContractMixin, SafeSignature

is_valid(ethereum_client: EthereumClient | None = None, safe_address: str | None = None) → bool

Validate the signature using the appropriate EIP-1271 path. First tries the updated method (bytes32,bytes). Falls back to the legacy method (bytes,bytes).

Parameters:

ethereum_client – EthereumClient instance
safe_address – Optional Safe EthereumAddress instance.

class safe_eth.safe.safe_signature.SafeSignatureContractAsync(signature: bytes | str, safe_hash: bytes | str, safe_hash_preimage: bytes | str, contract_signature: bytes | str)

Bases: SafeSignatureContractMixin, SafeSignatureAsync

async is_valid(web3: AsyncWeb3 | None = None, safe_address: str | None = None) → bool

Validate the signature using the appropriate EIP-1271 path. First tries the updated method (bytes32,bytes). Falls back to the legacy method (bytes,bytes).

Parameters:

web3 – Optional EthereumClient instance.
safe_address – Optional Safe EthereumAddress instance.

class safe_eth.safe.safe_signature.SafeSignatureContractMixin(signature: bytes | str, safe_hash: bytes | str, safe_hash_preimage: bytes | str, contract_signature: bytes | str)

Bases: SafeSignatureBase

EIP1271_MAGIC_VALUE = HexBytes('0x20c13b0b')

EIP1271_MAGIC_VALUE_UPDATED = HexBytes('0x1626ba7e')

export_signature() → HexBytes

Exports signature in a format that’s valid individually. That’s important for contract signatures, as it will fix the offset

Returns:

classmethod from_values(safe_owner: ChecksumAddress, safe_hash: bytes | str, safe_hash_preimage: bytes | str, contract_signature: bytes | str) → Self

property owner: ChecksumAddress

Returns:: Decode owner from signature, without any further validation (signature can be not valid)

property signature_type: SafeSignatureType

class safe_eth.safe.safe_signature.SafeSignatureEOA(signature: bytes | str, safe_hash: bytes | str)

Bases: SafeSignatureEOAMixin, SafeSignature

is_valid(ethereum_client: EthereumClient | None = None, safe_address: str | None = None) → bool

Parameters:

ethereum_client – Required for Contract Signature and Approved Hash check
safe_address – Required for Approved Hash check

Returns:

True if signature is valid, False otherwise

class safe_eth.safe.safe_signature.SafeSignatureEOAAsync(signature: bytes | str, safe_hash: bytes | str)

Bases: SafeSignatureEOAMixin, SafeSignatureAsync

async is_valid(web3: AsyncWeb3 | None = None, safe_address: str | None = None) → bool

class safe_eth.safe.safe_signature.SafeSignatureEOAMixin(signature: bytes | str, safe_hash: bytes | str)

Bases: SafeSignatureBase

property owner: ChecksumAddress

Returns:: Decode owner from signature, without any further validation (signature can be not valid)

property signature_type: SafeSignatureType

class safe_eth.safe.safe_signature.SafeSignatureEthSign(signature: bytes | str, safe_hash: bytes | str)

Bases: SafeSignatureEthSignMixin, SafeSignature

is_valid(ethereum_client: EthereumClient | None = None, safe_address: str | None = None) → bool

Parameters:

ethereum_client – Required for Contract Signature and Approved Hash check
safe_address – Required for Approved Hash check

Returns:

True if signature is valid, False otherwise

class safe_eth.safe.safe_signature.SafeSignatureEthSignAsync(signature: bytes | str, safe_hash: bytes | str)

Bases: SafeSignatureEthSignMixin, SafeSignatureAsync

async is_valid(web3: AsyncWeb3 | None = None, safe_address: str | None = None) → bool

class safe_eth.safe.safe_signature.SafeSignatureEthSignMixin(signature: bytes | str, safe_hash: bytes | str)

Bases: SafeSignatureBase

property owner: ChecksumAddress

Returns:: Decode owner from signature, without any further validation (signature can be not valid)

property signature_type: SafeSignatureType

exception safe_eth.safe.safe_signature.SafeSignatureException: Bases: Exception

class safe_eth.safe.safe_signature.SafeSignatureType(value)

Bases: IntEnum

APPROVED_HASH = 1

CONTRACT_SIGNATURE = 0

EOA = 2

ETH_SIGN = 3

static from_v(v: int) → SafeSignatureType

class safe_eth.safe.safe_signature.SupportsContractSignature(*args, **kwargs)

Bases: Protocol

contract_signature: HexBytes

safe_eth.safe.safe_signature.uint_to_address(value: int) → ChecksumAddress

Convert a Solidity uint value to a checksummed address, removing invalid padding bytes if present

Returns:: Checksummed address

safe_eth.safe.safe_tx module

class safe_eth.safe.safe_tx.SafeTx(ethereum_client: EthereumClient, safe_address: ChecksumAddress, to: ChecksumAddress | None, value: int, data: bytes, operation: SafeOperationEnum | int, safe_tx_gas: int, base_gas: int, gas_price: int, gas_token: ChecksumAddress | None, refund_receiver: ChecksumAddress | None, signatures: bytes | None = None, safe_nonce: int | None = None, safe_version: str | None = None, chain_id: int | None = None)

Bases: object

Parameters:

tx_sender_address
tx_gas – Force a gas limit
block_identifier

Returns:

1 if everything ok

property chain_id: int

property contract

property eip712_structured_data: Dict[str, Any]

Send multisig tx to the Safe

Parameters:

tx_sender_private_key – Sender private key
tx_gas – Gas for the external tx. If not, (safe_tx_gas + base_gas) * 2 will be used
tx_gas_price – Gas price of the external tx. If not, gas_price will be used
tx_nonce – Force nonce for tx_sender
block_identifier – latest or pending
eip1559_speed – If provided, use EIP1559 transaction

Returns:

Tuple(tx_hash, tx)

Raises:

InvalidMultisigTx: If user tx cannot go through the Safe

recommended_gas() → Wei

Returns:: Recommended gas to use on the ethereum_tx

property safe_nonce: int

property safe_tx_hash: HexBytes

property safe_tx_hash_preimage: HexBytes

property safe_version: str

sign(private_key: str) → bytes: {bytes32 r}{bytes32 s}{uint8 v} :param private_key: :return: Signature

property signers: List[str]

property sorted_signers

unsign(address: str) → bool

property w3

property w3_tx: ContractFunction

Returns:: Web3 contract tx prepared for call, transact or build_transaction

safe_eth.safe.serializers module

class safe_eth.safe.serializers.SafeMultisigEstimateTxSerializer(*args, **kwargs)

Bases: Serializer

validate(data)

validate_operation(value)

class safe_eth.safe.serializers.SafeMultisigTxSerializer(*args, **kwargs): Bases: SafeMultisigEstimateTxSerializer

safe_eth.safe.signatures module

safe_eth.safe.signatures.get_signing_address(signed_hash: bytes, v: int, r: int, s: int) → str

Returns:: checksummed ethereum address, for example 0x568c93675A8dEb121700A6FAdDdfE7DFAb66Ae4A
Return type:: str or NULL_ADDRESS if signature is not valid

safe_eth.safe.signatures.signature_split(signatures: bytes | str, pos: int = 0) → Tuple[int, int, int]

Parameters:

signatures – signatures in form of {bytes32 r}{bytes32 s}{uint8 v}
pos – position of the signature

Returns:

Tuple with v, r, s

safe_eth.safe.signatures.signature_to_bytes(v: int, r: int, s: int) → bytes: Convert ecdsa signature to bytes :param v: :param r: :param s: :return: signature in form of {bytes32 r}{bytes32 s}{uint8 v}

safe_eth.safe.signatures.signatures_to_bytes(signatures: List[Tuple[int, int, int]]) → bytes: Convert signatures to bytes :param signatures: list of tuples(v, r, s) :return: 65 bytes per signature

Module contents

exception safe_eth.safe.CannotEstimateGas: Bases: SafeServiceException

exception safe_eth.safe.CouldNotPayGasWithEther: Bases: InvalidMultisigTx

exception safe_eth.safe.InvalidChecksumAddress: Bases: SafeServiceException

exception safe_eth.safe.InvalidInternalTx: Bases: InvalidMultisigTx

exception safe_eth.safe.InvalidMultisigTx: Bases: SafeServiceException

exception safe_eth.safe.InvalidPaymentToken: Bases: SafeServiceException

exception safe_eth.safe.InvalidSignaturesProvided: Bases: InvalidMultisigTx

class safe_eth.safe.ProxyFactory(*args, version: str = '1.5.0', **kwargs)

Bases: ContractBase

calculate_proxy_address(master_copy: ChecksumAddress, initializer: bytes, salt_nonce: int, chain_specific: bool = False) → ChecksumAddress

Calculate proxy address for calling deploy_proxy_contract_with_nonce

Parameters:

master_copy
initializer
salt_nonce
chain_specific – Calculate chain specific address (to prevent same address in other chains)

Returns:

check_proxy_code(address: ChecksumAddress) → bool

Check if proxy bytecode matches any of the deployed by the supported Proxy Factories

Parameters:: address – Ethereum address to check
Returns:: True if proxy is valid, False otherwise

classmethod deploy_contract(ethereum_client: EthereumClient, deployer_account: LocalAccount) → EthereumTxSent

Deploy Proxy Factory contract

Parameters:

ethereum_client
deployer_account – Ethereum Account

Returns:

EthereumTxSent with the deployed contract address

deploy_proxy_contract(deployer_account: LocalAccount, master_copy: ChecksumAddress, initializer: bytes = b'', gas: int | None = None, gas_price: int | None = None, nonce: int | None = None) → EthereumTxSent

Deploy proxy contract via ProxyFactory using createProxy function (CREATE opcode)

Parameters:

deployer_account – Ethereum account
master_copy – Address the proxy will point at
initializer – Initializer for the deployed proxy
gas – Gas
gas_price – Gas Price
nonce – Nonce

Returns:

EthereumTxSent

deploy_proxy_contract_with_nonce(deployer_account: LocalAccount, master_copy: ChecksumAddress, initializer: bytes = b'', salt_nonce: int | None = None, gas: int | None = None, gas_price: int | None = None, nonce: int | None = None, chain_specific: bool = False, is_l2: bool = False) → EthereumTxSent

Deploy proxy contract via Proxy Factory using createProxyWithNonce (CREATE2 opcode)

Parameters:

deployer_account – Ethereum account
master_copy – Address the proxy will point at
initializer – Initializer for the deployed proxy
salt_nonce – Uint256 for CREATE2 salt. If not provided, a random one will be used
gas – Gas
gas_price – Gas Price
nonce – Nonce
chain_specific – Calculate chain specific address (to prevent same address in other chains)
is_l2 – L2 deployment function

Returns:

EthereumTxSent

static detect_version_from_address(factory_address: ChecksumAddress) → str

Detect ProxyFactory version from a deployed address.

Parameters:: factory_address – The address of the ProxyFactory contract
Returns:: Version string (e.g., “1.5.0”)
Raises:: ValueError – If factory address is not found in safe_deployments

classmethod from_address(factory_address: ChecksumAddress, ethereum_client: EthereumClient) → ProxyFactory

Create a ProxyFactory instance from a deployed factory address. Automatically detects the correct version based on the address.

Parameters:

factory_address – The address of the deployed ProxyFactory contract
ethereum_client – Ethereum client instance

Returns:

ProxyFactory instance of the appropriate version (e.g., ProxyFactoryV141, ProxyFactoryV150)

Raises:

ValueError – If factory address is not found in safe_deployments

get_deploy_function(chain_specific: bool, is_l2: bool = False) → ContractFunction

get_proxy_creation_code() → bytes

Returns:: Creation code used for the Proxy deployment. With this it is easily possible to calculate predicted address.

get_proxy_runtime_code() → bytes

Returns:: Runtime code of a deployed Proxy. For v1.4.1 onwards the method is not available, so None will be returned

class safe_eth.safe.Safe(address: ChecksumAddress, ethereum_client: EthereumClient, version: str | None = None, *args, **kwargs)

Bases: SafeCreator, ContractBase

Collection of methods and utilities to handle a Safe

FALLBACK_HANDLER_STORAGE_SLOT = 49122629484629529244014240937346711770925847994644146912111677022347558721749

MODULE_GUARD_STORAGE_SLOT = 80067992571439485785405894129641280630172609254213753706009264638304931322183

SAFE_MESSAGE_TYPEHASH = b'`\xb3\xcb\xf8\xb4\xa2#\xd6\x8dd\x1b;m\xdf\x9a)\x8e\x7f3q\x0c\xf3\xd3\xa9\xd1\x14kZaP\xfb\xca'

TRANSACTION_GUARD_STORAGE_SLOT = 33528237782592280163068556224972516439282563014722366175641814928123294921928

classmethod available_versions() → List[str]

Helpful utility for tooling that needs to know which Safe versions are bundled.

Returns:: List of semantic versions, sorted ascending.

build_multisig_tx(to: ChecksumAddress, value: int, data: bytes, operation: SafeOperationEnum | int = 0, safe_tx_gas: int = 0, base_gas: int = 0, gas_price: int = 0, gas_token: ChecksumAddress = '0x0000000000000000000000000000000000000000', refund_receiver: ChecksumAddress = '0x0000000000000000000000000000000000000000', signatures: bytes = b'', safe_nonce: int | None = None) → SafeTx

Allows to execute a Safe transaction confirmed by required number of owners and then pays the account that submitted the transaction. The fees are always transferred, even if the user transaction fails

Parameters:

to – Destination address of Safe transaction
value – Ether value of Safe transaction
data – Data payload of Safe transaction
operation – Operation type (SafeOperationEnum or matching integer value)
safe_tx_gas – Gas that should be used for the Safe transaction
base_gas – Gas costs for that are independent of the transaction execution (e.g. base transaction fee, signature check, payment of the refund)
gas_price – Gas price that should be used for the payment calculation
gas_token – Token address (or 0x000..000 if ETH) that is used for the payment
refund_receiver – Address of receiver of gas payment (or 0x000..000 if tx.origin).
signatures – Packed signature data ({bytes32 r}{bytes32 s}{uint8 v})
safe_nonce – Nonce of the safe (to calculate hash)

Returns:

SafeTx

property chain_id: int

check_funds_for_tx_gas(safe_tx_gas: int, base_gas: int, gas_price: int, gas_token: str) → bool

Check safe has enough funds to pay for a tx

Parameters:

safe_tx_gas – Safe tx gas
base_gas – Data gas
gas_price – Gas Price
gas_token – Gas Token, to use token instead of ether for the gas

Returns:

True if enough funds, False otherwise

classmethod deploy_contract(ethereum_client: EthereumClient, deployer_account: LocalAccount) → EthereumTxSent

Deploy master contract. Takes deployer_account (if unlocked in the node) or the deployer private key Safe with version > v1.1.1 doesn’t need to be initialized as it already has a constructor

Parameters:

ethereum_client
deployer_account – Ethereum account

Returns:

EthereumTxSent with the deployed contract address

Return the Safe semantic version reported by the contract. None is returned if the read fails.

Parameters:

address – Safe proxy address
ethereum_client – Client wrapper used to interact with the node
block_identifier – Optional block identifier for the call

Returns:

Semantic version string or None if it cannot be detected

property domain_separator: bytes | None

Returns:: EIP721 DomainSeparator for the Safe. Returns None if not supported (for Safes < 1.0.0)

estimate_tx_base_gas(to: ChecksumAddress, value: int, data: bytes, operation: SafeOperationEnum | int, gas_token: ChecksumAddress, estimated_tx_gas: int) → int

Calculate gas costs that are independent of the transaction execution(e.g. base transaction fee, signature check, payment of the refund…)

Parameters:

to
value
data
operation
gas_token
estimated_tx_gas – gas calculated with estimate_tx_gas

Returns:

estimate_tx_gas(to: ChecksumAddress, value: int, data: bytes, operation: SafeOperationEnum | int) → int

Estimate tx gas. Use requiredTxGas on the Safe contract and fallbacks to eth_estimateGas if that method fails. Note: eth_estimateGas cannot estimate delegate calls

Parameters:

to
value
data
operation

Returns:

Estimated gas for Safe inner tx

Raises:

CannotEstimateGas

estimate_tx_gas_by_trying(to: ChecksumAddress, value: int, data: bytes | str, operation: SafeOperationEnum | int) → int

Try to get an estimation with Safe’s requiredTxGas. If estimation is successful, try to set a gas limit and estimate again. If gas estimation is ok, same gas estimation should be returned, if it’s less than required estimation will not be completed, so estimation was not accurate and gas limit needs to be increased.

Parameters:

to
value
data
operation

Returns:

Estimated gas calling requiredTxGas setting a gas limit and checking if eth_call is successful

Raises:

CannotEstimateGas

Estimate tx gas using safe requiredTxGas method

Returns:: int: Estimated gas
Raises:: CannotEstimateGas: If gas cannot be estimated
Raises:: ValueError: Cannot decode received data

estimate_tx_gas_with_web3(to: ChecksumAddress, value: int, data: bytes | HexStr) → int

Parameters:

to
value
data

Returns:

Estimation using web3 estimate_gas

classmethod from_version(version: str, address: ChecksumAddress, ethereum_client: EthereumClient, *args, **kwargs) → Safe

Build a Safe without querying the chain for VERSION(). Existing call sites keep working but integrators that already know the version can bypass the RPC lookup.

Parameters:

version – Semantic version to instantiate
address – Safe proxy address
ethereum_client – Client wrapper used to interact with the node
args – Extra args forwarded to the concrete Safe class
kwargs – Extra kwargs forwarded to the concrete Safe class

Returns:

Instance of the requested Safe subclass

get_message_hash(message: str | bytes) → Hash32

Return hash of a message that can be signed by owners.

Parameters:: message – Message that should be hashed. A Hash32 must be provided for EIP191 or EIP712 messages
Returns:: Message hash

get_message_hash_and_preimage(message: str | bytes) → tuple[Hash32, bytes]

Return hash of a message and its preimage that can be signed by owners.

Parameters:: message – Message that should be hashed. A Hash32 must be provided for EIP191 or EIP712 messages
Returns:: Tuple of message hash and preimage for the provided message

get_message_preimage(message: str | bytes) → bytes

Return preimage for a message that can be signed by owners.

Parameters:: message – Message that should be hashed. A Hash32 must be provided for EIP191 or EIP712 messages
Returns:: Preimage for the provided message

abstractmethod get_version() → str

Returns:: String with Safe Master Copy semantic version, must match retrieve_version()

Get all Safe info in the same batch call.

Parameters:: block_identifier
Returns:
Raises:: CannotRetrieveSafeInfoException

retrieve_code() → HexBytes

retrieve_domain_separator(block_identifier: Literal['latest', 'earliest', 'pending', 'safe', 'finalized'] | BlockNumber | Hash32 | HexStr | HexBytes | int | None = 'latest') → bytes | None

retrieve_fallback_handler(block_identifier: Literal['latest', 'earliest', 'pending', 'safe', 'finalized'] | BlockNumber | Hash32 | HexStr | HexBytes | int | None = 'latest') → ChecksumAddress

retrieve_is_hash_approved(owner: ChecksumAddress, safe_hash: bytes, block_identifier: Literal['latest', 'earliest', 'pending', 'safe', 'finalized'] | BlockNumber | Hash32 | HexStr | HexBytes | int | None = 'latest') → bool

retrieve_is_message_signed(message_hash: Hash32, block_identifier: Literal['latest', 'earliest', 'pending', 'safe', 'finalized'] | BlockNumber | Hash32 | HexStr | HexBytes | int | None = 'latest') → bool

retrieve_is_owner(owner: ChecksumAddress, block_identifier: Literal['latest', 'earliest', 'pending', 'safe', 'finalized'] | BlockNumber | Hash32 | HexStr | HexBytes | int | None = 'latest') → bool

Parameters:: block_identifier
Returns:: Returns the implementation address. Multiple types of proxies are supported

Retrieve the module guard address from storage. Module guard was introduced in Safe v1.5.0.

Parameters:: block_identifier
Returns:: Module guard address or NULL_ADDRESS if not set

Get modules enabled on the Safe From v1.1.1:

getModulesPaginated is available

getModules returns only 10 modules

Parameters:

pagination – Number of modules to get per request
max_modules_to_retrieve – Maximum number of modules to retrieve
block_identifier

Returns:

List of module addresses

retrieve_nonce(block_identifier: Literal['latest', 'earliest', 'pending', 'safe', 'finalized'] | BlockNumber | Hash32 | HexStr | HexBytes | int | None = 'latest') → int

retrieve_owners(block_identifier: Literal['latest', 'earliest', 'pending', 'safe', 'finalized'] | BlockNumber | Hash32 | HexStr | HexBytes | int | None = 'latest') → List[ChecksumAddress]

retrieve_threshold(block_identifier: Literal['latest', 'earliest', 'pending', 'safe', 'finalized'] | BlockNumber | Hash32 | HexStr | HexBytes | int | None = 'latest') → int

Retrieve the transaction guard address from storage. Transaction guard (previously just “guard”) was implemented in v1.1.1.

Parameters:: block_identifier
Returns:: Transaction guard address or NULL_ADDRESS if not set

retrieve_version(block_identifier: Literal['latest', 'earliest', 'pending', 'safe', 'finalized'] | BlockNumber | Hash32 | HexStr | HexBytes | int | None = 'latest') → str

send_multisig_tx(to: ChecksumAddress, value: int, data: bytes, operation: SafeOperationEnum | int, safe_tx_gas: int, base_gas: int, gas_price: int, gas_token: ChecksumAddress, refund_receiver: ChecksumAddress, signatures: bytes, tx_sender_private_key: HexStr, tx_gas=None, tx_gas_price=None, block_identifier: Literal['latest', 'earliest', 'pending', 'safe', 'finalized'] | BlockNumber | Hash32 | HexStr | HexBytes | int | None = 'latest') → EthereumTxSent

Build and send Safe tx

Parameters:

to
value
data
operation – Operation type (SafeOperationEnum or matching integer value)
safe_tx_gas
base_gas
gas_price
gas_token
refund_receiver
signatures
tx_sender_private_key
tx_gas – Gas for the external tx. If not, (safe_tx_gas + data_gas) * 2 will be used
tx_gas_price – Gas price of the external tx. If not, gas_price will be used
block_identifier

Returns:

EthereumTxSent

Raises:

InvalidMultisigTx: If user tx cannot go through the Safe

property simulate_tx_accessor_address: ChecksumAddress: Address of the SimulateTxAccessor contract. Can be overridden via SAFE_SIMULATE_TX_ACCESSOR_ADDRESS env var.

class safe_eth.safe.SafeOperationEnum(value)

Bases: IntEnum

CALL = 0

CREATE = 2

DELEGATE_CALL = 1

exception safe_eth.safe.SafeServiceException: Bases: Exception

class safe_eth.safe.SafeTx(ethereum_client: EthereumClient, safe_address: ChecksumAddress, to: ChecksumAddress | None, value: int, data: bytes, operation: SafeOperationEnum | int, safe_tx_gas: int, base_gas: int, gas_price: int, gas_token: ChecksumAddress | None, refund_receiver: ChecksumAddress | None, signatures: bytes | None = None, safe_nonce: int | None = None, safe_version: str | None = None, chain_id: int | None = None)

Bases: object

Parameters:

tx_sender_address
tx_gas – Force a gas limit
block_identifier

Returns:

1 if everything ok

property chain_id: int

property contract

property eip712_structured_data: Dict[str, Any]

Send multisig tx to the Safe

Parameters:

tx_sender_private_key – Sender private key
tx_gas – Gas for the external tx. If not, (safe_tx_gas + base_gas) * 2 will be used
tx_gas_price – Gas price of the external tx. If not, gas_price will be used
tx_nonce – Force nonce for tx_sender
block_identifier – latest or pending
eip1559_speed – If provided, use EIP1559 transaction

Returns:

Tuple(tx_hash, tx)

Raises:

InvalidMultisigTx: If user tx cannot go through the Safe

recommended_gas() → Wei

Returns:: Recommended gas to use on the ethereum_tx

property safe_nonce: int

property safe_tx_hash: HexBytes

property safe_tx_hash_preimage: HexBytes

property safe_version: str

sign(private_key: str) → bytes: {bytes32 r}{bytes32 s}{uint8 v} :param private_key: :return: Signature

property signers: List[str]

property sorted_signers

unsign(address: str) → bool

property w3

property w3_tx: ContractFunction

Returns:: Web3 contract tx prepared for call, transact or build_transaction

exception safe_eth.safe.SignatureNotProvidedByOwner: Bases: InvalidMultisigTx