Check out the previous articles from this series:

• Gnosis Safe Internals — Part 1 — SafeProxy

• Gnosis Safe Internals — Part 2 — Ownership

Executing transactions

Let’s go back to Safe.sol and look at the execTransaction() function. This function executes the desired transaction on-chain, provided all necessary requirements are met.

function execTransaction(
    address to,
    uint256 value,
    bytes calldata data,
    Enum.Operation operation,
    uint256 safeTxGas,
    uint256 baseGas,
    uint256 gasPrice,
    address gasToken,
    address payable refundReceiver,
    bytes memory signatures
) external payable override returns (bool success) {

The arguments are straightforward:

• To: The address of the smart contract the wallet will interact with.

• Data: The input data for the transaction.

• Operation: 0 for a standard call, 1 for a delegatecall (be careful).

• Gas-related variables: Parameters controlling gas usage.

• Signatures: Approvals required to authorize the transaction.

The first step is to compute the transaction hash. This is what is signed by the owners at the end.

txHash = getTransactionHash( // Transaction info
    to,
    value,
    data,
    operation,
    safeTxGas,
    // Payment info
    baseGas,
    gasPrice,
    gasToken,
    refundReceiver,
    // Signature info
    // We use the post-increment here, so the current nonce value is used and incremented afterwards.
    nonce++
);

This is nearly all the previous parameters and a nonce variable.

Let’s say we want to send 1 USDC on the Gnosis Safe chain to:

• cizeon.eth — 0xffF4aA9E37a3661db92d550936E5e27442aa5fa6

The to argument is the address of the USDC token on the Gnosis chain:

• 0x2a22f9c3b484c3629090FeED35F17Ff8F88f76F0.

Since the second article in this series, we’ve learned how to construct the calldata:

$ cast calldata "transfer(address,uint256)" 0xffF4aA9E37a3661db92d550936E5e27442aa5fa6 1000000
0xa9059cbb000000000000000000000000fff4aa9e37a3661db92d550936e5e27442aa5fa600000000000000000000000000000000000000000000000000000000000f4240

The operation variable is set to 0 since we’re making a standard call.

We’ll set all gas-related variables to 0 and set gasToken and refundReceiver to address(0).

To approve this transaction, we could simply sign all these parameters. This involves an owner using the private key of their externally owned address (EOA), their personal wallet, to generate a digital signature, ensuring the transaction’s authenticity and integrity.

However, this would be highly insecure. The recipient, cizeon.eth, could retrieve the transaction and its signature, then replay it to receive the USDC again and again. To prevent this replay attack, a nonce is used. A nonce is a unique number for each transaction, ensuring that once a transaction is executed, it cannot be used again.

To retrieve the nonce value to use, we can fetch it from the Safe wallet.

$ export ETH_RPC_URL=https://rpc.gnosischain.com
$ cast call 0xE27f243CD5CB7364Bbae758Bb05AA62ec2a5Fb7D "nonce()"
0x0000000000000000000000000000000000000000000000000000000000000001

The nonce value here is one, this will be the first transaction from this Safe wallet.

Domain hash

Now, let’s explore this getTransactionHash() function. It follows the EIP-712 specifications for hashing typed data structures. However, we’ll go through this function line by line for a detailed explanation.

bytes32 domainHash = domainSeparator();

First, it retrieves a domain hash from the domainSeparator() public view function.

// keccak256(
//     "EIP712Domain(uint256 chainId,address verifyingContract)"
// );
bytes32 private constant DOMAIN_SEPARATOR_TYPEHASH = 0x47e79534a245952e8b16893a336b85a3d9ea9fa8c573f3d803afb92a79469218;

function domainSeparator() public view override returns (bytes32) {
    uint256 chainId;
    /* solhint-disable no-inline-assembly */
    /// @solidity memory-safe-assembly
    assembly {
        chainId := chainid()
    }
    /* solhint-enable no-inline-assembly */
    return keccak256(abi.encode(DOMAIN_SEPARATOR_TYPEHASH, chainId, this));
}

The DOMAIN_SEPARATOR_TYPEHASH is just a hash of the EIP712Domain.

$ chisel
Welcome to Chisel! Type `!help` to show available commands.
➜ keccak256("EIP712Domain(uint256 chainId,address verifyingContract)")
Type: bytes32
└ Data: 0x47e79534a245952e8b16893a336b85a3d9ea9fa8c573f3d803afb92a79469218

The chainId in Ethereum is a unique identifier for each Ethereum network or blockchain. If you recall the replay attack explained earlier, cizeon.eth could attempt to replay the transaction, even with the correct nonce, but on a different EVM blockchain. Assuming the target smart contract exists on that other chain. Which could also be malicious!

We can retrieve the chain id using cast.

$ export ETH_RPC_URL=https://rpc.gnosischain.com
$ cast chain-id
100

Lastly, we need the address of the Safe wallet. Again, we want to prevent cizeon.eth from replaying the transaction. Even with the correct nonce value and on the correct chain, if it targets a different Safe wallet owned by the same owner.

We can compute the domainHash ourselves.

$ chisel
➜ keccak256(abi.encode(0x47e79534a245952e8b16893a336b85a3d9ea9fa8c573f3d803afb92a79469218, 100, 0xE27f243CD5CB7364Bbae758Bb05AA62ec2a5Fb7D))
Type: bytes32
└ Data: 0xd6092a6c53243ed8a77ab41647fd6b9c38df40eeaa8c1a259e87e620a9cba646

Since the domainSeparator() function is a public view, we could also have retrieve the domain hash from the wallet.

$ cast call 0xE27f243CD5CB7364Bbae758Bb05AA62ec2a5Fb7D "domainSeparator()"
0xd6092a6c53243ed8a77ab41647fd6b9c38df40eeaa8c1a259e87e620a9cba646

However, it’s better to do the maximum possible off-chain. Hopefully, the hashes match :-).

