gnosis.safe package

Subpackages

Submodules

gnosis.safe.exceptions module

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

gnosis.safe.multi_send module

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

Bases: object

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

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

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

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 gnosis.safe.multi_send.MultiSendOperation(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

CALL = 0

DELEGATE_CALL = 1

class gnosis.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:

gnosis.safe.proxy_factory module

class gnosis.safe.proxy_factory.ProxyFactory(*args, version: str = '1.4.1', **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) → 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)

Returns:

EthereumTxSent

get_deploy_function(chain_specific: bool) → 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 gnosis.safe.proxy_factory.ProxyFactoryV100(*args, version: str = '1.4.1', **kwargs)

Bases: ProxyFactory

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

Returns:: Contract function to get the proper contract

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

Bases: ProxyFactory

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

Returns:: Contract function to get the proper contract

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

Bases: ProxyFactory

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

Returns:: Contract function to get the proper contract

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

Bases: ProxyFactory

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_contract_fn() → Callable[[Web3, ChecksumAddress], Contract]

Returns:: Contract function to get the proper contract

get_deploy_function(chain_specific: bool) → ContractFunction

get_proxy_runtime_code() → bytes | None

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

gnosis.safe.safe module

class gnosis.safe.safe.Safe(address: ChecksumAddress, ethereum_client: EthereumClient, *args, **kwargs)

Bases: SafeCreator, ContractBase

Collection of methods and utilies to handle a Safe

FALLBACK_HANDLER_STORAGE_SLOT = 49122629484629529244014240937346711770925847994644146912111677022347558721749

GUARD_STORAGE_SLOT = 33528237782592280163068556224972516439282563014722366175641814928123294921928

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'

build_multisig_tx(to: ChecksumAddress, value: int, data: bytes, operation: 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 transfered, 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 of Safe transaction
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)
safe_version – Safe version (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

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: 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: 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: 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

get_message_hash(message: str | Hash32) → 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

abstract 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') → str

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

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

retrieve_is_hash_approved(owner: str, 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: str, block_identifier: Literal['latest', 'earliest', 'pending', 'safe', 'finalized'] | BlockNumber | Hash32 | HexStr | HexBytes | int | None = 'latest') → bool

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

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[str]

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

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: 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 –
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:

Tuple(tx_hash, tx)

Raises:

InvalidMultisigTx: If user tx cannot go through the Safe

property simulate_tx_accessor_address: ChecksumAddress

class gnosis.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)

Bases: object

address: ChecksumAddress

fallback_handler: ChecksumAddress

guard: ChecksumAddress

master_copy: ChecksumAddress

modules: List[ChecksumAddress]

nonce: int

owners: List[ChecksumAddress]

threshold: int

version: str

class gnosis.safe.safe.SafeV001(address: ChecksumAddress, ethereum_client: EthereumClient, *args, **kwargs)

Bases: Safe

static 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], Contract]

Returns:: Contract function to get the proper contract

get_version()

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

class gnosis.safe.safe.SafeV100(address: ChecksumAddress, ethereum_client: EthereumClient, *args, **kwargs)

Bases: Safe

static 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() → Contract

Returns:: Contract function to get the proper contract

get_version()

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

class gnosis.safe.safe.SafeV111(address: ChecksumAddress, ethereum_client: EthereumClient, *args, **kwargs)

Bases: Safe

get_contract_fn() → Contract

Returns:: Contract function to get the proper contract

get_version()

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

class gnosis.safe.safe.SafeV120(address: ChecksumAddress, ethereum_client: EthereumClient, *args, **kwargs)

Bases: Safe

get_contract_fn() → Contract

Returns:: Contract function to get the proper contract

get_version()

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

class gnosis.safe.safe.SafeV130(address: ChecksumAddress, ethereum_client: EthereumClient, *args, **kwargs)

Bases: Safe

get_contract_fn() → Contract

Returns:: Contract function to get the proper contract

get_version()

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

class gnosis.safe.safe.SafeV141(address: ChecksumAddress, ethereum_client: EthereumClient, *args, **kwargs)

Bases: Safe

Estimate tx gas. Use SimulateTxAccesor and simulate on the CompatibilityFallHandler

Parameters:

to –
value –
data –
operation –
gas_limit –
block_identifier –

Returns:

get_contract_fn() → Contract

Returns:: Contract function to get the proper contract

get_version()

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

gnosis.safe.safe_create2_tx module

exception gnosis.safe.safe_create2_tx.InvalidERC20Token: Bases: Exception

class gnosis.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 gnosis.safe.safe_create2_tx.SafeCreate2TxBuilder(w3: Web3, master_copy_address: ChecksumAddress, proxy_factory_address: ChecksumAddress)

Bases: object

build(owners: List[str], threshold: int, salt_nonce: int, gas_price: int, fallback_handler: str | None = None, payment_receiver: str | None = None, payment_token: str | None = None, payment_token_eth_value: float = 1.0, fixed_creation_cost: int | None = None)

Prepare Safe creation

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)

calculate_create2_address(safe_setup_data: bytes, salt_nonce: int)

gnosis.safe.safe_creation_tx module

