> For the complete documentation index, see [llms.txt](https://docs.ante.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ante.org/technical-stuff/how-a-vault-is-wired.md).

# How a vault is wired

How an Ante vault's contracts fit together: permissions, check-in, grace period, cancelling a handoff.

A vault is a Safe owned by the holder with one module enabled: the Delay. Everything else hangs off the Delay or the guardian Safe. Guardians have exactly one permission: queue one pinned handoff payload while the dead man's switch reports the owner dead. Every module is owned by the vault, and Ante holds no key over any of them. Addresses are on [Technical Stuff & Deployed Contracts](https://docs.ante.org/technical-stuff.md).

## Where each module sits

<figure><img src="https://3625867833-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FMkTsRaI2jBZJJikq4M3p%2Fuploads%2FtXsM7mlGkI7mfwbBeK4l%2Flayout-modules.svg?alt=media" alt="Module placement"><figcaption><p>Solid arrows read "is enabled on" (for a Roles modifier, also its target). Dashed arrows are membership or a condition.</p></figcaption></figure>

* **Delay**: the only module enabled on the vault. It holds the handoff queue and enforces the grace period.
* **Guardian Roles** (Roles modifier): enabled on the Delay, with the Delay as its target, and the only account that can queue. The guardian Safe holds the GUARDIAN\_1 role. The rule allows exactly one call, `vault.enableModule(recoveryRoles)`, with the DMS as a custom condition.
* **DMS**: the check-in timer. It answers the guardian rule's condition: the call passes only while the owner has missed a check-in.
* **Recovery Roles** (Roles modifier): enabled on the vault only once a handoff lands. The recipient and the guardian proxies hold RECOVERER\_1 and may move allowed assets to the recipient, nowhere else. See [What a handoff can move](https://docs.ante.org/technical-stuff/how-a-vault-is-wired.md#what-a-handoff-can-move).
* **Guardian Safe**: owned by the per-guardian proxy Safes (1-of-1). The vault is enabled as a module on it, which is how the holder adds or removes guardians and changes the threshold.
* **ScopeGuard**: the guard on the guardian Safe. Guardians can only call guardianRoles; they cannot run arbitrary transactions or remove themselves. It also refuses ETH transfers and delegate calls from the guardian Safe.

## Check-in interval and grace period

Two timers protect a vault. They are set on different contracts and run one after the other.

|                  | Check-in interval             | Grace period                                     |
| ---------------- | ----------------------------- | ------------------------------------------------ |
| Set on           | DMS (`checkInInterval`)       | Delay (`txCooldown`)                             |
| Default          | 6 months (183 days)           | 6 months (183 days)                              |
| Starts           | At your last check-in         | When guardians queue a handoff                   |
| When it runs out | Guardians can start a handoff | Anyone can execute the handoff                   |
| What you can do  | Check in to reset it          | Check in from the Ante app to cancel the handoff |

A queued handoff never expires on its own (the Delay's expiration is 0).

## Starting a handoff

<figure><img src="https://3625867833-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FMkTsRaI2jBZJJikq4M3p%2Fuploads%2FWwCZMZOYHqkJkd86o5pn%2Flayout-handoff.svg?alt=media" alt="Start-handoff call path"><figcaption><p>The path a guardian's signature takes to the Delay queue, and what happens after the grace period.</p></figcaption></figure>

A Zodiac modifier calls `execTransactionFromModule` on its target directly, so the Delay sees guardianRoles as the sender. The guardian Safe never touches the Delay. The queued entry is always the same bytes: `{ to: vault, value: 0, data: enableModule(recoveryRoles), operation: Call }`.

After the grace period, anyone can call `Delay.executeNextTx(...)`. The vault enables recoveryRoles, and the recipient and guardians transfer the allowed assets via `execTransactionWithRole(RECOVERER_1)`. The owner can cancel at any point before that; see [Cancelling a handoff](https://docs.ante.org/technical-stuff/how-a-vault-is-wired.md#cancelling-a-handoff).

## What a handoff can move

Each asset the holder chooses to hand off becomes one rule on Recovery Roles:

| Asset        | What RECOVERER\_1 may do                                                  |
| ------------ | ------------------------------------------------------------------------- |
| ERC-20 token | Call `transfer(to, amount)` on that token, with `to` set to a recipient.  |
| Native ETH   | Send ETH to a recipient's address. ETH moves as ETH; it is never wrapped. |

Roles checks the ETH value of every call it allows. ETH sent to any other address, or attached to a token call, is rejected. An asset with no rule doesn't move. A rule names an asset, not an amount: once a handoff lands, the full balance of each allowed asset can go to the recipient.

## Cancelling a handoff

Checking in from the Ante app sends one transaction from the vault that does up to three things:

1. `DMS.checkIn()` resets the timer, so guardians can't queue a new handoff.
2. `Delay.setTxNonce(queueNonce)` skips every entry still in the queue, so a queued handoff can never run.
3. If a handoff already landed, `vault.disableModule(recoveryRoles)` removes the recipient's permissions. Transfers already made stay with the recipient.

`checkIn()` on its own does not cancel a handoff that is already queued: the DMS is checked when a handoff is queued, not when it runs. If you check in outside the Ante app, also call `setTxNonce` on the Delay with its current `queueNonce`.

## Editing guardians

<figure><img src="https://3625867833-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FMkTsRaI2jBZJJikq4M3p%2Fuploads%2FySQEjh1mRHMtXzSKnkw0%2Flayout-guardians.svg?alt=media" alt="Guardian edit path"><figcaption><p>The vault calls the guardian Safe directly as one of its modules.</p></figcaption></figure>

The vault controls the guardian Safe's owner set, threshold and guard. Adding a guardian, removing one, changing the threshold and setting the ScopeGuard are one module call each from the vault.

## Changing a recipient

Changing a recipient revokes the old recipient's RECOVERER\_1 role and their ETH and token rules in the same transaction. A queued handoff names no recipient: it only enables Recovery Roles, so it always pays out under the settings in force when it runs.

## Creating a vault

<figure><img src="https://3625867833-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FMkTsRaI2jBZJJikq4M3p%2Fuploads%2FLRf3pPgN0R1MqaaxB2EF%2Flayout-create.svg?alt=media" alt="Two-stage create"><figcaption><p>The modules stage knows nothing about people. The people stage's first write is the witness.</p></figcaption></figure>

The setup is built in two stages, modules then people. How they are sent depends on what owns the vault:

* **A key**, such as your Ante wallet's: both stages go out in one transaction, so the vault exists with its people or not at all.
* **A smart account**: two ERC-4337 operations, modules first, because a bundler won't carry the whole setup in one operation once EIP-8037 reprices new state. Between the two the vault exists but is inert: its modules have no members, so nobody but the owner can act on it.

**Stage 1, modules.** Deploy recoveryRoles, Delay, DMS, ScopeGuard and guardianRoles (owner = vault, avatar = target = Delay); enable the Delay on the vault and guardianRoles on the Delay. Five deployments, two enables. Every address derives from the vault, so a reloaded session rebuilds the next stage from the vault address alone, and the app reads a vault the same way however it was sent.

**Stage 2, people.** The first write is `ScopeGuard.setTargetAllowed(guardianRoles)`, the witness the app reads to tell "people not yet named" from "done". Then: assign RECOVERER\_1 and scope allowances on recoveryRoles; deploy the per-guardian proxy Safes; deploy the guardian Safe with the vault enabled as its module; assign RECOVERER\_1 to each proxy; set the ScopeGuard on the guardian Safe; check the vault in (`DMS.checkIn()`), so the first check-in interval starts when the guardian can first act; scope the guardian rule (`scopeTarget(vault)`, `scopeFunction(enableModule)`); assign GUARDIAN\_1 to the guardian Safe.

There is no `setDefaultRole` anywhere. Modules are classified by owner and target, and every caller names its role explicitly. The people stage also checks that every module it scopes has code, so a stage built against the wrong addresses fails instead of landing empty.

## Transactions that need several keys

When a vault needs more than one key, Ante's server holds the pending transaction and its signatures until enough keys have signed: one per vault, at the vault's current nonce. Each key signs the Safe transaction. A connected wallet, such as a hardware wallet, signs the EIP-712 `SafeTx`; the Ante wallet signs its hash; a legacy Ante wallet approves the hash on the vault (`approveHash`), whether it starts the transaction or signs one another key started. The app treats what the server returns as data to check: it recomputes the hash from the transaction's fields, and counts a signature only if it recovers to one of the vault's `getOwners()` or `approvedHashes(owner, hash)` is set. Once enough keys have signed, an Ante wallet executes it with `execTransaction`.

Cancelling one that is still short of signatures costs nothing. One with every signature could be executed by anyone holding them, so it is cancelled by a rejection at the same nonce, which the same number of keys sign.

A transaction started in Safe{Wallet} lives in Safe's Transaction Service, which Ante doesn't read, so it doesn't show in Ante and is finished in Safe{Wallet}. If it takes the same nonce as the transaction Ante holds, whichever is executed first runs, and the other can't.

## What each party can do

| Party           | Can do                                                                                |
| --------------- | ------------------------------------------------------------------------------------- |
| Vault owner     | Everything: owns every module, checks in, cancels a handoff, rescopes, disables.      |
| Guardian quorum | Queue the one pinned payload while the DMS reports dead. Nothing else.                |
| Recipient       | After the handoff lands: transfer the allowed assets to themselves via recoveryRoles. |
| Anyone          | Execute a queued entry once the grace period has passed.                              |