The domain hash is 0xd6092a6c53243ed8a77ab41647fd6b9c38df40eeaa8c1a259e87e620a9cba646

Message hash

Before we return to the getTransactionHash() function, we need an additional key value: the SAFE_TX_TYPEHASH.

// keccak256(
//     "SafeTx(address to,uint256 value,bytes data,uint8 operation,uint256 safeTxGas,uint256 baseGas,uint256 gasPrice,address gasToken,address refundReceiver,uint256 nonce)"
// );
bytes32 private constant SAFE_TX_TYPEHASH = 0xbb8310d486368db6bd6f849402fdd73ad53d316b5a4b2644ad6efe0f941286d8;

The rest of the getTransactionHash() function is written in assembly.

calldatacopy(ptr, data.offset, data.length)
let calldataHash := keccak256(ptr, data.length)

First, it computes a hash of the calldata, which we crafted earlier to send 1 USDC to cizeon.eth.

$ chisel
keccak256(hex"a9059cbb000000000000000000000000fff4aa9e37a3661db92d550936e5e27442aa5fa600000000000000000000000000000000000000000000000000000000000f4240")
Type: bytes32
└ Data: 0x1133c5be11ee6385513e229829a8b3176a52ee02943ed2406ddf25beffe0b7ec

It then combines all the variables and the SAFE_TX_TYPEHASH into a single packed structure.

mstore(ptr, SAFE_TX_TYPEHASH)
mstore(add(ptr, 32), to)
mstore(add(ptr, 64), value)
mstore(add(ptr, 96), calldataHash)
mstore(add(ptr, 128), operation)
mstore(add(ptr, 160), safeTxGas)
mstore(add(ptr, 192), baseGas)
mstore(add(ptr, 224), gasPrice)
mstore(add(ptr, 256), gasToken)
mstore(add(ptr, 288), refundReceiver)
mstore(add(ptr, 320), _nonce)

The message hash is the result of hashing this structure. We can use chisel again to compute the hash of this structure ourselves.

$ chisel
➜ bytes32 safe_tx_typehash = 0xbb8310d486368db6bd6f849402fdd73ad53d316b5a4b2644ad6efe0f941286d8;
➜ address to = 0x2a22f9c3b484c3629090FeED35F17Ff8F88f76F0;
➜ uint256 value = 0;
➜ bytes32 data_hashed = 0x1133c5be11ee6385513e229829a8b3176a52ee02943ed2406ddf25beffe0b7ec;
➜ uint8 operation = 0;
➜ uint256 safe_tx_gas = 0;
➜ uint256 base_gas = 0;
➜ uint256 gas_price = 0;
➜ address gas_token = address(0);
➜ address refund_receiver = address(0);
➜ uint256 nonce = 1;
➜ keccak256(abi.encode(safe_tx_typehash,to,value,data_hashed,operation,safe_tx_gas,base_gas,gas_price,gas_token,refund_receiver,nonce))
Type: bytes32
└ Data: 0x170fb87d7e389e2d5a22da94d29141f5e15bc4d316decc4d182060c8c2db84ba

The message hash is 0x170fb87d7e389e2d5a22da94d29141f5e15bc4d316decc4d182060c8c2db84ba

safeTxHash

Finally, we need to combine this hash with the EIP-712 prefix and the domain hash, as shown in the getTransactionHash() function.

// Step 3: Calculate the final EIP-712 hash
// First, hash the SafeTX struct (352 bytes total length)
mstore(add(ptr, 64), keccak256(ptr, 352))
// Store the EIP-712 prefix (0x1901), note that integers are left-padded
// so the EIP-712 encoded data starts at add(ptr, 30)
mstore(ptr, 0x1901)
// Store the domain separator
mstore(add(ptr, 32), domainHash)
// Calculate the hash
txHash := keccak256(add(ptr, 30), 66)

Chisel to the rescue again. Note that here we need to use abi.encodePacked() and not abi.encode().

