# Storage Layout \[How Shield storage layout is protected across beacon upgrades.]

Shield clones are `BeaconProxy` instances that share the beacon's current implementation's storage layout slot-for-slot. A layout change that is not append-only corrupts every existing Shield the moment `beacon.upgradeTo(newImpl)` runs, and the stock beacon has no rollback, so storage changes are treated as live-upgrade safety changes.

## Rule

The layout is append-only:

* Existing slots cannot move.
* Existing slots cannot change type.
* Existing slots cannot be deleted.
* New storage variables go after the existing layout.

If a change needs to reorder, retype, or remove storage, it cannot ship as a beacon upgrade: deploy a new implementation behind a new beacon and factory. Curators opt in by deploying new clones.

## Snapshot

The canonical snapshot is `contracts/.storage-layouts/Shield.json` in the Shield repo. It is regenerated from compiled artifacts:

```bash
cd contracts
forge inspect Shield storage-layout --json > .storage-layouts/Shield.json
```

The snapshot records each field's contract, label, slot, offset, and type, plus the type map.

## CI Checks

The Shield repository runs two storage-layout checks:

| Check | What it catches |
| --- | --- |
| Append-only validator | Any changed label, slot, offset, or type for existing entries, plus inserted entries below the baseline tail. |
| Freshness check | A stale committed snapshot that no longer matches `forge inspect`. |

Both must pass before a layout-affecting PR can merge.

## Inherited Storage

Shield inherits `ReentrancyGuardUpgradeable` and `NewtonPolicyClient`. Changes in either inherited contract can still move the effective layout, so the snapshot intentionally catches upstream dependency drift as well as edits to `Shield.sol`.
