## Safe Protocol

The Safe Protocol is a non-custodial set of smart contracts that allows users to create programmable multi-signature accounts that require multiple parties to authorize transactions. This provides an added layer of security and reduces the risk of funds being lost or stolen compared to regular EOA account.

### Basic flows:

**Deploying a Safe account**

-   A user creates a Safe account by deploying a Proxy contract pointing to the Safe implementation contract. The implementation itself is Proxy-agnostic.
-   The user configures the Safe wallet by setting the number of required signatures and the list of owners.

**Executing a transaction**

-   To sign a transaction, the user generates a Safe transaction hash using the EIP-712 typed structured data hashing scheme.
-   The required amount of parties sign it either with a private key, on-chain approval or a smart contract wallet
-   The user submits the transaction to the Safe account on-chain.

**Updating the owner structure or policies**

-   The implementation contract has self-authorised (can be called by the Safe account itself) methods to update the owner structure or policies of the Safe account.

**Signing a message**
The message can be signed two ways on-chain and off-chain.

-   On-chain signing:
    -   The user generates a Safe message hash using the EIP-712 typed structured data hashing scheme.
    -   The user submits a delegatecall transaction to `SignMessageLib` contract to mark the hash as signed.
    -   The hash now can be verified through the EIP-1271 interface.
-   Off-chain signing:
    -   The user generates a Safe message hash using the EIP-712 typed structured data hashing scheme.
    -   The user signs the message hash with a private key or a smart contract wallet.
    -   The signature now can be verified through the EIP-1271 interface.

### Advanced features

#### Modules

Modules add additional functionalities to the Safe contracts. They are smart contracts that implement the Safe’s functionality while separating module logic from the Safe’s core contract.

A basic Safe does not require any modules. Adding and removing a module requires confirmation from all owners. Events are emitted whenever a module is added or removed and also whenever a module transaction was successful or failed.

> ⚠️ WARNING: Modules are a security risk since they can execute arbitrary transactions,
> so only trusted and audited modules should be added to a Safe. A malicious module can completely takeover a Safe

#### Transaction guards

Transaction guards can make checks before and after a Safe transaction.
The check before a transaction can e.g. programmatically check all of the parameters of the respective transaction prior to execution. The check after a transaction execution can be used to e.g. perform checks on the final state of the Safe.

> ⚠️ IMPORTANT: Since a guard has full power to block Safe transaction execution,
> a broken guard can cause a denial of service for the Safe. Make sure to carefully audit the guard code and design recovery mechanisms.

### Technical Overview

#### Safe Domain Separator

```json
DomainSeparator {
    uint256 chainId;
    address verifyingContract;
}
```

The domain includes the chainId and the address of the Safe account to prevent replay attacks across chains/safes.

#### Safe Transaction

The Safe transaction is defined by the following EIP-712 typed structured data:

```json
SafeTx {
    bytes to;
    uint256 value;
    bytes data;
    Enum.Operation operation;
    uint256 safeTxGas;
    uint256 baseGas;
    uint256 gasPrice;
    address gasToken;
    address refundReceiver;
    uint256 nonce;
}
```

-   to: address of the account to which the transaction is being sent
-   value: value in wei to be sent with the transaction
-   data: data to be sent with the transaction
-   operation: type of operation (0: CALL, 1: DELEGATECALL)
-   safeTxGas: gas that should be used for the Safe transaction
-   baseGas: gas costs for data that needs to be paid for by the Safe regardless of the used gas amount
-   gasPrice: gas price that should be used for the payment calculation
-   gasToken: token address (or 0 if ETH) that is used for the payment
-   refundReceiver: address of receiver of gas payment (or 0 if tx.origin)
-   nonce: unique number to make sure this transaction can only be executed once

#### Safe Transaction Hash

The Safe transaction hash is generated by hashing the Safe transaction with the EIP-712 typed structured data hashing scheme.

#### Safe Transaction Signature

A Safe transaction signature is generated by signing the Safe transaction hash.

To learn more about supported signature formats, please refer to the [Signatures](./signatures.md) documentation.

#### Safe Transaction Gas

For a detailed description of the Safe transaction gas, please refer to the [safeTxGas](./safe_tx_gas.md) documentation.

#### Safe Message

The Safe message is defined by the following EIP-712 typed structured data:

```json
SafeMessage {
    bytes message;
}
```

#### Owner Management

Owners are managed in the `OwnerManager` contract. It uses a linked list to store the owners because the EVM bytecode `solc` generates for a dynamic array is not the most efficient.

The linked list head and tail are the 0x1 address. The head and tail are never removed from the list. The head and tail are never owners.

#### Module Management

Owners are managed in the `ModuleManager` contract. It uses a linked list to store the modules because the EVM bytecode `solc` generates for a dynamic array is not the most efficient.

The linked list head and tail are the 0x1 address. The head and tail are never removed from the list. The head and tail are never modules.

#### Transaction execution

The method `execTransaction` in the Safe.sol contract is the main entry point for executing transactions.
It takes the transaction parameters and nonce/chain id from the chain, generates the Safe transaction hash and verifies the signatures.

If a transaction guard is set, it forwards the transaction to the guard for additional checks. If the guard check passes, it executes the transaction. After the transaction is executed, it forwards the hash and success boolean to the guard.

If the refund parameter is set to true, the Safe will refund the gas costs to the refund receiver. If the refund receiver is set to 0, the Safe will refund the gas costs to the tx.origin.

#### Fallback contract

A Fallback contract contains logic outside of the scope of the core Safe contracts, such as the token callback logic and/or logic that didn't fit into the core contracts because of bytecode size limitations.