Concepts: the Zodiac account model

This page connects the words in the Zodiac App with the objects on the chain. Read this page first. All other pages use these terms.

The product view

In the Zodiac App, you manage a workspace. A workspace contains vaults, policies, and members:

• A vault is a Safe account that holds the assets. See Import a Safe.
• A policy gives members permission for specific actions on a vault. See Create a policy.
• Zodiac Pilot executes transactions through a policy. See Execute a transaction.

Each app word names an onchain object:

The rest of this page explains the contract side: what modules, modifiers, and guards are, and how they connect. When you set up an organization with a constellation or with the app, these are the objects that get deployed and wired for you.

One account, many actors

A Safe requires signatures from its owners for every transaction. That is safe, but slow. Zodiac adds a second path into the Safe: modules. A module can execute transactions through the Safe without owner signatures. Modifiers and guards then put limits on that path.

The four contract types

• Avatar — the account that holds the assets and executes the transactions. In almost all setups, the avatar is a Safe. The avatar exposes the IAvatar interface.
• Module — a contract that the avatar has enabled. A module can tell the avatar to execute transactions. The avatar does not check what a module sends. Only enable modules that you trust or that a modifier limits.
• Modifier — a contract between a module (or an address) and the avatar. A modifier accepts transactions, applies a rule, and forwards the transactions that pass. The Roles Modifier and the Delay Modifier are modifiers.
• Guard — a contract that checks every transaction of an avatar or of a module, before and after execution. A guard cannot start transactions.

A modifier is itself a module from the point of view of the avatar. The avatar must enable the modifier. The modifier then enables its own callers as modules on itself.

The module path into the Safe

Every avatar implements the IAvatar interface. The important function is:

function execTransactionFromModule(
    address to,
    uint256 value,
    bytes memory data,
    Operation operation // 0 = call, 1 = delegate call
) external returns (bool success);

When a module calls this function, the Safe executes the transaction. The full interface also has enableModule, disableModule, isModuleEnabled, and getModulesPaginated. See Build a module for the full interface.

Avatar and target

Every module and every modifier stores two addresses:

• avatar — the account that holds the assets. Conditions such as EqualToAvatar compare against this address.
• target — the address that receives execTransactionFromModule calls from this contract.

In a simple setup, both point to the same Safe. The two addresses differ when you put a modifier in the path. Then the module’s target is the modifier, and the module’s avatar stays the Safe.

Chain of modifiers: Roles and Delay together

Modifiers compose. A common setup gives a team scoped permissions with a mandatory review period:

The wiring for this setup is:

1. The Safe enables the Delay Modifier as a module.
2. The Delay Modifier enables the Roles Modifier as a module.
3. The target of the Roles Modifier is the Delay Modifier. The avatar of both modifiers is the Safe.

Mastercopies and proxies

You do not deploy the full code of a Zodiac tool. You deploy a minimal proxy (EIP-1167) that points to an audited mastercopy. The Module Proxy Factory deploys the proxy and calls setUp with your parameters in one transaction. Each mastercopy version has one canonical address on all supported chains.

See Build a module for the factory details, and Security for the list of safe mastercopy versions.

Next steps

• Set up permissions: Quickstart: Roles
• Add a review period: Quickstart: Delay
• Look up a term: Glossary