$ chisel
➜ bytes2 prefix = 0x1901;
➜ bytes32 domain_hash = 0xd6092a6c53243ed8a77ab41647fd6b9c38df40eeaa8c1a259e87e620a9cba646;
➜ bytes32 message_hash = 0x170fb87d7e389e2d5a22da94d29141f5e15bc4d316decc4d182060c8c2db84ba;
➜ keccak256(abi.encodePacked(prefix,domain_hash,message_hash))
Type: bytes32
└ Data: 0x6403ca37fa9c54872e827f9da78cbc5818e7386a6bf5cbfb2788277b670ad80a

The txHash is 0x6403ca37fa9c54872e827f9da78cbc5818e7386a6bf5cbfb2788277b670ad80a

This is all we need to sign the transaction :-)

Signing

The sub command with cast is wallet sign. There are several ways to use the private key:

• With -i (interactive mode), you simply need to copy and paste the private key.

• Passing the private key or mnemonic as an argument, though this is not recommended.

• Storing the key on the filesystem and protecting it with a password using cast wallet import.

$ cast wallet sign 0x6403ca37fa9c54872e827f9da78cbc5818e7386a6bf5cbfb2788277b670ad80a -i --no-hash
0x75c0a770c7b65c23fa711c2c6e20332e7fa5c41f46e8f6cc0a089354974bed7d29f6b8e6606d2c11c3f03e7f406678bf40be41fa686d631a92a698becf7ef1df1c

With the signature, we can ask the Gnosis Safe wallet to execute the transaction. I suggest that we simulate the transaction first. This will be done forking the Gnosis chain locally. For that, we will use anvil, also part of the Foundry tool suite.

$ anvil --fork-url https://rpc.gnosischain.com

This creates a new local RPC on 127.0.0.1:8545 by default.

Let’s simulate the final transaction:

export ETH_RPC_URL=http://127.0.0.1:8545

Since the command line is quite long, I recommend creating a simple script to streamline the process. The trace argument will be valuable for understanding the simulated transaction.

export ETH_RPC_URL=http://127.0.0.1:8545

SAFE_WALLET=0xE27f243CD5CB7364Bbae758Bb05AA62ec2a5Fb7D
TO=0x2a22f9c3b484c3629090FeED35F17Ff8F88f76F0
VALUE=0
DATA=0xa9059cbb000000000000000000000000fff4aa9e37a3661db92d550936e5e27442aa5fa600000000000000000000000000000000000000000000000000000000000f4240
OPERATION=0
SAFE_TX_GAS=0
BASE_GAS=0
GAS_PRICE=0
GAS_TOKEN=0x0000000000000000000000000000000000000000
REFUND_RECEIVER=0x0000000000000000000000000000000000000000
SIGNATURE=0x75c0a770c7b65c23fa711c2c6e20332e7fa5c41f46e8f6cc0a089354974bed7d29f6b8e6606d2c11c3f03e7f406678bf40be41fa686d631a92a698becf7ef1df1c
cast call --trace \
    $SAFE_WALLET \
    "execTransaction(address,uint256,bytes,uint8,uint256,uint256,uint256,address,address,bytes)" \
    $TO \
    $VALUE \
    $DATA \
    $OPERATION \
    $SAFE_TX_GAS \
    $BASE_GAS \
    $GAS_PRICE \
    $GAS_TOKEN \
    $REFUND_RECEIVER \
    $SIGNATURE

The result is quite verbose, so I’ve only selected the most relevant part.

❯ sh exec.sh
Traces:
  [59797] 

[...]  
  0x2a22f9c3b484c3629090FeED35F17Ff8F88f76F0::transfer(0xffF4aA9E37a3661db92d550936E5e27442aa5fa6, 1000000 [1e6])
    │   │   ├─ [16263] 0x107CF7fb73EA48D1D200989b156Ce1894d7AfEC7::transfer(0xffF4aA9E37a3661db92d550936E5e27442aa5fa6, 1000000 [1e6]) [delegatecall]
    │   │   │   ├─ emit Transfer(param0: 0xE27f243CD5CB7364Bbae758Bb05AA62ec2a5Fb7D, param1: 0xffF4aA9E37a3661db92d550936E5e27442aa5fa6, param2: 1000000 [1e6])
[...]
└─ ← [Return] 0x0000000000000000000000000000000000000000000000000000000000000001
Transaction successfully executed.
Gas used: 79781

We can see the call to USDC::transfer() with cizeon.eth as the recipient for 1 USDC. The final return value is 1, indicating success.

Now, it’s time to execute this on-chain. Instead of using cast call, we’ll use cast send and provide a private key.

export ETH_RPC_URL=https://rpc.gnosischain.com

