# 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** by default.
- **Per-deposit-type configuration** — admins can block or disable token requirements for specific withdrawal credential prefixes (0x00, 0x01, 0x02, 0x03) and top-ups.
- **Custom gater support** — an optional external gater contract can be set to extend or override the default gating logic.
- 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
- Per-deposit-type gate configuration (block/allow, token required/not required)
- Optional custom gater contract delegation
- The deposit contract is allowed to perform controlled burns.
#### Per-Deposit-Type Gate Configuration
Admins can configure gating behavior per deposit type using `setDepositGateConfig(uint16 depositType, bool blocked, bool noToken)`:
| Deposit Type | Value | Description |
|--------------|-------|-------------|
| `0x0000` | 0 | BLS withdrawal credentials (0x00 prefix) |
| `0x0001` | 1 | Execution layer withdrawal credentials (0x01 prefix) |
| `0x0002` | 2 | Compounding credentials (0x02 prefix) |
| `0x0003` | 3 | ePBS builder credentials (0x03 prefix) |
| `0xffff` | 65535 | Top-up deposits |
Configuration flags:
- **blocked** — if `true`, deposits of this type are rejected entirely.
- **noToken** — if `true`, no token is burned for deposits of this type (deposits are allowed without holding tokens).
By default, all deposit types require 1 token and are not blocked.
#### Custom Gater
Admins can set a custom gater contract via `setCustomGater(address gater)`. When set:
1. The custom gater's `check_deposit()` is called **first**.
2. If the custom gater returns `true`, the deposit is approved immediately (no token burned).
3. If it returns `false`, the standard token-based gating logic is applied.
This allows extending the gating mechanism with custom logic (e.g., whitelists, time-based restrictions, external oracles) while keeping the token-based fallback.
## 🧾 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": "0x608060405234801561000f575f5ffd5b506004361061019a575f3560e01c80638bd99e8a116100e8578063afcde0ed11610093578063d547741f1161006e578063d547741f1461039e578063dd62ed3e146103b1578063f3f52e26146103e9578063fbe5943c14610413575f5ffd5b8063afcde0ed14610352578063c174892814610378578063c395fcb31461038b575f5ffd5b8063a217fddf116100c3578063a217fddf14610305578063a9059cbb1461032c578063aa93e3ac1461033f575f5ffd5b80638bd99e8a146102ce57806391d14854146102ea57806395d89b41146102fd575f5ffd5b8063313ce567116101485780634c7b79ec116101235780634c7b79ec1461028057806370a08231146102935780637abc4957146102bb575f5ffd5b8063313ce5671461024c57806336568abe1461025a57806340c10f191461026d575f5ffd5b806323b872dd1161017857806323b872dd146101f1578063248a9ca3146102045780632f2ff15d14610237575f5ffd5b806306fdde031461019e578063095ea7b3146101bc57806318160ddd146101df575b5f5ffd5b6101a661043a565b6040516101b391906114a4565b60405180910390f35b6101cf6101ca3660046114f4565b6104ca565b60405190151581526020016101b3565b6002545b6040519081526020016101b3565b6101cf6101ff36600461151c565b6104e3565b6101e3610212366004611556565b507facce55000000000000000000ffffffffffffffffffffffffffffffffffffffff90565b61024a61024536600461156d565b610508565b005b6040515f81526020016101b3565b61024a61026836600461156d565b61064f565b61024a61027b3660046114f4565b610772565b61024a61028e366004611597565b6107f6565b6101e36102a1366004611597565b6001600160a01b03165f9081526020819052604090205490565b6101cf6102c936600461156d565b6108d7565b6102d761ffff81565b60405161ffff90911681526020016101b3565b6101cf6102f836600461156d565b610947565b6101a66109b8565b6101e37facce55000000000000000000ffffffffffffffffffffffffffffffffffffffff81565b6101cf61033a3660046114f4565b6109c7565b61024a61034d3660046115d1565b6109d4565b6831bab9ba33b0ba32b960b91b546040516001600160a01b0390911681526020016101b3565b6101cf61038636600461165c565b610acb565b6101cf610399366004611597565b610db9565b61024a6103ac36600461156d565b610de4565b6101e36103bf366004611712565b6001600160a01b039182165f90815260016020908152604080832093909416825291909152205490565b6103fc6103f736600461173a565b610efd565b6040805192151583529015156020830152016101b3565b6101e37fc0de00000000000000000000ffffffffffffffffffffffffffffffffffffffff81565b60606003805461044990611753565b80601f016020809104026020016040519081016040528092919081815260200182805461047590611753565b80156104c05780601f10610497576101008083540402835291602001916104c0565b820191905f5260205f20905b8154815290600101906020018083116104a357829003601f168201915b5050505050905090565b5f336104d7818585610f20565b60019150505b92915050565b5f336104f0858285610f32565b6104fb858585610fc7565b60019150505b9392505050565b6105327facce55000000000000000000ffffffffffffffffffffffffffffffffffffffff33610947565b6105a95760405162461bcd60e51b815260206004820152603260248201527f53696d706c65416363657373436f6e74726f6c3a206d7573742068617665206160448201527f646d696e20726f6c6520746f206772616e74000000000000000000000000000060648201526084015b60405180910390fd5b5f6105b383611056565b6040805173ffffffffffffffffffffffffffffffffffffffff19831660208201526bffffffffffffffffffffffff19606086901b16602c8201529192505f910160405160208183030381529060405261060b9061178b565b6001815560405190915033906001600160a01b0385169086907f2f8788117e7eff1d82e926ec794901d17c78024a50270940304540a733656f0d905f90a450505050565b6001600160a01b03811633146106cd5760405162461bcd60e51b815260206004820152603560248201527f53696d706c65416363657373436f6e74726f6c3a2063616e206f6e6c7920726560448201527f6e6f756e636520726f6c657320666f722073656c66000000000000000000000060648201526084016105a0565b5f6106d783611056565b6040805173ffffffffffffffffffffffffffffffffffffffff19831660208201526bffffffffffffffffffffffff19606086901b16602c8201529192505f910160405160208183030381529060405261072f9061178b565b5f80825560405191925033916001600160a01b0386169187917ff6391f5c32d9c69d2a47ea670b442974b53935d1edc7fd64eb21e047a839171b9190a450505050565b61079c7facce55000000000000000000ffffffffffffffffffffffffffffffffffffffff33610947565b6107e85760405162461bcd60e51b815260206004820152601360248201527f4f6e6c792061646d696e2063616e206d696e740000000000000000000000000060448201526064016105a0565b6107f282826110e2565b5050565b6107ff33610db9565b6108715760405162461bcd60e51b815260206004820152603460248201527f53696d706c65416363657373436f6e74726f6c3a2063616c6c657220646f657360448201527f206e6f7420686176652061646d696e20726f6c6500000000000000000000000060648201526084016105a0565b5f6108866831bab9ba33b0ba32b960b91b5490565b6831bab9ba33b0ba32b960b91b838155604051919250906001600160a01b0380851691908416907f562b492461e43f0be67564dc401859d11f5720aeb034d95f3baa17eb371e5d86905f90a3505050565b5f5f6108e284611056565b6040805173ffffffffffffffffffffffffffffffffffffffff19831660208201526bffffffffffffffffffffffff19606087901b16602c8201529192505f910160405160208183030381529060405261093a9061178b565b5460021495945050505050565b5f5f61095284611056565b6040805173ffffffffffffffffffffffffffffffffffffffff19831660208201526bffffffffffffffffffffffff19606087901b16602c8201529192505f91016040516020818303038152906040526109aa9061178b565b546001111595945050505050565b60606004805461044990611753565b5f336104d7818585610fc7565b6109dd33610db9565b610a4f5760405162461bcd60e51b815260206004820152603460248201527f53696d706c65416363657373436f6e74726f6c3a2063616c6c657220646f657360448201527f206e6f7420686176652061646d696e20726f6c6500000000000000000000000060648201526084016105a0565b5f610a598461112f565b90505f82610a67575f610a6a565b60025b84610a75575f610a78565b60015b1760ff16808355604080518615158152851515602082015291925061ffff8716917f0c188bc85a1c8d8aed6ffac0a86d3aff3160b6d8c014d1c30342899aec77afb9910160405180910390a25050505050565b5f610af67fc0de00000000000000000000ffffffffffffffffffffffffffffffffffffffff33610947565b610b685760405162461bcd60e51b815260206004820152602c60248201527f4f6e6c79206465706f73697420636f6e74726163742063616e2063616c6c207460448201527f6869732066756e6374696f6e000000000000000000000000000000000000000060648201526084016105a0565b5f610b7d6831bab9ba33b0ba32b960b91b5490565b90506001600160a01b03811615610c30576040517fc17489280000000000000000000000000000000000000000000000000000000081526001600160a01b0382169063c174892890610be1908d908d908d908d908d908d908d908d906004016117d7565b6020604051808303815f875af1158015610bfd573d5f5f3e3d5ffd5b505050506040513d601f19601f82011682018060405250810190610c219190611837565b15610c30576001915050610dad565b5f610c3d868660606111a0565b8015610c505750610c50888860206111a0565b90505f8115610c62575061ffff610cd1565b6001881015610cb35760405162461bcd60e51b815260206004820152601e60248201527f496e76616c6964207769746864726177616c2063726564656e7469616c73000060448201526064016105a0565b88885f818110610cc557610cc5611852565b919091013560f81c9150505b5f5f610cdc83610efd565b915091508115610d2e5760405162461bcd60e51b815260206004820152601760248201527f4465706f736974207479706520697320626c6f636b656400000000000000000060448201526064016105a0565b80610da3576001600160a01b038e165f9081526020819052604081205411610d985760405162461bcd60e51b815260206004820152601160248201527f4e6f7420656e6f75676820746f6b656e7300000000000000000000000000000060448201526064016105a0565b610da38e6001611214565b6001955050505050505b98975050505050505050565b5f6104dd7facce55000000000000000000ffffffffffffffffffffffffffffffffffffffff83610947565b610e0e7facce55000000000000000000ffffffffffffffffffffffffffffffffffffffff33610947565b610e805760405162461bcd60e51b815260206004820152603360248201527f53696d706c65416363657373436f6e74726f6c3a206d7573742068617665206160448201527f646d696e20726f6c6520746f207265766f6b650000000000000000000000000060648201526084016105a0565b610e8a82826108d7565b156106cd5760405162461bcd60e51b815260206004820152602e60248201527f53696d706c65416363657373436f6e74726f6c3a2063616e6e6f74207265766f60448201527f6b6520737469636b7920726f6c6500000000000000000000000000000000000060648201526084016105a0565b5f5f5f610f098461112f565b546001811615159560029091161515945092505050565b610f2d8383836001611261565b505050565b6001600160a01b038381165f908152600160209081526040808320938616835292905220545f19811015610fc15781811015610fb3576040517ffb8f41b20000000000000000000000000000000000000000000000000000000081526001600160a01b038416600482015260248101829052604481018390526064016105a0565b610fc184848484035f611261565b50505050565b6001600160a01b038316611009576040517f96c6fd1e0000000000000000000000000000000000000000000000000000000081525f60048201526024016105a0565b6001600160a01b03821661104b576040517fec442f050000000000000000000000000000000000000000000000000000000081525f60048201526024016105a0565b610f2d838383611365565b5f8173ffffffffffffffffffffffffffffffffffffffff1981166104dd5760405162461bcd60e51b815260206004820152602c60248201527f53696d706c65416363657373436f6e74726f6c3a207a65726f2070726566697860448201527f206e6f7420616c6c6f776564000000000000000000000000000000000000000060648201526084016105a0565b6001600160a01b038216611124576040517fec442f050000000000000000000000000000000000000000000000000000000081525f60048201526024016105a0565b6107f25f8383611365565b604080517f676174650000000000000000000000000000000000000000000000000000000060208201527fffff00000000000000000000000000000000000000000000000000000000000060f084901b16603e8201525f91016040516020818303038152906040526104dd9061178b565b5f8282146111af57505f610501565b5f5b83811015611209578484828181106111cb576111cb611852565b909101357fff0000000000000000000000000000000000000000000000000000000000000016159050611201575f915050610501565b6001016111b1565b506001949350505050565b6001600160a01b038216611256576040517f96c6fd1e0000000000000000000000000000000000000000000000000000000081525f60048201526024016105a0565b6107f2825f83611365565b6001600160a01b0384166112a3576040517fe602df050000000000000000000000000000000000000000000000000000000081525f60048201526024016105a0565b6001600160a01b0383166112e5576040517f94280d620000000000000000000000000000000000000000000000000000000081525f60048201526024016105a0565b6001600160a01b038085165f9081526001602090815260408083209387168352929052208290558015610fc157826001600160a01b0316846001600160a01b03167f8c5be1e5ebec7d5bd14f71427d1e84f3dd0314c0f7b2291e5b200ac8c7c3b9258460405161135791815260200190565b60405180910390a350505050565b6001600160a01b03831661138f578060025f8282546113849190611866565b909155506114189050565b6001600160a01b0383165f90815260208190526040902054818110156113fa576040517fe450d38c0000000000000000000000000000000000000000000000000000000081526001600160a01b038516600482015260248101829052604481018390526064016105a0565b6001600160a01b0384165f9081526020819052604090209082900390555b6001600160a01b03821661143457600280548290039055611452565b6001600160a01b0382165f9081526020819052604090208054820190555b816001600160a01b0316836001600160a01b03167fddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef8360405161149791815260200190565b60405180910390a3505050565b602081525f82518060208401528060208501604085015e5f604082850101526040601f19601f83011684010191505092915050565b80356001600160a01b03811681146114ef575f5ffd5b919050565b5f5f60408385031215611505575f5ffd5b61150e836114d9565b946020939093013593505050565b5f5f5f6060848603121561152e575f5ffd5b611537846114d9565b9250611545602085016114d9565b929592945050506040919091013590565b5f60208284031215611566575f5ffd5b5035919050565b5f5f6040838503121561157e575f5ffd5b8235915061158e602084016114d9565b90509250929050565b5f602082840312156115a7575f5ffd5b610501826114d9565b803561ffff811681146114ef575f5ffd5b80151581146115ce575f5ffd5b50565b5f5f5f606084860312156115e3575f5ffd5b6115ec846115b0565b925060208401356115fc816115c1565b9150604084013561160c816115c1565b809150509250925092565b5f5f83601f840112611627575f5ffd5b50813567ffffffffffffffff81111561163e575f5ffd5b602083019150836020828501011115611655575f5ffd5b9250929050565b5f5f5f5f5f5f5f5f60a0898b031215611673575f5ffd5b61167c896114d9565b9750602089013567ffffffffffffffff811115611697575f5ffd5b6116a38b828c01611617565b909850965050604089013567ffffffffffffffff8111156116c2575f5ffd5b6116ce8b828c01611617565b909650945050606089013567ffffffffffffffff8111156116ed575f5ffd5b6116f98b828c01611617565b999c989b50969995989497949560800135949350505050565b5f5f60408385031215611723575f5ffd5b61172c836114d9565b915061158e602084016114d9565b5f6020828403121561174a575f5ffd5b610501826115b0565b600181811c9082168061176757607f821691505b60208210810361178557634e487b7160e01b5f52602260045260245ffd5b50919050565b80516020808301519190811015611785575f1960209190910360031b1b16919050565b81835281816020850137505f602082840101525f6020601f19601f840116840101905092915050565b6001600160a01b038916815260a060208201525f6117f960a08301898b6117ae565b828103604084015261180c81888a6117ae565b905082810360608401526118218186886117ae565b9150508260808301529998505050505050505050565b5f60208284031215611847575f5ffd5b8151610501816115c1565b634e487b7160e01b5f52603260045260245ffd5b808201808211156104dd57634e487b7160e01b5f52601160045260245ffdfea164736f6c634300081e000a",
"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.
- `slot 0x67617465000000000000000000000000000000000000000000000000{type}` → **Gate settings** per deposit type ("gate" prefix + 2-byte type). Value bits: `0x01` = blocked, `0x02` = noToken. Example: `0x6761746500000000000000000000000000000000000000000000000000000001` for 0x01 credentials.
- `slot 0x6375737467617465720000000000000000000000000000000000000000000000` → **Custom gater address** ("custgater"). If set to a non-zero address, this gater is called first before token-based gating.
> ✅ 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
By default, top-up deposits do not consume tokens.
The gater detects these deposits automatically (signature = 96 zero bytes, withdrawal_credentials = 32 zero bytes) and applies the gate config for deposit type `0xffff`.
Admins can modify this behavior using `setDepositGateConfig(0xffff, blocked, noToken)`.
---
### ⚙️ Configuring Gate Settings
Admins can configure per-deposit-type gating via `setDepositGateConfig()`:
**Example: Block all 0x00 (BLS) withdrawal credential deposits:**
```solidity
tokenDepositGater.setDepositGateConfig(0x0000, true, false);
```
**Example: Allow 0x01 deposits without requiring tokens:**
```solidity
tokenDepositGater.setDepositGateConfig(0x0001, false, true);
```
**Example: Set a custom gater contract:**
```solidity
tokenDepositGater.setCustomGater(0x1234...customGaterAddress);
```
To query current settings:
```solidity
(bool blocked, bool noToken) = tokenDepositGater.getDepositGateConfig(0x0001);
address customGater = tokenDepositGater.getCustomGater();
```
---
## 🧱 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: ethpandaops/ethereum-genesis-generator:gated-deposit-contract
extra_env:
"DEPOSIT_CONTRACT_GATED": "true"
# set your wallet here
"DEPOSIT_CONTRACT_ADMINS": '["0x1eA692E68a7765dE26FC03A6D74EE5B56A7e2b4d"]'
# optional per prefix settings (0x01: blocked, 0x02: no token requirement)
"DEPOSIT_CONTRACT_SETTINGS": '{"0x03": "0x02"}' # allow builder deposits without token
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)
---