Skip to content

Commit 623fb02

Browse files
chasingrainbowschasingrainbows
committed
feat(orc-483): add delegtaion docs
1 parent 6416df9 commit 623fb02

File tree

2 files changed

+78
-1
lines changed

2 files changed

+78
-1
lines changed

‎README.md‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -220,7 +220,7 @@ In manual mode all sleeps are disabled and `ALLOW_REPORTING_IN_BUNKER_MODE` is T
220220
| `KEYS_API_URI` | URI of the Keys API | True | `http://localhost:8080` |
221221
| `LIDO_LOCATOR_ADDRESS` | Address of the Lido contract | True | `0x1...` |
222222
| `STAKING_MODULE_ADDRESS` | Address of the Staking Module contract | Staking Module only | `0x1...` |
223-
| `DELEGATION_CONTRACT_ADDRESS` | Address of the delegation contract. When set, oracle calls are routed through this contract | False | `0x1...` |
223+
| `DELEGATION_CONTRACT_ADDRESS` | Address of the delegation contract. When set, oracle calls are routed through this contract. See [delegation guide](docs/delegation.md) | False | `0x1...` |
224224
| `MEMBER_PRIV_KEY` | Private key of the Oracle member account | False | `0x1...` |
225225
| `MEMBER_PRIV_KEY_FILE` | A path to the file contained the private key of the Oracle member account. It takes precedence over `MEMBER_PRIV_KEY` | False | `/app/private_key` |
226226
| `PINATA_JWT` | JWT token to access pinata.cloud IPFS provider | True | `aBcD1234...` |
@@ -272,6 +272,10 @@ In manual mode all sleeps are disabled and `ALLOW_REPORTING_IN_BUNKER_MODE` is T
272272
> STAKING_MODULE_ADDRESS=0xdA7dE2ECdDfccC6c3AF10108Db212ACBBf9EA83F
273273
> ALLOW_REPORTING_IN_BUNKER_MODE=False
274274
275+
### Delegation
276+
277+
Check out our [delegation guide](docs/delegation.md) for setting up oracle with a delegation contract.
278+
275279
### Alerts
276280
277281
Check out our [alerting guide](docs/alerts.md) for Prometheus Alertmanager configuration examples.

‎docs/delegation.md‎

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
## Delegation
2+
3+
Delegation allows separating protocol permissions from oracle hot keys. Instead of granting permissions directly to the oracle account, they are granted to a [DelegationContract](https://github.com/lidofinance/delegation-execution-authority), and the oracle executes calls through it.
4+
5+
This enables instant hot key rotation by the contract admin without governance voting.
6+
7+
### How it works
8+
9+
```
10+
Oracle (hot key)
11+
│
12+
│ calls execute(target, calldata)
13+
▼
14+
DelegationContract (holds protocol permissions)
15+
│
16+
│ forwards call as msg.sender
17+
▼
18+
Target contract (HashConsensus, AccountingOracle, ExitBusOracle, CSFeeOracle)
19+
```
20+
21+
When delegation is enabled, the following calls are affected:
22+
23+
| Target contract | Method | Module |
24+
|--------------------------------------------------------------------------------------------|-------------------------------|--------------------|
25+
| [HashConsensus](https://docs.lido.fi/contracts/hash-consensus) | `submitReport` | All |
26+
| [AccountingOracle](https://docs.lido.fi/contracts/accounting-oracle) | `submitReportData` | Accounting |
27+
| [AccountingOracle](https://docs.lido.fi/contracts/accounting-oracle) | `submitReportExtraDataList` | Accounting |
28+
| [AccountingOracle](https://docs.lido.fi/contracts/accounting-oracle) | `submitReportExtraDataEmpty` | Accounting |
29+
| [ValidatorsExitBusOracle](https://docs.lido.fi/contracts/validators-exit-bus-oracle) | `submitReportData` | Ejector |
30+
| CSFeeOracle | `submitReportData` | Staking Module |
31+
32+
The target contract sees `DelegationContract` as `msg.sender`, so all permissions must be granted to the delegation contract address, not to the oracle account.
33+
34+
### Setup
35+
36+
#### 1. Deploy delegation contract
37+
38+
The contract admin deploys a `DelegationContract` instance via `DelegationFactory` from the [delegation-execution-authority](https://github.com/lidofinance/delegation-execution-authority) repository.
39+
40+
#### 2. Grant protocol permissions
41+
42+
Governance grants oracle member permissions to the deployed `DelegationContract` address (not to the oracle hot key).
43+
44+
#### 3. Assign oracle as delegatee
45+
46+
The contract admin calls `assignDelegate(oracleAddress)` on the delegation contract, where `oracleAddress` is the oracle operator's account address.
47+
48+
#### 4. Configure the oracle
49+
50+
Set the environment variable:
51+
52+
```bash
53+
DELEGATION_CONTRACT_ADDRESS=0x... # deployed DelegationContract address
54+
```
55+
56+
### Startup validation
57+
58+
On startup the oracle validates the delegation setup:
59+
60+
- If `DELEGATION_CONTRACT_ADDRESS` is not set, delegation is disabled and the oracle sends transactions directly.
61+
- If set but `MEMBER_PRIV_KEY` is not configured (dry mode), validation is skipped.
62+
- If the contract has no delegatee (`address(0)`), the oracle fails with `NotConfiguredError`.
63+
- If the contract's delegatee does not match the oracle account, the oracle fails with `DelegateMismatchError`.
64+
65+
### Key rotation
66+
67+
To rotate the oracle hot key:
68+
69+
1. Admin calls `assignDelegate(newOracleAddress)` on the delegation contract.
70+
2. Update `MEMBER_PRIV_KEY` in the oracle config to the new key.
71+
3. Restart the oracle.
72+
73+
No governance vote is required.

0 commit comments

Comments
 (0)