# Gated Deposit Contract (v2)
> **Repository:** [pk910/gated-deposit-contract](https://github.com/pk910/gated-deposit-contract)
> **Genesis Generator PR:** [ethpandaops/ethereum-genesis-generator#248](https://github.com/ethpandaops/ethereum-genesis-generator/pull/248)
---
## 🌐 Introduction
The Gated Deposit Contract is a permissioned variant of the official Ethereum deposit contract.
It adds a token-based gating mechanism that allows testnet operators to control who can deposit validators on the network.
This system is designed primarily for permissioned networks like Sepolia — and in particular, for the upcoming Sepolia replacement network launching next year.
It replaces the current gated deposit system, which introduced architectural deviations from the mainnet deposit contract and has caused compatibility issues with network upgrades (e.g., during the Electra fork).
The new design ensures full mainnet compatibility while still enforcing controlled access to deposits — solving the historical problems caused by earlier gating implementations.
---
## 🧩 Summary
| Component | Address | Description |
|------------|----------|-------------|
| **Gated Deposit Contract** | `0x00000000219ab540356cBB839Cbe05303d7705Fa` | Handles validator deposits; identical to mainnet deposit contract except for a gating check. |
| **Gating Token Contract** | `0x00000000A11Acc355c0dE0000A11aCC355C0DE00` | ERC20-compatible token used to grant permission for validator deposits. |
**Key features:**
- Fully compatible with the mainnet deposit contract (same events, tree structure, and hashing).
- Gating enforced via an external ERC20 token contract.
- Token is **burned (1 per validator deposit)** upon deposit.
- **Top-ups** (additional deposits to existing validators) are **not gated**.
- Admins can **mint tokens** and **manage other admins** via on-chain roles.
---
## ⚙️ Architectural Overview
The architecture is built around two contracts, designed for clean separation of concerns and minimal deviation from Ethereum mainnet logic.
### 1. GatedDepositContract
- Directly based on the official Ethereum 2.0 deposit contract.
- Adds only a **single external call** to the gater contract before processing a deposit:
```solidity
depositGater.check_deposit(msg.sender, msg.value);
```
- This preserves all core behavior:
- Same deposit data validation rules
- Identical Merkle tree hashing
- Standard deposit event signatures
- No custom or extra events (preventing issues during consensus upgrades)
### 2. TokenDepositGater
- Implements a simple ERC20 token for gating.
- Handles:
- Token minting & burning (1 token per new validator deposit)
- Access control via admin role
- Logic to skip burns for top-up deposits
- The deposit contract is allowed it to perform controlled burns.
## 🧾 Genesis Deployment — Allocations
The following genesis allocations define the predeployments and initial storage for both contracts.
This configuration wires the deposit contract to the gater (via storage slot `0x41`) and seeds the token contract with name/symbol and role permissions.
**Add this to your genesis state (geth-style `alloc`)**:
```json
{
"alloc": {
"0x00000000219ab540356cBB839Cbe05303d7705Fa": {
"balance": "0",
"code": "0x60806040526004361061003e575f3560e01c806301ffc9a7146100425780632289511814610076578063621fd1301461008b578063c5f2892f146100ac575b5f5ffd5b34801561004d575f5ffd5b5061006161005c366004610e46565b6100ce565b60405190151581526020015b60405180910390f35b610089610084366004610ed1565b610166565b005b348015610096575f5ffd5b5061009f610ac9565b60405161006d9190610fa6565b3480156100b7575f5ffd5b506100c0610adb565b60405190815260200161006d565b5f7fffffffff0000000000000000000000000000000000000000000000000000000082167f01ffc9a700000000000000000000000000000000000000000000000000000000148061016057507fffffffff0000000000000000000000000000000000000000000000000000000082167f8564090700000000000000000000000000000000000000000000000000000000145b92915050565b603086146101e15760405162461bcd60e51b815260206004820152602660248201527f4465706f736974436f6e74726163743a20696e76616c6964207075626b65792060448201527f6c656e677468000000000000000000000000000000000000000000000000000060648201526084015b60405180910390fd5b602084146102575760405162461bcd60e51b815260206004820152603660248201527f4465706f736974436f6e74726163743a20696e76616c6964207769746864726160448201527f77616c5f63726564656e7469616c73206c656e6774680000000000000000000060648201526084016101d8565b606082146102cd5760405162461bcd60e51b815260206004820152602960248201527f4465706f736974436f6e74726163743a20696e76616c6964207369676e61747560448201527f7265206c656e677468000000000000000000000000000000000000000000000060648201526084016101d8565b670de0b6b3a764000034101561034b5760405162461bcd60e51b815260206004820152602660248201527f4465706f736974436f6e74726163743a206465706f7369742076616c7565207460448201527f6f6f206c6f77000000000000000000000000000000000000000000000000000060648201526084016101d8565b610359633b9aca0034610fcc565b156103cc5760405162461bcd60e51b815260206004820152603360248201527f4465706f736974436f6e74726163743a206465706f7369742076616c7565206e60448201527f6f74206d756c7469706c65206f6620677765690000000000000000000000000060648201526084016101d8565b5f6103db633b9aca0034610ff3565b905067ffffffffffffffff81111561045b5760405162461bcd60e51b815260206004820152602760248201527f4465706f736974436f6e74726163743a206465706f7369742076616c7565207460448201527f6f6f20686967680000000000000000000000000000000000000000000000000060648201526084016101d8565b60415473ffffffffffffffffffffffffffffffffffffffff161561051f576041546040517fc174892800000000000000000000000000000000000000000000000000000000815273ffffffffffffffffffffffffffffffffffffffff9091169063c1748928906104dd9033908c908c908c908c908c908c90349060040161102f565b6020604051808303815f875af11580156104f9573d5f5f3e3d5ffd5b505050506040513d601f19601f8201168201806040525081019061051d919061109c565b505b5f61052982610c9c565b90507f649bbc62d0e31342afea4e5cd82d4049e7e1ee912fc0889aa790803be39038c589898989858a8a61055e602054610c9c565b6040516105729897969594939291906110bb565b60405180910390a15f60028a8a5f60801b6040516020016105959392919061112d565b60408051601f19818403018152908290526105af9161117a565b602060405180830381855afa1580156105ca573d5f5f3e3d5ffd5b5050506040513d601f19601f820116820180604052508101906105ed9190611185565b90505f6002806106006040848a8c61119c565b6040516020016106119291906111c3565b60408051601f198184030181529082905261062b9161117a565b602060405180830381855afa158015610646573d5f5f3e3d5ffd5b5050506040513d601f19601f820116820180604052508101906106699190611185565b6002610678896040818d61119c565b60405161068b9291905f906020016111d2565b60408051601f19818403018152908290526106a59161117a565b602060405180830381855afa1580156106c0573d5f5f3e3d5ffd5b5050506040513d601f19601f820116820180604052508101906106e39190611185565b60408051602081019390935282015260600160408051601f198184030181529082905261070f9161117a565b602060405180830381855afa15801561072a573d5f5f3e3d5ffd5b5050506040513d601f19601f8201168201806040525081019061074d9190611185565b90505f600280848c8c604051602001610768939291906111e4565b60408051601f19818403018152908290526107829161117a565b602060405180830381855afa15801561079d573d5f5f3e3d5ffd5b5050506040513d601f19601f820116820180604052508101906107c09190611185565b6040516002906107d89088905f9088906020016111fd565b60408051601f19818403018152908290526107f29161117a565b602060405180830381855afa15801561080d573d5f5f3e3d5ffd5b5050506040513d601f19601f820116820180604052508101906108309190611185565b60408051602081019390935282015260600160408051601f198184030181529082905261085c9161117a565b602060405180830381855afa158015610877573d5f5f3e3d5ffd5b5050506040513d601f19601f8201168201806040525081019061089a9190611185565b90508581146109375760405162461bcd60e51b815260206004820152605460248201527f4465706f736974436f6e74726163743a207265636f6e7374727563746564204460448201527f65706f7369744461746120646f6573206e6f74206d6174636820737570706c6960648201527f6564206465706f7369745f646174615f726f6f74000000000000000000000000608482015260a4016101d8565b60016109456020600261130a565b61094f9190611315565b602054106109c55760405162461bcd60e51b815260206004820152602160248201527f4465706f736974436f6e74726163743a206d65726b6c6520747265652066756c60448201527f6c0000000000000000000000000000000000000000000000000000000000000060648201526084016101d8565b600160205f8282546109d79190611328565b90915550506020545f5b6020811015610ab05781600116600103610a1757825f8260208110610a0857610a0861133b565b015550610ac095505050505050565b60025f8260208110610a2b57610a2b61133b565b0154604080516020810192909252810185905260600160408051601f1981840301815290829052610a5b9161117a565b602060405180830381855afa158015610a76573d5f5f3e3d5ffd5b5050506040513d601f19601f82011682018060405250810190610a999190611185565b9250610aa6600283610ff3565b91506001016109e1565b50610ab961134f565b5050505050505b50505050505050565b6060610ad6602054610c9c565b905090565b6020545f908190815b6020811015610c1b5781600116600103610b815760025f8260208110610b0c57610b0c61133b565b0154604080516020810192909252810185905260600160408051601f1981840301815290829052610b3c9161117a565b602060405180830381855afa158015610b57573d5f5f3e3d5ffd5b5050506040513d601f19601f82011682018060405250810190610b7a9190611185565b9250610c06565b60028360218360208110610b9757610b9761133b565b015460408051602081019390935282015260600160408051601f1981840301815290829052610bc59161117a565b602060405180830381855afa158015610be0573d5f5f3e3d5ffd5b5050506040513d601f19601f82011682018060405250810190610c039190611185565b92505b610c11600283610ff3565b9150600101610ae4565b50600282610c2a602054610c9c565b604051610c3d9291905f90602001611363565b60408051601f1981840301815290829052610c579161117a565b602060405180830381855afa158015610c72573d5f5f3e3d5ffd5b5050506040513d601f19601f82011682018060405250810190610c959190611185565b9250505090565b60408051600880825281830190925260609160208201818036833701905050905060c082901b8060071a60f81b825f81518110610cdb57610cdb61133b565b60200101906001600160f81b03191690815f1a9053508060061a60f81b82600181518110610d0b57610d0b61133b565b60200101906001600160f81b03191690815f1a9053508060051a60f81b82600281518110610d3b57610d3b61133b565b60200101906001600160f81b03191690815f1a9053508060041a60f81b82600381518110610d6b57610d6b61133b565b60200101906001600160f81b03191690815f1a9053508060031a60f81b82600481518110610d9b57610d9b61133b565b60200101906001600160f81b03191690815f1a9053508060021a60f81b82600581518110610dcb57610dcb61133b565b60200101906001600160f81b03191690815f1a9053508060011a60f81b82600681518110610dfb57610dfb61133b565b60200101906001600160f81b03191690815f1a905350805f1a60f81b82600781518110610e2a57610e2a61133b565b60200101906001600160f81b03191690815f1a90535050919050565b5f60208284031215610e56575f5ffd5b81357fffffffff0000000000000000000000000000000000000000000000000000000081168114610e85575f5ffd5b9392505050565b5f5f83601f840112610e9c575f5ffd5b50813567ffffffffffffffff811115610eb3575f5ffd5b602083019150836020828501011115610eca575f5ffd5b9250929050565b5f5f5f5f5f5f5f6080888a031215610ee7575f5ffd5b873567ffffffffffffffff811115610efd575f5ffd5b610f098a828b01610e8c565b909850965050602088013567ffffffffffffffff811115610f28575f5ffd5b610f348a828b01610e8c565b909650945050604088013567ffffffffffffffff811115610f53575f5ffd5b610f5f8a828b01610e8c565b989b979a50959894979596606090950135949350505050565b5f81518084528060208401602086015e5f602082860101526020601f19601f83011685010191505092915050565b602081525f610e856020830184610f78565b634e487b7160e01b5f52601260045260245ffd5b5f82610fda57610fda610fb8565b500690565b634e487b7160e01b5f52601160045260245ffd5b5f8261100157611001610fb8565b500490565b81835281816020850137505f602082840101525f6020601f19601f840116840101905092915050565b73ffffffffffffffffffffffffffffffffffffffff8916815260a060208201525f61105e60a08301898b611006565b828103604084015261107181888a611006565b90508281036060840152611086818688611006565b9150508260808301529998505050505050505050565b5f602082840312156110ac575f5ffd5b81518015158114610e85575f5ffd5b60a081525f6110ce60a083018a8c611006565b82810360208401526110e181898b611006565b905082810360408401526110f58188610f78565b9050828103606084015261110a818688611006565b9050828103608084015261111e8185610f78565b9b9a5050505050505050505050565b828482377fffffffffffffffffffffffffffffffff00000000000000000000000000000000919091169101908152601001919050565b5f81518060208401855e5f93019283525090919050565b5f610e858284611163565b5f60208284031215611195575f5ffd5b5051919050565b5f5f858511156111aa575f5ffd5b838611156111b6575f5ffd5b5050820193919092039150565b818382375f9101908152919050565b82848237909101908152602001919050565b838152818360208301375f910160200190815292915050565b5f6112088286611163565b67ffffffffffffffff1994909416845250506018820152603801919050565b6001815b60018411156112625780850481111561124657611246610fdf565b600184161561125457908102905b60019390931c92800261122b565b935093915050565b5f8261127857506001610160565b8161128457505f610160565b816001811461129a57600281146112a4576112c0565b6001915050610160565b60ff8411156112b5576112b5610fdf565b50506001821b610160565b5060208310610133831016604e8410600b84101617156112e3575081810a610160565b6112ef5f198484611227565b805f190482111561130257611302610fdf565b029392505050565b5f610e85838361126a565b8181038181111561016057610160610fdf565b8082018082111561016057610160610fdf565b634e487b7160e01b5f52603260045260245ffd5b634e487b7160e01b5f52600160045260245ffd5b8381525f6113746020830185611163565b67ffffffffffffffff1993909316835250506018019291505056fea164736f6c634300081e000a",
"storage": {
"0x0000000000000000000000000000000000000000000000000000000000000022": "0xf5a5fd42d16a20302798ef6ed309979b43003d2320d9f0e8ea9831a92759fb4b",
"0x0000000000000000000000000000000000000000000000000000000000000023": "0xdb56114e00fdd4c1f85c892bf35ac9a89289aaecb1ebd0a96cde606a748b5d71",
"0x0000000000000000000000000000000000000000000000000000000000000024": "0xc78009fdf07fc56a11f122370658a353aaa542ed63e44c4bc15ff4cd105ab33c",
"0x0000000000000000000000000000000000000000000000000000000000000025": "0x536d98837f2dd165a55d5eeae91485954472d56f246df256bf3cae19352a123c",
"0x0000000000000000000000000000000000000000000000000000000000000026": "0x9efde052aa15429fae05bad4d0b1d7c64da64d03d7a1854a588c2cb8430c0d30",
"0x0000000000000000000000000000000000000000000000000000000000000027": "0xd88ddfeed400a8755596b21942c1497e114c302e6118290f91e6772976041fa1",
"0x0000000000000000000000000000000000000000000000000000000000000028": "0x87eb0ddba57e35f6d286673802a4af5975e22506c7cf4c64bb6be5ee11527f2c",
"0x0000000000000000000000000000000000000000000000000000000000000029": "0x26846476fd5fc54a5d43385167c95144f2643f533cc85bb9d16b782f8d7db193",
"0x000000000000000000000000000000000000000000000000000000000000002a": "0x506d86582d252405b840018792cad2bf1259f1ef5aa5f887e13cb2f0094f51e1",
"0x000000000000000000000000000000000000000000000000000000000000002b": "0xffff0ad7e659772f9534c195c815efc4014ef1e1daed4404c06385d11192e92b",
"0x000000000000000000000000000000000000000000000000000000000000002c": "0x6cf04127db05441cd833107a52be852868890e4317e6a02ab47683aa75964220",
"0x000000000000000000000000000000000000000000000000000000000000002d": "0xb7d05f875f140027ef5118a2247bbb84ce8f2f0f1123623085daf7960c329f5f",
"0x000000000000000000000000000000000000000000000000000000000000002e": "0xdf6af5f5bbdb6be9ef8aa618e4bf8073960867171e29676f8b284dea6a08a85e",
"0x000000000000000000000000000000000000000000000000000000000000002f": "0xb58d900f5e182e3c50ef74969ea16c7726c549757cc23523c369587da7293784",
"0x0000000000000000000000000000000000000000000000000000000000000030": "0xd49a7502ffcfb0340b1d7885688500ca308161a7f96b62df9d083b71fcc8f2bb",
"0x0000000000000000000000000000000000000000000000000000000000000031": "0x8fe6b1689256c0d385f42f5bbe2027a22c1996e110ba97c171d3e5948de92beb",
"0x0000000000000000000000000000000000000000000000000000000000000032": "0x8d0d63c39ebade8509e0ae3c9c3876fb5fa112be18f905ecacfecb92057603ab",
"0x0000000000000000000000000000000000000000000000000000000000000033": "0x95eec8b2e541cad4e91de38385f2e046619f54496c2382cb6cacd5b98c26f5a4",
"0x0000000000000000000000000000000000000000000000000000000000000034": "0xf893e908917775b62bff23294dbbe3a1cd8e6cc1c35b4801887b646a6f81f17f",
"0x0000000000000000000000000000000000000000000000000000000000000035": "0xcddba7b592e3133393c16194fac7431abf2f5485ed711db282183c819e08ebaa",
"0x0000000000000000000000000000000000000000000000000000000000000036": "0x8a8d7fe3af8caa085a7639a832001457dfb9128a8061142ad0335629ff23ff9c",
"0x0000000000000000000000000000000000000000000000000000000000000037": "0xfeb3c337d7a51a6fbf00b9e34c52e1c9195c969bd4e7a0bfd51d5c5bed9c1167",
"0x0000000000000000000000000000000000000000000000000000000000000038": "0xe71f0aa83cc32edfbefa9f4d3e0174ca85182eec9f3a09f6a6c0df6377a510d7",
"0x0000000000000000000000000000000000000000000000000000000000000039": "0x31206fa80a50bb6abe29085058f16212212a60eec8f049fecb92d8c8e0a84bc0",
"0x000000000000000000000000000000000000000000000000000000000000003a": "0x21352bfecbeddde993839f614c3dac0a3ee37543f9b412b16199dc158e23b544",
"0x000000000000000000000000000000000000000000000000000000000000003b": "0x619e312724bb6d7c3153ed9de791d764a366b389af13c58bf8a8d90481a46765",
"0x000000000000000000000000000000000000000000000000000000000000003c": "0x7cdd2986268250628d0c10e385c58c6191e6fbe05191bcc04f133f2cea72c1c4",
"0x000000000000000000000000000000000000000000000000000000000000003d": "0x848930bd7ba8cac54661072113fb278869e07bb8587f91392933374d017bcbe1",
"0x000000000000000000000000000000000000000000000000000000000000003e": "0x8869ff2c22b28cc10510d9853292803328be4fb0e80495e8bb8d271f5b889636",
"0x000000000000000000000000000000000000000000000000000000000000003f": "0xb5fe28e79f1b850f8658246ce9b6a1e7b49fc06db7143e8fe0b4f2b0c5523a5c",
"0x0000000000000000000000000000000000000000000000000000000000000040": "0x985e929f70af28d0bdd1a90a808f977f597c7c778c489e98d3bd8910d31ac0f7",
"0x0000000000000000000000000000000000000000000000000000000000000041": "0x00000000000000000000000000000000a11acc355c0de0000a11acc355c0de00"
}
},
"0x00000000a11acc355c0de0000a11acc355c0de00": {
"balance": "0",
"code": "0x608060405234801561000f575f5ffd5b5060043610610149575f3560e01c806370a08231116100c7578063c17489281161007d578063d547741f11610063578063d547741f146102d2578063dd62ed3e146102e5578063fbe5943c1461031d575f5ffd5b8063c1748928146102ac578063c395fcb3146102bf575f5ffd5b806395d89b41116100ad57806395d89b411461026a578063a217fddf14610272578063a9059cbb14610299575f5ffd5b806370a082311461022f57806391d1485414610257575f5ffd5b8063248a9ca31161011c578063313ce56711610102578063313ce567146101fb57806336568abe1461020957806340c10f191461021c575f5ffd5b8063248a9ca3146101b35780632f2ff15d146101e6575f5ffd5b806306fdde031461014d578063095ea7b31461016b57806318160ddd1461018e57806323b872dd146101a0575b5f5ffd5b610155610344565b6040516101629190610eab565b60405180910390f35b61017e610179366004610f19565b6103d4565b6040519015158152602001610162565b6002545b604051908152602001610162565b61017e6101ae366004610f41565b6103ed565b6101926101c1366004610f7b565b507facce55000000000000000000ffffffffffffffffffffffffffffffffffffffff90565b6101f96101f4366004610f92565b610412565b005b6040515f8152602001610162565b6101f9610217366004610f92565b610559565b6101f961022a366004610f19565b61067c565b61019261023d366004610fbc565b6001600160a01b03165f9081526020819052604090205490565b61017e610265366004610f92565b610700565b610155610770565b6101927facce55000000000000000000ffffffffffffffffffffffffffffffffffffffff81565b61017e6102a7366004610f19565b61077f565b61017e6102ba36600461101a565b61078c565b61017e6102cd366004610fbc565b6108d1565b6101f96102e0366004610f92565b6108fc565b6101926102f33660046110d0565b6001600160a01b039182165f90815260016020908152604080832093909416825291909152205490565b6101927fc0de00000000000000000000ffffffffffffffffffffffffffffffffffffffff81565b606060038054610353906110f8565b80601f016020809104026020016040519081016040528092919081815260200182805461037f906110f8565b80156103ca5780601f106103a1576101008083540402835291602001916103ca565b820191905f5260205f20905b8154815290600101906020018083116103ad57829003601f168201915b5050505050905090565b5f336103e1818585610998565b60019150505b92915050565b5f336103fa8582856109aa565b610405858585610a3f565b60019150505b9392505050565b61043c7facce55000000000000000000ffffffffffffffffffffffffffffffffffffffff33610700565b6104b35760405162461bcd60e51b815260206004820152603260248201527f53696d706c65416363657373436f6e74726f6c3a206d7573742068617665206160448201527f646d696e20726f6c6520746f206772616e74000000000000000000000000000060648201526084015b60405180910390fd5b5f6104bd83610ace565b6040805173ffffffffffffffffffffffffffffffffffffffff19831660208201526bffffffffffffffffffffffff19606086901b16602c8201529192505f910160405160208183030381529060405261051590611130565b6001815560405190915033906001600160a01b0385169086907f2f8788117e7eff1d82e926ec794901d17c78024a50270940304540a733656f0d905f90a450505050565b6001600160a01b03811633146105d75760405162461bcd60e51b815260206004820152603560248201527f53696d706c65416363657373436f6e74726f6c3a2063616e206f6e6c7920726560448201527f6e6f756e636520726f6c657320666f722073656c66000000000000000000000060648201526084016104aa565b5f6105e183610ace565b6040805173ffffffffffffffffffffffffffffffffffffffff19831660208201526bffffffffffffffffffffffff19606086901b16602c8201529192505f910160405160208183030381529060405261063990611130565b5f80825560405191925033916001600160a01b0386169187917ff6391f5c32d9c69d2a47ea670b442974b53935d1edc7fd64eb21e047a839171b9190a450505050565b6106a67facce55000000000000000000ffffffffffffffffffffffffffffffffffffffff33610700565b6106f25760405162461bcd60e51b815260206004820152601360248201527f4f6e6c792061646d696e2063616e206d696e740000000000000000000000000060448201526064016104aa565b6106fc8282610b5a565b5050565b5f5f61070b84610ace565b6040805173ffffffffffffffffffffffffffffffffffffffff19831660208201526bffffffffffffffffffffffff19606087901b16602c8201529192505f910160405160208183030381529060405261076390611130565b5460011495945050505050565b606060048054610353906110f8565b5f336103e1818585610a3f565b5f6107b77fc0de00000000000000000000ffffffffffffffffffffffffffffffffffffffff33610700565b6108295760405162461bcd60e51b815260206004820152602c60248201527f4f6e6c79206465706f73697420636f6e74726163742063616e2063616c6c207460448201527f6869732066756e6374696f6e000000000000000000000000000000000000000060648201526084016104aa565b5f61083685856060610ba7565b8015610849575061084987876020610ba7565b9050806108c1576001600160a01b038a165f908152602081905260409020545f036108b65760405162461bcd60e51b815260206004820152601160248201527f4e6f7420656e6f75676820746f6b656e7300000000000000000000000000000060448201526064016104aa565b6108c18a6001610c1b565b5060019998505050505050505050565b5f6103e77facce55000000000000000000ffffffffffffffffffffffffffffffffffffffff83610700565b6109267facce55000000000000000000ffffffffffffffffffffffffffffffffffffffff33610700565b6105d75760405162461bcd60e51b815260206004820152603360248201527f53696d706c65416363657373436f6e74726f6c3a206d7573742068617665206160448201527f646d696e20726f6c6520746f207265766f6b650000000000000000000000000060648201526084016104aa565b6109a58383836001610c68565b505050565b6001600160a01b038381165f908152600160209081526040808320938616835292905220545f19811015610a395781811015610a2b576040517ffb8f41b20000000000000000000000000000000000000000000000000000000081526001600160a01b038416600482015260248101829052604481018390526064016104aa565b610a3984848484035f610c68565b50505050565b6001600160a01b038316610a81576040517f96c6fd1e0000000000000000000000000000000000000000000000000000000081525f60048201526024016104aa565b6001600160a01b038216610ac3576040517fec442f050000000000000000000000000000000000000000000000000000000081525f60048201526024016104aa565b6109a5838383610d6c565b5f8173ffffffffffffffffffffffffffffffffffffffff1981166103e75760405162461bcd60e51b815260206004820152602c60248201527f53696d706c65416363657373436f6e74726f6c3a207a65726f2070726566697860448201527f206e6f7420616c6c6f776564000000000000000000000000000000000000000060648201526084016104aa565b6001600160a01b038216610b9c576040517fec442f050000000000000000000000000000000000000000000000000000000081525f60048201526024016104aa565b6106fc5f8383610d6c565b5f828214610bb657505f61040b565b5f5b83811015610c1057848482818110610bd257610bd2611153565b909101357fff0000000000000000000000000000000000000000000000000000000000000016159050610c08575f91505061040b565b600101610bb8565b506001949350505050565b6001600160a01b038216610c5d576040517f96c6fd1e0000000000000000000000000000000000000000000000000000000081525f60048201526024016104aa565b6106fc825f83610d6c565b6001600160a01b038416610caa576040517fe602df050000000000000000000000000000000000000000000000000000000081525f60048201526024016104aa565b6001600160a01b038316610cec576040517f94280d620000000000000000000000000000000000000000000000000000000081525f60048201526024016104aa565b6001600160a01b038085165f9081526001602090815260408083209387168352929052208290558015610a3957826001600160a01b0316846001600160a01b03167f8c5be1e5ebec7d5bd14f71427d1e84f3dd0314c0f7b2291e5b200ac8c7c3b92584604051610d5e91815260200190565b60405180910390a350505050565b6001600160a01b038316610d96578060025f828254610d8b9190611167565b90915550610e1f9050565b6001600160a01b0383165f9081526020819052604090205481811015610e01576040517fe450d38c0000000000000000000000000000000000000000000000000000000081526001600160a01b038516600482015260248101829052604481018390526064016104aa565b6001600160a01b0384165f9081526020819052604090209082900390555b6001600160a01b038216610e3b57600280548290039055610e59565b6001600160a01b0382165f9081526020819052604090208054820190555b816001600160a01b0316836001600160a01b03167fddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef83604051610e9e91815260200190565b60405180910390a3505050565b602081525f82518060208401528060208501604085015e5f6040828501015260407fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffe0601f83011684010191505092915050565b80356001600160a01b0381168114610f14575f5ffd5b919050565b5f5f60408385031215610f2a575f5ffd5b610f3383610efe565b946020939093013593505050565b5f5f5f60608486031215610f53575f5ffd5b610f5c84610efe565b9250610f6a60208501610efe565b929592945050506040919091013590565b5f60208284031215610f8b575f5ffd5b5035919050565b5f5f60408385031215610fa3575f5ffd5b82359150610fb360208401610efe565b90509250929050565b5f60208284031215610fcc575f5ffd5b61040b82610efe565b5f5f83601f840112610fe5575f5ffd5b50813567ffffffffffffffff811115610ffc575f5ffd5b602083019150836020828501011115611013575f5ffd5b9250929050565b5f5f5f5f5f5f5f5f60a0898b031215611031575f5ffd5b61103a89610efe565b9750602089013567ffffffffffffffff811115611055575f5ffd5b6110618b828c01610fd5565b909850965050604089013567ffffffffffffffff811115611080575f5ffd5b61108c8b828c01610fd5565b909650945050606089013567ffffffffffffffff8111156110ab575f5ffd5b6110b78b828c01610fd5565b999c989b50969995989497949560800135949350505050565b5f5f604083850312156110e1575f5ffd5b6110ea83610efe565b9150610fb360208401610efe565b600181811c9082168061110c57607f821691505b60208210810361112a57634e487b7160e01b5f52602260045260245ffd5b50919050565b8051602080830151919081101561112a575f1960209190910360031b1b16919050565b634e487b7160e01b5f52603260045260245ffd5b808201808211156103e757634e487b7160e01b5f52601160045260245ffdfea164736f6c634300081e000a",
"storage": {
"0x0000000000000000000000000000000000000000000000000000000000000003": "0x4465706f73697420546f6b656e0000000000000000000000000000000000001a",
"0x0000000000000000000000000000000000000000000000000000000000000004": "0x4465706f7369740000000000000000000000000000000000000000000000000e",
"0xc0de0000000000000000000000000000219ab540356cbb839cbe05303d7705fa": "0x0000000000000000000000000000000000000000000000000000000000000001",
"0xacce550000000000000000001eA692E68a7765dE26FC03A6D74EE5B56A7e2b4d": "0x0000000000000000000000000000000000000000000000000000000000000001"
}
}
}
}
```
### 🔎 What the storage fields mean
- **Deposit contract (`0x…d7705Fa`)**
- `slot 0x41` → `0x00000000A11Acc355c0dE0000A11aCC355C0DE00`
Points to the **gating token contract address** used by the deposit contract to enforce gating.
- **Gating token contract (`0x…C0DE00`)**
- `slot 0x03` → Token **name** (bytes/hex): `0x4465706f73697420546f6b656e` → “Deposit Token”
- `slot 0x04` → Token **symbol** (bytes/hex): `0x4465706f736974` → “Deposit”
- `slot 0xc0de00000000000000000000{deposit_addr}` → Controlled **burn permission** for the deposit contract (enables 1-token burn per new validator deposit).
- `slot 0xacce55000000000000000000{admin_addr}` → **Admin permission** for initial admins seeded at genesis.
> ✅ These allocations ensure:
> - The deposit contract is wired to the correct gater at genesis.
> - The token contract has its metadata set and the required roles (deposit burn, initial admins) granted.
---
## 🛠️ Usage Guide
### 🧾 Deployment (via Genesis)
In permissioned networks built using the updated [ethereum-genesis-generator](https://github.com/ethpandaops/ethereum-genesis-generator/pull/248), both contracts are automatically included during genesis creation when enabling the gated deposit contract via the `DEPOSIT_CONTRACT_GATED` / `DEPOSIT_CONTRACT_ADMINS` env vars.
- Deposit contract → deployed at canonical address
- Gating token contract → deployed at fixed address
- Admins → preconfigured via `DEPOSIT_CONTRACT_ADMINS`
Admins are responsible for minting deposit tokens and managing who can deposit validators.
---
### 💰 Minting Gating Tokens
Admins can mint gating tokens either directly via on-chain calls or through the provided Hardhat scripts.
**Example:**
```sh
git clone https://github.com/pk910/gated-deposit-contract.git
cd gated-deposit-contract.git
npm install
# Set your privkey
npx hardhat vars set GATED_DEPOSIT_DEPLOYER_PRIVATE_KEY
# Set environment variables
export TOKEN_DEPOSIT_GATER_ADDRESS=0x00000000A11Acc355c0dE0000A11aCC355C0DE00
export RECIPIENT_ADDRESS=0x1234...abcd
export MINT_AMOUNT=10
# Run minting script
npx hardhat run scripts/mint-tokens.js --network <network-name>
```
Each minted token grants the recipient the right to make **one validator deposit**.
**If the Hardhat script does not work:** admins can call `mint(address to, uint256 amount)` directly by sending a transaction to the gating token contract (`0x00000000a11acc355c0de0000a11acc355c0de00`) with the following calldata to mint 1000 tokens:
`0x40c10f190000000000000000000000001ea692e68a7765de26fc03a6d74ee5b56a7e2b4d00000000000000000000000000000000000000000000000000000000000003e8`
Replace `1ea692e68a7765de26fc03a6d74ee5b56a7e2b4d` with your address.
---
### 🔐 Performing a Validator Deposit
Once a wallet holds at least **1 gating token**, it can make a deposit using standard deposit tools — no custom clients or forks required.
When calling `deposit()`:
1. The deposit contract calls the gater contract (`check_deposit()`).
2. The gater verifies that the sender has a token and burns it.
3. The deposit is processed normally.
If the wallet **does not hold tokens**, the transaction reverts.
This guarantees that **only authorized participants** (with tokens) can register validators.
---
### 🔄 Top-Up Deposits
Top-ups deposits do not consume tokens.
The gater detects these deposits automatically and skips the burn logic.
---
## 🧱 Example Kurtosis Config
```yaml
# kurtosis-network.yaml
participants:
- cl_type: lighthouse
el_type: geth
supernode: true
- cl_type: teku
el_type: reth
supernode: true
port_publisher:
additional_services:
enabled: true
public_port_start: 55500
el:
enabled: true
public_port_start: 55400
ethereum_genesis_generator_params:
# The image to use for ethereum genesis generator
image: pk910/dev-images:egg-gated-deposit
extra_env:
"DEPOSIT_CONTRACT_GATED": "true"
# set your wallet here
"DEPOSIT_CONTRACT_ADMINS": '["0x1eA692E68a7765dE26FC03A6D74EE5B56A7e2b4d"]'
additional_services:
- dora
- blockscout
- spamoor
```
---
## 📚 References
- [Contract Repository](https://github.com/pk910/gated-deposit-contract)
- [Genesis Generator PR #248](https://github.com/ethpandaops/ethereum-genesis-generator/pull/248)
- [Ethereum Deposit Contract Specification](https://github.com/ethereum/consensus-specs/blob/dev/specs/phase0/deposit-contract.md)
---