Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion .github/workflows/contracts-ecdsa.yml
Original file line number Diff line number Diff line change
Expand Up @@ -80,7 +80,8 @@ jobs:
if: |
github.event_name != 'pull_request'
|| needs.contracts-detect-changes.outputs.path-filter == 'true'
runs-on: ubuntu-latest
# Python 3.10.8 has an official Actions build for this runner image.
runs-on: ubuntu-22.04
defaults:
run:
working-directory: ./solidity/ecdsa
Expand Down
3 changes: 2 additions & 1 deletion .github/workflows/contracts-random-beacon.yml
Original file line number Diff line number Diff line change
Expand Up @@ -80,7 +80,8 @@ jobs:
if: |
github.event_name != 'pull_request'
|| needs.contracts-detect-changes.outputs.path-filter == 'true'
runs-on: ubuntu-latest
# Python 3.10.8 has an official Actions build for this runner image.
runs-on: ubuntu-22.04
defaults:
run:
working-directory: ./solidity/random-beacon
Expand Down
109 changes: 109 additions & 0 deletions docs/glamsterdam-migration.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,109 @@
# Glamsterdam gas compatibility

The current Amsterdam gas rules are provisional until the fork specification is
finalized. This draft provides defensive gas-meter arithmetic and review tooling;
it does not establish a required mainnet contract upgrade.

## Live wallet-creation wiring

At mainnet block 26,363,834, WalletRegistry
`0x46d52E41C2F300BC82217Ce22b920c34995204eb` returned
`0xF23fc18EcE6Afe7fb57ba59979e8600bb4B0294a` from `randomBeacon()`.
That provider is RandomBeaconChaosnet, whose callback forwards available gas
without a fixed 64k cap. The registry switched to it on January 25, 2023 in
[this transaction](https://etherscan.io/tx/0xa7314c468cb059867cb9d544b964754ca95d228aa72d6d74e9c40e419083304a).

The separate RandomBeacon at `0x5499f54b4A1CB4816eefCf78962040461be3D80b`
has a 64k callback parameter, but it is not the live registry's provider.
Consequently, this draft does not change callback defaults or generate callback
governance updates. Always read the registry's actual provider before assessing
callback limits.

The EELS fixture in `solidity/ecdsa/test/glamsterdam/` uses verified deployed
registry bytecode with **synthetic storage assigning the capped beacon** and a
stub sortition pool. It demonstrates a hypothetical capped-callback failure,
not the current mainnet wallet-creation path. Its 240,768 threshold and 300k
success must not be used to justify a live callback update.

## DKG reimbursement: calldata floor matters

DKG submission can succeed while its fixed reimbursement underpays operators.
The draft leaves the historical defaults unchanged: 237,650 gas for RandomBeacon
and 290,000 for WalletRegistry. These are not post-fork recommendations.

For a WalletRegistry result with 100 members, 100 signatures and no misbehaved
members, both submission and approval calldata are 13,412 bytes. With no value
or access list, the pinned Amsterdam transaction floor is:

```text
12,000 base + 3,000 recipient access + 64 × 13,412 bytes = 873,368 gas
```

The floor depends on the actual encoding and signature count. It is imposed at
final transaction settlement, so `gasleft()` cannot observe it even below a
`2^24` transaction gas limit. Adding only the two fresh-slot cost increases
misses this mechanism; the earlier 450k/500k proposals were not justified.

A supplied Sepolia benchmark proposes a WalletRegistry allowance of 920k.
Treat it as a candidate for that measured path, not a mainnet quote. Covering
gas units does not guarantee full ETH reimbursement: submission and approval
can use different effective gas prices, and the pool pays at its capped
approval-transaction price. Check both receipts, signature count, implementation,
approval measurement and credited ETH. Do not copy the value to RandomBeacon:
that DKG uses a different result shape and 64 members.

Benchmark the complete submission **and** approval transactions, using actual
receipts and credited ETH at the pool's capped reimbursement gas price. Include
the approval offset and `ReimbursementPool.staticGas` (40,800 in the observed
mainnet deployment). Recheck all timeout/inactivity offsets separately. Existing
governance setters can change reimbursement parameters without upgrading the
contract implementation.

## Read-only governance preparation

The script prints the actual registry provider, current gas parameters, owners,
delays and optional refund-update calldata at one pinned block. With neither
environment variable set, it prints no update calls. Supply a separately
benchmarked positive integer for each parameter you intend to review:

```sh
cd solidity/ecdsa
GLAMSTERDAM_WALLET_DKG_SUBMISSION_GAS=<benchmarked-value> \
yarn hardhat run scripts/prepare-glamsterdam.ts --network mainnet
```

Use `GLAMSTERDAM_BEACON_DKG_SUBMISSION_GAS` only after a separate RandomBeacon
benchmark. The script never signs or broadcasts. Review the chain ID, live
provider, owners and pending updates; submit approved begin calls, wait the
on-chain governance delay, verify pending values, then submit matching finalize
calls. Never finalize an unrelated pending update. Read `gasParameters()` again
afterward. Neither historical defaults nor supplied environment values become
automatically validated by generating calldata.

## Gas measurement and payout limitations

The updated meter clamps a negative `gasStart - gasleft()` delta to zero,
including the negative DKG-timeout offset. This prevents arithmetic underflow
from reverting otherwise successful work. It adds no storage fields and preserves
proxy storage layouts. No ordinary production transaction has been demonstrated
to trigger such an underflow; this is defensive compatibility work.

Saturation does not make reimbursement exact. Besides the settlement floor,
reservoir-paid new-state gas above `2^24` is invisible to `gasleft()`. Monitor
actual transaction costs and use ordinary fresh estimates. A reimbursement
redesign needs an agreed capped fee or a state-aware quote; this draft does not
provide one.

ReimbursementPool treats failed ETH sends as best effort. Contract operators
should use a storage-free receiver and monitor `SendingEtherFailed`. Adding a
fresh retry-credit slot after an out-of-gas receiver call can itself exhaust gas
and revert protocol work; this draft does not add that failure path. A replacement
pool requires separate migration and gas benchmarks.

## References

- https://eips.ethereum.org/EIPS/eip-7976
- https://eips.ethereum.org/EIPS/eip-2780
- https://eips.ethereum.org/EIPS/eip-8037
- https://eips.ethereum.org/EIPS/eip-8038
- https://github.com/ethereum/glamsterdam-gas-invariants
31 changes: 27 additions & 4 deletions solidity/ecdsa/contracts/WalletRegistry.sol
Original file line number Diff line number Diff line change
Expand Up @@ -902,7 +902,7 @@ contract WalletRegistry is
// Refund msg.sender's ETH for DKG result submission and result approval
reimbursementPool.refund(
_dkgResultSubmissionGas +
(gasStart - gasleft()) +
_registryGasSpent(gasStart) +
_dkgResultApprovalGasOffset,
msg.sender
);
Expand All @@ -917,7 +917,7 @@ contract WalletRegistry is
dkg.notifySeedTimeout();

reimbursementPool.refund(
(gasStart - gasleft()) + _notifySeedTimeoutGasOffset,
_registryGasSpent(gasStart) + _notifySeedTimeoutGasOffset,
msg.sender
);
}
Expand All @@ -932,7 +932,10 @@ contract WalletRegistry is
// performed on DKG timeout notification removes data from the storage
// which is recovering gas for the transaction.
reimbursementPool.refund(
(gasStart - gasleft()) - _notifyDkgTimeoutNegativeGasOffset,
_registryGasSpentAfterOffset(
gasStart,
_notifyDkgTimeoutNegativeGasOffset
),
msg.sender
);
}
Expand Down Expand Up @@ -1123,7 +1126,7 @@ contract WalletRegistry is
}