SAFE_WALLET=0xE27f243CD5CB7364Bbae758Bb05AA62ec2a5Fb7D
TO=0x2a22f9c3b484c3629090FeED35F17Ff8F88f76F0
VALUE=0
DATA=0xa9059cbb000000000000000000000000fff4aa9e37a3661db92d550936e5e27442aa5fa600000000000000000000000000000000000000000000000000000000000f4240
OPERATION=0
SAFE_TX_GAS=0
BASE_GAS=0
GAS_PRICE=0
GAS_TOKEN=0x0000000000000000000000000000000000000000
REFUND_RECEIVER=0x0000000000000000000000000000000000000000
SIGNATURE=0x75c0a770c7b65c23fa711c2c6e20332e7fa5c41f46e8f6cc0a089354974bed7d29f6b8e6606d2c11c3f03e7f406678bf40be41fa686d631a92a698becf7ef1df1c
cast send --interactive \
    $SAFE_WALLET \
    "execTransaction(address,uint256,bytes,uint8,uint256,uint256,uint256,address,address,bytes)" \
    $TO \
    $VALUE \
    $DATA \
    $OPERATION \
    $SAFE_TX_GAS \
    $BASE_GAS \
    $GAS_PRICE \
    $GAS_TOKEN \
    $REFUND_RECEIVER \
    $SIGNATURE

Once again, the output of the command is quite verbose, so I’ve only selected the relevant part.

The full transaction can be viewed on GnosisScan.

For this article, we used a private key in interactive mode. This is not recommended for production, as if your computer is compromised, malware could access the private key from memory and sign transactions on your behalf. Instead, using a hardware wallet is highly recommended.

Signing using a Ledger key

Personally, I only own a Ledger device, so I’ve focused on signing with a Ledger key.

Directly signing the safeTxHash is not supported by the Ledger key.

$ cast wallet sign 0x6403ca37fa9c54872e827f9da78cbc5818e7386a6bf5cbfb2788277b670ad80a --ledger --no-hash
Error: operation `sign_hash` is not supported by the signer

However, if provided in JSON format, the Ledger device understand EIP-712 and will gladly compute the message hash and the safeTxHash for you.

{
  "domain": {
    "chainId": 100,
    "verifyingContract": "0xE27f243CD5CB7364Bbae758Bb05AA62ec2a5Fb7D"
  },
  "message": {
    "to": "0x2a22f9c3b484c3629090FeED35F17Ff8F88f76F0",
    "value": 0,
    "data": "0xa9059cbb000000000000000000000000fff4aa9e37a3661db92d550936e5e27442aa5fa600000000000000000000000000000000000000000000000000000000000f4240",
    "operation": 0,
    "safeTxGas": 0,
    "baseGas": 0,
    "gasPrice": 0,
    "gasToken": "0x0000000000000000000000000000000000000000",
    "refundReceiver": "0x0000000000000000000000000000000000000000",
    "nonce": 1
  },
  "primaryType": "SafeTx",
  "types": {
    "EIP712Domain": [
      {
        "name": "chainId",
        "type": "uint256"
      },
      {
        "name": "verifyingContract",
        "type": "address"
      }
    ],
    "SafeTx": [
      { "name": "to", "type": "address" },
      { "name": "value", "type": "uint256" },
      { "name": "data", "type": "bytes" },
      { "name": "operation", "type": "uint8" },
      { "name": "safeTxGas", "type": "uint256" },
      { "name": "baseGas", "type": "uint256" },
      { "name": "gasPrice", "type": "uint256" },
      { "name": "gasToken", "type": "address" },
      { "name": "refundReceiver", "type": "address" },
      { "name": "nonce", "type": "uint256" }
    ]
  }
}

$ cast wallet sign --ledger --mnemonic-index 1 --data --from-file transaction.json
0x8a14302c34d390ef6bee8291181677fd1dbbe9a483b1d0c1207b487cb58f54a463bd194075e2917a80258d6596b391ada5831daf4d5bc84b2e6d5d884cb242501b

Make sure to verify the domain hash and message hash displayed on the Ledger with the ones you’ve computed yourself.

And you now have the signature for your transaction: 0x8a14302c34d390ef6bee8291181677fd1dbbe9a483b1d0c1207b487cb58f54a463bd194075e2917a80258d6596b391ada5831daf4d5bc84b2e6d5d884cb242501b

Using the Gnosis Safe frontend

If we had used the official Gnosis front-end, we would have obtained the same information.

1. The USDC recipient

2. The amount of USDC to send

3. The address of the USDC smart contract

4. Operation: call

5. The same domain hash as we have computed ourselves

6. The same message hash

7. The same safeTxHash

And lastly, the same signature from the Ledger key.

That’s it for today! I hope you had as much fun reading this as I did writing it. In a future article, we’ll dive into how signature verification is handled in the smart contract.

Owners and threshold

The implementation contract source code can be found on github.