gnosis.safe.safe_signature module

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

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

Bases: ABC

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[SafeSignature]) → 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 is_valid(ethereum_client: EthereumClient, safe_address: str) → 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

abstract property owner

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[SafeSignature]

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 gnosis.safe.safe_signature.SafeSignatureApprovedHash(signature: bytes | str, safe_hash: bytes | str)

Bases: SafeSignature

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

is_valid(ethereum_client: EthereumClient, safe_address: str) → 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

property owner

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

property signature_type

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

Bases: SafeSignature

EIP1271_MAGIC_VALUE = HexBytes('0x20c13b0b')

EIP1271_MAGIC_VALUE_UPDATED = HexBytes('0x1626ba7e')

export_signature() → HexBytes

Fix offset (s) and append contract_signature at the end of the signature

Returns:

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

is_valid(ethereum_client: EthereumClient, *args) → 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

property owner: ChecksumAddress

Returns:: Address of contract signing. No further checks to get the owner are needed, but it could be a non-existing contract

property signature_type: SafeSignatureType

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

Bases: SafeSignature

is_valid(*args) → 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

property owner

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

property signature_type

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

Bases: SafeSignature

is_valid(*args) → 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

property owner

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

property signature_type

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

class gnosis.safe.safe_signature.SafeSignatureType(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

APPROVED_HASH = 1

CONTRACT_SIGNATURE = 0

EOA = 2

ETH_SIGN = 3

static from_v(v: int)

gnosis.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

gnosis.safe.safe_tx module

class gnosis.safe.safe_tx.SafeTx(ethereum_client: EthereumClient, safe_address: ChecksumAddress, to: ChecksumAddress | None, value: int, data: bytes, operation: 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

gnosis.safe.serializers module

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

Bases: Serializer

validate(data)

validate_operation(value)

class gnosis.safe.serializers.SafeMultisigTxSerializer(*args, **kwargs)

Bases: SafeMultisigEstimateTxSerializer

DEPRECATED, use SafeMultisigTxSerializerV1 instead

class gnosis.safe.serializers.SafeMultisigTxSerializerV1(*args, **kwargs)

Bases: SafeMultisigEstimateTxSerializer

Version 1.0.0 of the Safe changes data_gas to base_gas

class gnosis.safe.serializers.SafeSignatureSerializer(*args, **kwargs)

Bases: Serializer

When using safe signatures v can have more values

check_r(r)

check_s(s)

check_v(v)

validate(data)

validate_v(v)

gnosis.safe.signatures module

gnosis.safe.signatures.get_signing_address(signed_hash: bytes | str, 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

gnosis.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

gnosis.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}

gnosis.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 gnosis.safe.CannotEstimateGas: Bases: SafeServiceException

exception gnosis.safe.CouldNotPayGasWithEther: Bases: InvalidMultisigTx

exception gnosis.safe.InvalidChecksumAddress: Bases: SafeServiceException

exception gnosis.safe.InvalidInternalTx: Bases: InvalidMultisigTx

exception gnosis.safe.InvalidMultisigTx: Bases: SafeServiceException

exception gnosis.safe.InvalidPaymentToken: Bases: SafeServiceException

exception gnosis.safe.InvalidSignaturesProvided: Bases: InvalidMultisigTx

class gnosis.safe.ProxyFactory(*args, version: str = '1.4.1', **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) → 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)

Returns:

EthereumTxSent

get_deploy_function(chain_specific: bool) → 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 gnosis.safe.Safe(address: ChecksumAddress, ethereum_client: EthereumClient, *args, **kwargs)

Bases: SafeCreator, ContractBase

Collection of methods and utilies to handle a Safe

FALLBACK_HANDLER_STORAGE_SLOT = 49122629484629529244014240937346711770925847994644146912111677022347558721749

GUARD_STORAGE_SLOT = 33528237782592280163068556224972516439282563014722366175641814928123294921928

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'

build_multisig_tx(to: ChecksumAddress, value: int, data: bytes, operation: 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 transfered, 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 of Safe transaction
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)
safe_version – Safe version (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

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: 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: 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: 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

get_message_hash(message: str | Hash32) → 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

abstract 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') → str

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

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

retrieve_is_hash_approved(owner: str, 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: str, block_identifier: Literal['latest', 'earliest', 'pending', 'safe', 'finalized'] | BlockNumber | Hash32 | HexStr | HexBytes | int | None = 'latest') → bool

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

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[str]

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

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: 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 –
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:

Tuple(tx_hash, tx)

Raises:

InvalidMultisigTx: If user tx cannot go through the Safe

property simulate_tx_accessor_address: ChecksumAddress

class gnosis.safe.SafeOperationEnum(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

CALL = 0

CREATE = 2

DELEGATE_CALL = 1

exception gnosis.safe.SafeServiceException: Bases: Exception

class gnosis.safe.SafeTx(ethereum_client: EthereumClient, safe_address: ChecksumAddress, to: ChecksumAddress | None, value: int, data: bytes, operation: 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 gnosis.safe.SignatureNotProvidedByOwner: Bases: InvalidMultisigTx