reimbursementPool.refund(
(gasStart - gasleft()) + _notifyOperatorInactivityGasOffset,
_registryGasSpent(gasStart) + _notifyOperatorInactivityGasOffset,
msg.sender
);
}
Expand Down Expand Up @@ -1480,6 +1483,26 @@ contract WalletRegistry is
return _maliciousDkgResultSlashingAmount;
}

/// @dev Keep the meter local so this upgrade does not require a new
/// random-beacon npm dependency. Reservoir state gas is invisible.
function _registryGasSpent(uint256 gasStart)
internal
view
returns (uint256)
{
uint256 gasEnd = gasleft();
return gasStart > gasEnd ? gasStart - gasEnd : 0;
}

function _registryGasSpentAfterOffset(uint256 gasStart, uint256 offset)
internal
view
returns (uint256)
{
uint256 spent = _registryGasSpent(gasStart);
return spent > offset ? spent - offset : 0;
}

/// @notice Retrieves gas-related parameters.
/// @return dkgResultSubmissionGas Calculated max gas cost for submitting
/// a DKG result. This will be refunded as part of the DKG approval
Expand Down
120 changes: 120 additions & 0 deletions solidity/ecdsa/scripts/prepare-glamsterdam.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,120 @@
/* eslint-disable import/no-extraneous-dependencies, no-console */
import { deployments, ethers, network } from "hardhat"

// Read-only: explicit, independently benchmarked inputs are required. No defaults.
function benchmarkedGas(name: string): string | undefined {
const value = process.env[name]
if (value === undefined) return undefined
if (!/^[1-9][0-9]*$/.test(value)) {
throw new Error(
`${name} must be a positive integer from a full DKG benchmark`
)
}
if (ethers.BigNumber.from(value).gt(ethers.constants.MaxUint256)) {
throw new Error(`${name} exceeds uint256`)
}
return value
}