contract Safe is
    Singleton,
    NativeCurrencyPaymentFallback,
    ModuleManager,
    GuardManager,
    OwnerManager,
    SignatureDecoder,
    SecuredTokenTransfer,
    ISignatureValidatorConstants,
    FallbackManager,
    StorageAccessible,
    ISafe
{

The Safe contracts inherit from multiple other contracts, each containing different wallet functionalities. Today, we will focus on the OwnerManager.

The Gnosis Safe wallet, often referred to as a multi-signature (or multi-sig) wallet, allows multiple owners to manage a single wallet. Transactions can only be executed once a predefined number of owners have approved them. This significantly reduces the risk of a compromised owner, as a quorum of owners must approve transactions.

The source code for the OwnerManager module is is located here.

Several storage variables are declared.

mapping(address => address) internal owners;
uint256 internal ownerCount;
uint256 internal threshold;

First, a mapping from address to address stores the list of owners. If you’re not familiar with Solidity's mappings, think of them as a HashMap or a dictionary in Python, where both the key and the value are addresses here.

The second variable, ownerCount, simply represents the number of owners.

Lastly, the threshold variable defines the number of owners required to approve a transaction. If set to 1, any owner can execute transactions. If set to 2, at least two owners must approve, regardless of the total number of owners.

This was simple. Let’s see how we can retrieve these variables on-chain.

Retrieving the data on-chain

On line 120, there’s a public view function that returns the threshold value. We’ll call it using the cast command from Foundry. If you haven’t installed Foundry yet, refer to the first article for instructions.

Pay close attention here. A solid understanding of this is essential for part 3 of the series.

On Ethereum, a transaction consists of several parameters. Here are the most important ones:

• from: The sender’s address

• to: The recipient’s address

• value: The amount of ETH to send, 0 if none.

• input data: Optional field to include data.

Addresses can also belong to smart contracts. For example, when sending ERC-20 tokens, you’re actually sending a transaction to the ERC-20 smart contract, which then calls the transfer() function with two parameters: the recipient (to) and the amount of tokens to send.

The function to call and its parameters are recorded in the input data field, known as calldata. This is the data passed along by our proxy contract.

To encode the calldata, we need the function’s signature. This consists of the function’s name and the data types of its parameters, separated by commas, no spaces. For the transfer() function of an ERC-20 token, the signature would be:

transfer(address,uint256)

The function’s signature is then hashed using keccak256 and only the first 4 bytes of the hash are taken as function selector.

$ cast keccak256 "transfer(address,uint256)"
 0xa9059cbb2ab09eb219583f4a59a5d0623ade346d962bcd4e46b11da047c9049b

The transfer function selector is: 0xa9059cbb. We would then append an address and an amount. Luckily we can use the cast command to pack this for us, and even send the transaction.

$ cast calldata "transfer(address,uint256)" 0xE27f243CD5CB7364Bbae758Bb05AA62ec2a5Fb7D 10000000
0xa9059cbb000000000000000000000000e27f243cd5cb7364bbae758bb05aa62ec2a5fb7d0000000000000000000000000000000000000000000000000000000000989680

If this transaction is sent to the USDC smart contract, the calldata would be decoded as a call to the transfer() function, instructing it to send 10 USDC to the address 0xE27f243CD5CB7364Bbae758Bb05AA62ec2a5Fb7D.

The observant reader might have guessed that, with just the calldata, it’s impossible to retrieve the function’s signature from the function selector. This is because there’s no way to reverse a hash back to its original data.

However, there are several databases of function selectors, and the most commonly used ones are stored. The transfer() function is on of them.

$ cast 4byte 0xa9059cbb
transfer(address,uint256)

We now have all the pieces needed to retrieve the threshold value from a Safe wallet. We’ll send a transaction to the wallet’s address (the proxy contract) which will borrow the code from the implementation contract containing the OwnerManager module. Are you following so far? 🙂

We can retrieve the function’s signature from the source code on line 120. There are no parameters.

getThreshold()

We don’t need to manually compute the calldata; we’ll simply ask the cast command to send the transaction for us. Since it’s a public view function, no gas is required.

$ export ETH_RPC_URL=https://rpc.gnosischain.com
$ cast call 0xE27f243CD5CB7364Bbae758Bb05AA62ec2a5Fb7D "getThreshold()"
0x0000000000000000000000000000000000000000000000000000000000000001

For this Gnosis Safe wallet, only one owner or signer is needed to meet the threshold.

Similarly, on line 134, there’s a public view function called getOwners(), which returns an array of addresses. To help cast understand the return value, we can specify its type.

$ cast call 0xE27f243CD5CB7364Bbae758Bb05AA62ec2a5Fb7D "getOwners() returns (address[])"
[0x6D5904167423e36A07427340d14804798039D4e6, 0xffF4aA9E37a3661db92d550936E5e27442aa5fa6]

There are two owners, but only one is needed to execute a transaction from the wallet.

This is all we need to know to retrieve information on-chain from a wallet.

How does it work internally?

Since we’re here to learn and understand how things work, let’s take a look at the OwnerManager source code.

The list of owners is stored in an address to address mapping and unlike an array, it is not possible to simply loop through each elements of the array.

mapping(address => address) internal owners;

The Gnosis Safe developers have done it in a very similar way that a linked list. A linked list is a data structure where each element contains a value and a reference to the next element in the sequence.

Let’s observe the getOwners() funtion.

address internal constant SENTINEL_OWNERS = address(0x1);

function getOwners() public view override returns (address[] memory) {
    address[] memory array = new addressUnsupported embed;
    // populate return array
    uint256 index = 0;
    address currentOwner = owners[SENTINEL_OWNERS];
    while (currentOwner != SENTINEL_OWNERS) {
        array[index] = currentOwner;
        currentOwner = owners[currentOwner];
        ++index;
    }
    return array;
}

1. First, it reads the address stored in the mapping for address(0x1), which gives the address of the first owner.

2. Then, it reads the address stored at the first owner’s address, revealing the second owner’s address.

3. This process continues until the last owner points back to address(0x1).

In this way, it’s possible to loop through each owner in the mapping while remaining gas-efficient.

As we saw in our first article, the cast command allows us to retrieve on-chain storage, even if the value is private. Remember, with the EVM, nothing is truly private. But before we dive in, we need to understand how mappings are stored in storage.

The EVM storage is essentially a large array of 256-bit elements, starting at index 0 up to 2²⁵⁶. Each storage variables are stored one after each others. We can simply count each variables to find its slot number. This is why, to get the address of the singleton contract, we instructed cast to fetch storage at index 0.

$ cast storage 0xE27f243CD5CB7364Bbae758Bb05AA62ec2a5Fb7D 0
0x00000000000000000000000029fcb43b46531bca003ddc8fcb67ffe91900c762

If the source code of the smart-contract was also published to Etherscan or Gnosisscan here, cast can count the slots number for us.

$ export ETHERSCAN_API_KEY=**********************************
$ cast storage 0xE27f243CD5CB7364Bbae758Bb05AA62ec2a5Fb7D --proxy 0x29fcb43b46531bca003ddc8fcb67ffe91900c762
╭-----------------------+------------------------------------------+------+
| Name                  | Type                                     | Slot |
+==========================================================================
| singleton             | address                                  | 0    |
|-----------------------+------------------------------------------+------+
| modules               | mapping(address => address)              | 1    |
|-----------------------+------------------------------------------+------+
| owners                | mapping(address => address)              | 2    |
|-----------------------+------------------------------------------+------+
| ownerCount            | uint256                                  | 3    |
|-----------------------+------------------------------------------+------+
| threshold             | uint256                                  | 4    |
|-----------------------+------------------------------------------+------+
| nonce                 | uint256                                  | 5    |
|-----------------------+------------------------------------------+------+
| _deprecatedDomainSeparator | bytes32                             | 6    |
|-----------------------+------------------------------------------+------+
| signedMessages        | mapping(bytes32 => uint256)              | 7    |
|-----------------------+------------------------------------------+------+
| approvedHashe  | mapping(address => mapping(bytes32 => uint256)) | 8    |
╰-----------------------+------------------------------------------+------+

If the proxy argument isn’t available in your version of Foundry, simply enter the address of the singleton contract instead. The command output here is truncated for clarity.

We now know that the owner’s mapping is stored in the second slot. However, the entire mapping can’t fit in 256 bits. In fact, this variable serves only as a placeholder, and what’s actually stored inside isn’t relevant.

$ cast storage 0xE27f243CD5CB7364Bbae758Bb05AA62ec2a5Fb7D 2
0x0000000000000000000000000000000000000000000000000000000000000000

Rather, the mapping’s values are stored in different slot numbers that we need to compute. For that we need to concatenate the key value with the mapping’s slot number, two in this case. The hash of it is used as the slot number. Let’s use the chisel command also from Foundry. Chisel is a Solidity REPL (Read-Eval-Print-Loop) tool. It evaluates Solidity code and returns the result.

The first key value for our mapping is address(0x1), the SENTINEL_OWNERS constant. We need to concatenate it with the mapping’s slot number.

$ chisel
Welcome to Chisel! Type `!help` to show available commands.
➜ abi.encode(1,2)
Type: dynamic bytes
├ Hex (Memory):
├─ Length ([0x00:0x20]): 0x0000000000000000000000000000000000000000000000000000000000000040
├─ Contents ([0x20:..]): 0x00000000000000000000000000000000000000000000000000000000000000010000000000000000000000000000000000000000000000000000000000000002
├ Hex (Tuple Encoded):
├─ Pointer ([0x00:0x20]): 0x0000000000000000000000000000000000000000000000000000000000000020
├─ Length ([0x20:0x40]): 0x0000000000000000000000000000000000000000000000000000000000000040
└─ Contents ([0x40:..]): 0x00000000000000000000000000000000000000000000000000000000000000010000000000000000000000000000000000000000000000000000000000000002

Let’s compute the hash. This is our slot number.

➜ keccak256(abi.encode(1,2))
Type: bytes32
└ Data: 0xe90b7bceb6e7df5418fb78d8ee546e97c83a08bbccc01a0644d599ccd2a7c2e0

If correct that value at this slot number should be our first owner.

$ cast storage 0xE27f243CD5CB7364Bbae758Bb05AA62ec2a5Fb7D 0xe90b7bceb6e7df5418fb78d8ee546e97c83a08bbccc01a0644d599ccd2a7c2e0
0x0000000000000000000000006d5904167423e36a07427340d14804798039d4e6

If we want to retrieve the address of the second owner, we need to compute the slot number.

$ chisel
keccak256(abi.encode(0x6d5904167423e36a07427340d14804798039d4e6,2))
Type: bytes32
└ Data: 0x9af88d12773e5e18abf0cac977452a5c1dbfefcdef018154daf5409a67cd4bfe

Let’s retrieve the second owner’s address from the contract’s storage.

$ cast storage 0xE27f243CD5CB7364Bbae758Bb05AA62ec2a5Fb7D  0x9af88d12773e5e18abf0cac977452a5c1dbfefcdef018154daf5409a67cd4bfe
0x000000000000000000000000fff4aa9e37a3661db92d550936e5e27442aa5fa6

We already know there are only two owners for this wallet, the address of the third mapping slot should be address(0x1).

$ chisel
➜ keccak256(abi.encode(0xfff4aa9e37a3661db92d550936e5e27442aa5fa6,2))
Type: bytes32
└ Data: 0x7e0181350b9666b922b76c7918cbfa0c8b34d0de78f3a35620d03967f396f283
$ cast storage 0xE27f243CD5CB7364Bbae758Bb05AA62ec2a5Fb7D 0x7e0181350b9666b922b76c7918cbfa0c8b34d0de78f3a35620d03967f396f283
0x0000000000000000000000000000000000000000000000000000000000000001

The loop is closed :-).