async function main() {
const beaconGas = benchmarkedGas("GLAMSTERDAM_BEACON_DKG_SUBMISSION_GAS")
const registryGas = benchmarkedGas("GLAMSTERDAM_WALLET_DKG_SUBMISSION_GAS")
const blockNumber = await ethers.provider.getBlockNumber()
const atBlock = { blockTag: blockNumber }
const beaconDeployment = await deployments.get("RandomBeacon")
const registryDeployment = await deployments.get("WalletRegistry")
const beacon = new ethers.Contract(
beaconDeployment.address,
[
"function governance() view returns (address)",
"function relayEntryParameters() view returns (uint256,uint256,uint256)",
"function gasParameters() view returns (uint256,uint256,uint256,uint256)",
],
ethers.provider
)
const registry = new ethers.Contract(
registryDeployment.address,
[
"function governance() view returns (address)",
"function randomBeacon() view returns (address)",
"function gasParameters() view returns (uint256,uint256,uint256,uint256,uint256)",
],
ethers.provider
)
const governanceAbi = [
"function owner() view returns (address)",
"function governanceDelay() view returns (uint256)",
"function beginDkgResultSubmissionGasUpdate(uint256)",
"function finalizeDkgResultSubmissionGasUpdate()",
]
const beaconGovernance = new ethers.Contract(
await beacon.governance(atBlock),
governanceAbi,
ethers.provider
)
const registryGovernance = new ethers.Contract(
await registry.governance(atBlock),
governanceAbi,
ethers.provider
)
const updates = [
{ target: beaconGovernance, value: beaconGas },
{ target: registryGovernance, value: registryGas },
].filter(({ value }) => value !== undefined)
const call = (
target: typeof beaconGovernance,
method: string,
args: string[] = []
) => ({
to: target.address,
value: "0",
data: target.interface.encodeFunctionData(method, args),
method,
})
console.log(
JSON.stringify(
{
network: network.name,
chainId: (await ethers.provider.getNetwork()).chainId,
blockNumber,
walletRegistry: registry.address,
walletRegistryRandomBeacon: await registry.randomBeacon(atBlock),
cappedRandomBeacon: beacon.address,
// The deployed RandomBeacon artifact is not necessarily the registry's
// actual provider. Never infer callback wiring from its parameters.
callbackUpdateGenerated: false,
currentParameters: {
beaconRelay: (await beacon.relayEntryParameters(atBlock)).map(String),
beaconGas: (await beacon.gasParameters(atBlock)).map(String),
registryGas: (await registry.gasParameters(atBlock)).map(String),
},
owners: {
randomBeacon: await beaconGovernance.owner(atBlock),
walletRegistry: await registryGovernance.owner(atBlock),
},
governanceDelays: {
randomBeacon: (
await beaconGovernance.governanceDelay(atBlock)
).toString(),
walletRegistry: (
await registryGovernance.governanceDelay(atBlock)
).toString(),
},
begin: updates.map(({ target, value }) =>
call(target, "beginDkgResultSubmissionGasUpdate", [value as string])
),
// Submit only after each on-chain pending value and delay are checked.
finalize: updates.map(({ target }) =>
call(target, "finalizeDkgResultSubmissionGasUpdate")
),
},
null,
2
)
)
}

main().catch((error) => {
console.error(error)
process.exitCode = 1
})
14 changes: 10 additions & 4 deletions solidity/ecdsa/test/WalletRegistry.WalletCreation.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -1525,6 +1525,12 @@ describe("WalletRegistry - Wallet Creation", async () => {
})

describe("approveDkgResult", async () => {
// Identical inputs used 344,895 gas on the baseline and 344,968 with the
// saturating meter. Random inputs also reached a legacy-equivalent 345,015
// gas, so recenter at 345,000 plus the measured 73-gas metering overhead.
// Retain the original 15,000-gas tolerance.
const misbehavedApprovalGas = 345_000 + 73

context("with initial contract state", async () => {
it("should revert with 'Current state is not CHALLENGE' error", async () => {
await expect(
Expand Down Expand Up @@ -2067,8 +2073,8 @@ describe("WalletRegistry - Wallet Creation", async () => {
)
})

it("should use close to 330 000 gas", async () => {
await assertGasUsed(tx, 330_000, 15_000)
it("should use close to 345 073 gas", async () => {
await assertGasUsed(tx, misbehavedApprovalGas, 15_000)
})
})

Expand Down Expand Up @@ -2109,8 +2115,8 @@ describe("WalletRegistry - Wallet Creation", async () => {
await expect(tx).to.not.be.reverted
})

it("should use close to 330 000 gas", async () => {
await assertGasUsed(await tx, 330_000, 15_000)
it("should use close to 345 073 gas", async () => {
await assertGasUsed(await tx, misbehavedApprovalGas, 15_000)
})
}
)
Expand Down
5 changes: 5 additions & 0 deletions solidity/ecdsa/test/glamsterdam/wallet-registry-sourcify.json

Large diffs are not rendered by default.

Loading
Loading