Changing owners

Lastly, we can see there are a couple of internal functions to setup owners.

function setupOwners(address[] memory _owners, uint256 _threshold) internal {
function addOwnerWithThreshold(address owner, uint256 _threshold) public override authorized {
function removeOwner(address prevOwner, address owner, uint256 _threshold) public override authorized {
function swapOwner(address prevOwner, address oldOwner, address newOwner) public override authorized {

They are all protected by the authorized modifier.

function requireSelfCall() private view {
    if (msg.sender != address(this)) revertWithError("GS031");
}

modifier authorized() {
    // Modifiers are copied around during compilation. This is a function call as it minimized the bytecode size
    requireSelfCall();
    _;
}

Only the Gnosis Safe wallet itself has the ability to change the owners.

Several other protections are also implemented:

// Owner address cannot be null, the sentinel or the Safe itself.
if (newOwner == address(0) || newOwner == SENTINEL_OWNERS || newOwner == address(this)) revertWithError("GS203");

An owner cannot be address(0x0) or address(0x1), nor can it be the wallet itself.

// No duplicate owners allowed.
if (owners[owner] != address(0)) revertWithError("GS204");

Duplicates owners are also not permitted.

If the owner’s list needs to be updated, the transaction must go through the transaction signing process and reach the quorum to be executed on-chain.

This is what we need to explore next: how transactions that must be executed by the smart contract are encoded, signed, and then executed.

We’ll dive into this in the next article of the series. Stay tuned!

This blog series explores the Gnosis Safe wallet and how it works, giving readers the chance to use it directly on-chain without relying on a front-end.

If you want to follow along and experiment, I highly recommend installing Foundry. It provides powerful commands like cast and chisel, which we’ll be using extensively.

Installation is straightforward, but refer to the official manual for full details:

curl -L https://foundry.paradigm.xyz | bash

We’ll also be using the Gnosis Chain. You can set up a public RPC by exporting an environment variable:

export ETH_RPC_URL=https://rpc.gnosischain.com

The first key concept is that a Gnosis Safe wallet is simply a proxy contract. It’s a minimal contract used only for storing data while borrowing code from other smart contracts. This design enables upgrades and enhances modularity.

There are several design patterns in Solidity for proxy contracts such as the Transparent Proxy Pattern, Proxy Upgrade Pattern, EIP-1967 for storage collision, or the Diamond Pattern.

The approach used by Gnosis Safe can be observed from the SafeProxy.sol contract: https://github.com/safe-global/safe-smart-account/blob/main/contracts/proxies/SafeProxy.sol

The first storage slot stores the address of a singleton contract, which handles the execution of code.

// Singleton always needs to be first declared variable, to ensure that it is at the same location in the contracts to which calls are delegated.
// To reduce deployment costs this variable is internal and needs to be retrieved via `getStorageAt`
address internal singleton;

Let’s investigate this Safe wallet deployed on Gnosis: 0xE27f243CD5CB7364Bbae758Bb05AA62ec2a5Fb7D.

The singleton contract’s address is stored in an internal variable called singleton. Fortunately, the cast command can retrieve this storage for us.

$ cast storage 0xE27f243CD5CB7364Bbae758Bb05AA62ec2a5Fb7D 0
0x00000000000000000000000029fcb43b46531bca003ddc8fcb67ffe91900c762

In the EVM, storage slots are 256 bits (32 bytes), while addresses are only 160 bits (20 bytes). To extract the address, we simply take the last 160 bits, which gives us 0x29fcb43b46531bca003ddc8fcb67ffe91900c762 as the singleton’s address. This is indeed a SafeL2 contract.

Gnosis Safe implementation has two contracts: Safe.sol and SafeL2.sol. The SafeL2 contract is identical to the Safe contract but also emits events on transaction execution. Since L2s are generally cheaper, the extra gas cost is acceptable. In this article, we’ll focus on the Safe contract.

We know that the address of a Gnosis Safe wallet corresponds to the proxy contract’s address. We also know how to retrieve the address of the implementation contract, which contains the code to be executed. But how does the proxy actually execute the code?

This is achieved through the fallback() function of the proxy contract, combined with the use of delegate calls.

In EVM smart contracts, a fallback() function is a special function that is triggered when a contract receives a transaction or call that doesn’t match any of its defined functions.

For example, if we attempt to call the transfer() function from an ERC-20 contract, but our contract doesn’t implement it, the fallback() function will be triggered. Assuming we have a fallback() function defined, of course.

If we try to call the approve() function and it’s also not implemented in our contract, the fallback() function will be triggered once again. It acts as a catch-all for any unmatched function calls.

The second concept to understand is a delegatecall(). It s a low-level function that allows a contract to execute code in the context of another contract. It typically borrows code from another smart contract, but all storage modifications are made in the calling contract: the proxy contract.

We have the two essentials components of a proxy smart contract. A catch all fallback() function and a way to borrow code from another smart contract.

From SafeProxy.sol on line 32:

/// @dev Fallback function forwards all transactions and returns all received return data.
fallback() external payable {
    // Note that this assembly block is **intentionally** not marked as memory-safe. First of all, it isn't memory
    // safe to begin with, and turning this into memory-safe assembly would just make it less gas efficient.
    // Additionally, we noticed that converting this to memory-safe assembly had no affect on optimizations of other
    // contracts (as it always gets compiled alone in its own compilation unit anyway).
    /* solhint-disable no-inline-assembly */
    assembly {
        let _singleton := sload(0)
        // 0xa619486e == bytes4(keccak256("masterCopy()")). The value is right padded to 32-bytes with 0s
        if eq(calldataload(0), 0xa619486e00000000000000000000000000000000000000000000000000000000) {
            // We mask the singleton address when handling the `masterCopy()` call to ensure that it is correctly
            // ABI-encoded. We do this by shifting the address left by 96 bits (or 12 bytes) and then storing it in
            // memory with a 12 byte offset from where the return data starts. Note that we **intentionally** only
            // do this for the `masterCopy()` call, since the EVM `DELEGATECALL` opcode ignores the most-significant
            // 12 bytes from the address, so we do not need to make sure the top bytes are cleared when proxying
            // calls to the `singleton`. This saves us a tiny amount of gas per proxied call.
            mstore(0x0c, shl(96, _singleton))
            return(0, 0x20)
        }
        calldatacopy(0, 0, calldatasize())
        let success := delegatecall(gas(), _singleton, 0, calldatasize(), 0, 0)
        returndatacopy(0, 0, returndatasize())
        if iszero(success) {
            revert(0, returndatasize())
        }
        return(0, returndatasize())
    }
    /* solhint-enable no-inline-assembly */
}

This code is written in YUL, an EVM assembly language. It’s a bit harder to read than plain Solidity, but we’ll break it down and explain it line by line.

1. First, on line 40, the code loads storage slot 0, where the address of the singleton is stored. We will skip the optimisation.

2. On line 52, it copies the calldata from the transaction into memory slot 0.

3. Then, on line 53, it calls the contract pointed to by the singleton address, using the copied calldata in memory slot 0. It’s a delegate call, so any storage changes occur in this contract.

4. On line 54, the returned data from the delegatecall() is copied back into memory slot 0.

5. Finally, on line 56, the transaction is reverted if the call didn’t succeed.

Understand this, the contract address stored in the singleton variable on storage slot 0 is crucial. It typically stores the address of the latest implementation from Gnosis Safe, and can be updated to a newer version.

However, if it’s changed to a malicious contract, anything could happen to the safe wallet, including the loss of all assets protected by the smart contract. Unfortunately, this is exactly what the Bybit team signed. A harmful update to the singleton variable, pointing it to a malicious drainer contract.

That’s all for today! In the next article, we’ll explore how Safe wallets manage multiple owners and how we can retrieve the owner list directly on-chain.