diff --git a/contracts/.env.example b/contracts/.env.example index 5d9038354..ad50ac9ad 100644 --- a/contracts/.env.example +++ b/contracts/.env.example @@ -14,10 +14,11 @@ ADMIN_SAFE= # Fast pause guardian (small-threshold Safe). Can pause but NOT unpause, so a # compromised guardian can only halt, never release. Its signers must hold no -# attestor keys. Changeable later via setGuardian. +# attestor keys. Changeable later via setGuardian. The script refuses the +# deployer or an attestor address. GUARDIAN_SAFE= # The four attestor transaction-sender addresses (decision D4: 3-of-4, -# one per attestor node). +# one per attestor node); distinct, none of them the deployer. # Changeable later via addAttestor / removeAttestor. ATTESTOR_1= ATTESTOR_2= @@ -28,23 +29,28 @@ ATTESTOR_4= # script refuses any other value (Deploy.s.sol EXPECTED_MAX_ISSUANCE). MAX_ISSUANCE=150000000000000000000000000 -# Caps in 18-decimal units. Set equal to each other on purpose: a release -# blocked by the DAILY cap heals by itself as the rolling bucket refills and -# the releaser retries it, whereas one above the PER-RELEASE cap can only be -# cleared by a governance setCaps behind the 48h timelock. Keeping them equal -# removes that permanently-stuck band entirely, and the -# vault enforces PER_RELEASE_CAP <= DAILY_CAP on-chain (CapsInverted). +# Caps in 18-decimal units. The per-release cap is half the daily cap, so no +# single release takes the whole rolling allowance and smaller migrations +# still release while a large one waits for the bucket to refill. A release +# blocked by the DAILY cap heals by itself as the bucket refills and the +# releaser retries it; one above the PER-RELEASE cap waits for a setCaps +# (behind the 48h timelock once governance holds the vault), and the portal +# warns before such a burn. The vault enforces PER_RELEASE_CAP <= DAILY_CAP +# on-chain (CapsInverted); the script also refuses a per-release cap below +# 100 PEN (the smallest migration) and a daily cap above 3,000,000 PEN. # -# Soft launch: 1,000,000 PEN (below, active). Raise both to 3,000,000 by -# governance once the soft-launch checks pass — 3M/day is ~2% of supply per -# day, which clears the full supply well inside the migration window. -PER_RELEASE_CAP=1000000000000000000000000 +# Soft launch: 500,000 per release, 1,000,000 per day (below, active). Raise +# to 1,500,000 / 3,000,000 by governance once the soft-launch checks pass — +# 3M/day is ~2% of supply per day, which clears the full supply well inside +# the migration window. +PER_RELEASE_CAP=500000000000000000000000 DAILY_CAP=1000000000000000000000000 # PERMANENT. Unix timestamp in SECONDS before which the remainder CANNOT be # swept; the script refuses a value less than 30 days after the deploy block -# (2027-03-01 below passes for any deploy up to 2027-01-30) or more than two -# years ahead (a milliseconds value lands far beyond that). This is a floor on +# (2027-03-01 below passes for any deploy up to 2027-01-30), more than two +# years ahead (a milliseconds value lands far beyond that) or before +# 2027-03-01 (DECIDED_SWEEP_FLOOR; a later date is fine). This is a floor on # the earliest a sweep could happen, not a deadline for holders: closing the # window is a separate governance decision and can be deferred indefinitely. # @@ -60,8 +66,9 @@ DAILY_CAP=1000000000000000000000000 EARLIEST_SWEEP_TS=1803859200 # Testnet drills and local runs only: TEST_DEPLOY=true admits an ADMIN_SAFE -# that is not a Safe and an EARLIEST_SWEEP_TS less than 30 days ahead. Refused -# on Base mainnet; leave it unset for production. +# that is not a Safe, an EARLIEST_SWEEP_TS less than 30 days ahead or before +# 2027-03-01, and caps, guardian and attestors the script would otherwise +# refuse. Refused on Base mainnet; leave it unset for production. # TEST_DEPLOY= # --- DeployGovernance.s.sol (phase 5) --- @@ -72,18 +79,19 @@ TIMELOCK_DELAY=172800 # 48h (PRD V5); seconds, 48h to 30 days VOTING_DELAY=86400 # 1 day, seconds (timestamp clock), 1h to 30 days VOTING_PERIOD=432000 # 5 days, seconds, 1 to 30 days # 18-decimal token units required to propose, NOT whole PEN: the script -# refuses anything below 1 PEN (1e18) or above the total supply. -PROPOSAL_THRESHOLD= +# refuses anything below 10,000 PEN (1e22) or above 1,000,000 PEN (1e24). +PROPOSAL_THRESHOLD=50000000000000000000000 # 50,000 PEN # Percent of CIRCULATING supply (total minus the vault's unmigrated balance, # which setToken parks at the vote sink), counting For+Abstain # votes actually cast. Bounded below by QUORUM_FLOOR. 1 to 100; the script # refuses 0, which would leave quorum at the floor for good. QUORUM_FRACTION=2 # PERMANENT (immutable in the governor). Absolute quorum floor, 18-decimal -# token units, NOT whole PEN: the script refuses anything below 1 PEN (1e18) -# or above the total supply. Decide this before phase 5 — there is no safe -# default and the script refuses to run without it. Size it so quorum is -# reachable soon after launch, or no proposal (an unpause included) can pass. +# token units, NOT whole PEN: the script refuses anything below 100,000 PEN +# (1e23) or above 1,000,000 PEN (1e24). Decide this before phase 5 — there is +# no safe default and the script refuses to run without it. Size it so quorum +# is reachable soon after launch, or no proposal (an unpause included) can +# pass. QUORUM_FLOOR= # Required: a dedicated canceller Safe, separate from the guardian, granted # CANCELLER_ROLE on the timelock so a queued operation can still be vetoed @@ -95,6 +103,7 @@ QUORUM_FLOOR= TIMELOCK_CANCELLER= # Testnet drills only: TEST_DEPLOY=true admits a shorter TIMELOCK_DELAY, # VOTING_DELAY and VOTING_PERIOD, a TIMELOCK_CANCELLER that is not a Safe or -# is the guardian, QUORUM_FRACTION=0 and QUORUM_FLOOR=0. Refused on Base -# mainnet; leave it unset for production. +# is the guardian, QUORUM_FRACTION=0, QUORUM_FLOOR=0 and a PROPOSAL_THRESHOLD +# or QUORUM_FLOOR outside the ranges above. Refused on Base mainnet; leave it +# unset for production. # TEST_DEPLOY= diff --git a/contracts/README.md b/contracts/README.md index 4bf87f09f..7f42e4c17 100644 --- a/contracts/README.md +++ b/contracts/README.md @@ -42,8 +42,7 @@ forge build forge test ``` -## Open parameters (fixed at deployment, see PRD §4.2) +## Deployment parameters (fixed at deployment, see PRD §4.2) -- `maxIssuance` — exact figure pending decision D3 -- decimals/`conversionFactor` — 18/1e6 pending decision D2 -- attestor addresses, caps, `earliestSweepTimestamp` — decisions D4/D5 +Every value is documented in `.env.example`; the deploy scripts check each one +before broadcasting and refuse values outside their decided ranges. diff --git a/contracts/script/Deploy.s.sol b/contracts/script/Deploy.s.sol index f48db21be..80712be12 100644 --- a/contracts/script/Deploy.s.sol +++ b/contracts/script/Deploy.s.sol @@ -18,19 +18,24 @@ import {requireMultisigSafe} from "./SafeCheck.sol"; /// ADMIN_SAFE bootstrap Safe that becomes vault admin; must be a /// Safe on this chain with a threshold of at least 2 /// (getThreshold(); no EIP-7702 delegated EOA) -/// GUARDIAN_SAFE fast pause guardian -/// ATTESTOR_1..4 attestor transaction-sender addresses (D4: 3-of-4) +/// GUARDIAN_SAFE fast pause guardian; not the deployer or an attestor +/// ATTESTOR_1..4 attestor transaction-sender addresses (D4: 3-of-4); +/// distinct, none of them the deployer /// MAX_ISSUANCE max issuance in 18-decimal units (decision D3); /// must equal EXPECTED_MAX_ISSUANCE -/// PER_RELEASE_CAP initial per-release cap, 18-decimal units -/// DAILY_CAP initial daily cap, 18-decimal units +/// PER_RELEASE_CAP initial per-release cap, 18-decimal units; at least +/// MIN_PER_RELEASE_CAP and at most DAILY_CAP +/// DAILY_CAP initial daily cap, 18-decimal units; at most +/// MAX_INITIAL_DAILY_CAP /// EARLIEST_SWEEP_TS unix timestamp in SECONDS before which no remainder /// sweep (D5); at least MIN_SWEEP_FLOOR_AHEAD after -/// the deploy block and at most MAX_SWEEP_FLOOR_AHEAD +/// the deploy block and at most MAX_SWEEP_FLOOR_AHEAD, +/// not before DECIDED_SWEEP_FLOOR /// TEST_DEPLOY optional, testnet drills and local runs only: allows -/// an ADMIN_SAFE that is not a Safe and an -/// EARLIEST_SWEEP_TS any time in the future. Refused -/// on Base mainnet. +/// an ADMIN_SAFE that is not a Safe, an +/// EARLIEST_SWEEP_TS any time in the future, and caps, +/// guardian and attestors without the checks above. +/// Refused on Base mainnet. contract Deploy is Script { uint256 internal constant BASE_MAINNET = 8453; // 12-decimal pallet amounts -> 18-decimal token amounts (decision D2). @@ -45,6 +50,16 @@ contract Deploy is Script { uint256 internal constant MAX_SWEEP_FLOOR_AHEAD = 2 * 365 days; // A sweep floor closer than this is a drill value, not a migration window. uint256 internal constant MIN_SWEEP_FLOOR_AHEAD = 30 days; + // The decided floor, 2027-03-01 00:00 UTC. A later one is allowed; an + // earlier one is a superseded or mistyped date. + uint256 internal constant DECIDED_SWEEP_FLOOR = 1803859200; + // The caps can be changed later, but until then they bound what a release + // quorum can move before a pause. The smallest migration the pallet + // accepts is 100 PEN: a lower per-release cap would hold back every + // release. PRD V4 sizes the daily cap at 1-2% of the supply; more than + // 2% (3M PEN) is a units slip, not a launch value. + uint256 internal constant MIN_PER_RELEASE_CAP = 100e18; + uint256 internal constant MAX_INITIAL_DAILY_CAP = EXPECTED_MAX_ISSUANCE / 50; function run() external returns (PEN pen, MigrationVault vault) { bool testDeploy = vm.envOr("TEST_DEPLOY", false); @@ -68,6 +83,10 @@ contract Deploy is Script { earliestSweepTs >= block.timestamp + MIN_SWEEP_FLOOR_AHEAD || testDeploy, "EARLIEST_SWEEP_TS is less than 30 days after the deploy block" ); + require( + earliestSweepTs >= DECIDED_SWEEP_FLOOR || testDeploy, + "EARLIEST_SWEEP_TS is before the decided 2027-03-01 00:00 UTC" + ); address[] memory attestors = new address[](4); attestors[0] = vm.envAddress("ATTESTOR_1"); @@ -75,6 +94,24 @@ contract Deploy is Script { attestors[2] = vm.envAddress("ATTESTOR_3"); attestors[3] = vm.envAddress("ATTESTOR_4"); + if (!testDeploy) { + require( + perReleaseCap >= MIN_PER_RELEASE_CAP, "PER_RELEASE_CAP is below 100 PEN (18-decimal units expected)" + ); + require(perReleaseCap <= dailyCap, "PER_RELEASE_CAP is above DAILY_CAP"); + require(dailyCap <= MAX_INITIAL_DAILY_CAP, "DAILY_CAP is above 3M PEN, 2% of the supply"); + // The guardian's pause is the check on the attestors, so the roles + // are held apart from each other and from the deployer. + require(guardianSafe != msg.sender, "GUARDIAN_SAFE must not be the deployer"); + for (uint256 i = 0; i < attestors.length; i++) { + require(attestors[i] != msg.sender, "an attestor must not be the deployer"); + require(attestors[i] != guardianSafe, "GUARDIAN_SAFE must not be an attestor"); + for (uint256 j = 0; j < i; j++) { + require(attestors[i] != attestors[j], "ATTESTOR_1..4 must be distinct"); + } + } + } + // Broadcast as msg.sender (forge sets it to --sender or the single // signer), the address the interim admin role below is given to. vm.startBroadcast(msg.sender); diff --git a/contracts/script/DeployGovernance.s.sol b/contracts/script/DeployGovernance.s.sol index 8e93792d1..55137170a 100644 --- a/contracts/script/DeployGovernance.s.sol +++ b/contracts/script/DeployGovernance.s.sol @@ -31,12 +31,14 @@ import {requireMultisigSafe} from "./SafeCheck.sol"; /// VOTING_PERIOD seconds of voting, 1 day to 30 days /// PROPOSAL_THRESHOLD 18-decimal token units needed to propose, 1 PEN /// (1e18) to total supply; a whole-PEN figure such as -/// 50000 is refused +/// 50000 is refused. 10,000 to 1,000,000 PEN outside +/// TEST_DEPLOY /// QUORUM_FRACTION percent of CIRCULATING supply (total minus the /// vault's unmigrated balance parked at the vote /// sink, see PRD G1), 1 to 100 /// QUORUM_FLOOR absolute quorum lower bound, 18-decimal token -/// units, 1 PEN (1e18) to total supply; PERMANENT. +/// units, 1 PEN (1e18) to total supply, 100,000 to +/// 1,000,000 PEN outside TEST_DEPLOY; PERMANENT. /// Keeps early proposals from being trivially cheap /// while circulating supply is still small /// TIMELOCK_CANCELLER required: a dedicated canceller Safe, separate @@ -55,8 +57,9 @@ import {requireMultisigSafe} from "./SafeCheck.sol"; /// TEST_DEPLOY optional, testnet drills only: allows a shorter /// TIMELOCK_DELAY, VOTING_DELAY and VOTING_PERIOD, a /// TIMELOCK_CANCELLER that is not a Safe or is the -/// guardian, QUORUM_FRACTION=0 and QUORUM_FLOOR=0. -/// Refused on Base mainnet. +/// guardian, QUORUM_FRACTION=0, QUORUM_FLOOR=0 and a +/// PROPOSAL_THRESHOLD or QUORUM_FLOOR outside the +/// ranges above. Refused on Base mainnet. contract DeployGovernance is Script { uint256 internal constant BASE_MAINNET = 8453; uint256 internal constant MIN_TIMELOCK_DELAY = 2 days; @@ -67,6 +70,13 @@ contract DeployGovernance is Script { // Longer periods are a units slip (milliseconds land ~1000x further), and // a governor whose votes never end could not vote to shorten them. uint256 internal constant MAX_PERIOD = 30 days; + // The quorum floor is permanent, and a proposal threshold no holder + // reaches could only be lowered by a proposal nobody can make. Values + // outside these ranges are a zeros slip, not a sizing decision. + uint256 internal constant MIN_QUORUM_FLOOR = 100_000e18; + uint256 internal constant MAX_QUORUM_FLOOR = 1_000_000e18; + uint256 internal constant MIN_PROPOSAL_THRESHOLD = 10_000e18; + uint256 internal constant MAX_PROPOSAL_THRESHOLD = 1_000_000e18; function run() external returns (TimelockController timelock, PENGovernor governor) { bool testDeploy = vm.envOr("TEST_DEPLOY", false); @@ -94,6 +104,10 @@ contract DeployGovernance is Script { proposalThreshold >= 1e18 && proposalThreshold <= supply, "PROPOSAL_THRESHOLD must be 18-decimal units, 1 PEN to total supply" ); + require( + (proposalThreshold >= MIN_PROPOSAL_THRESHOLD && proposalThreshold <= MAX_PROPOSAL_THRESHOLD) || testDeploy, + "PROPOSAL_THRESHOLD must be 10,000 to 1,000,000 PEN" + ); // Zero leaves quorum at the permanent floor however much PEN // circulates. uint256 quorumFraction = vm.envUint("QUORUM_FRACTION"); @@ -103,6 +117,10 @@ contract DeployGovernance is Script { (quorumFloor >= 1e18 || (testDeploy && quorumFloor == 0)) && quorumFloor <= supply, "QUORUM_FLOOR must be 18-decimal units, 1 PEN to total supply" ); + require( + (quorumFloor >= MIN_QUORUM_FLOOR && quorumFloor <= MAX_QUORUM_FLOOR) || testDeploy, + "QUORUM_FLOOR must be 100,000 to 1,000,000 PEN" + ); address canceller = vm.envOr("TIMELOCK_CANCELLER", address(0)); require(canceller != address(0), "TIMELOCK_CANCELLER is required: no veto during the timelock delay otherwise"); diff --git a/contracts/test/DeployScripts.t.sol b/contracts/test/DeployScripts.t.sol index 470cba46b..f683a9d67 100644 --- a/contracts/test/DeployScripts.t.sol +++ b/contracts/test/DeployScripts.t.sol @@ -86,8 +86,8 @@ contract DeployScriptsTest is Test { vm.setEnv("ATTESTOR_3", vm.toString(makeAddr("attestor3"))); vm.setEnv("ATTESTOR_4", vm.toString(makeAddr("attestor4"))); vm.setEnv("MAX_ISSUANCE", "150000000000000000000000000"); - vm.setEnv("PER_RELEASE_CAP", "1000000000000000000000000"); - vm.setEnv("DAILY_CAP", "1000000000000000000000000"); + vm.setEnv("PER_RELEASE_CAP", "500000000000000000000000"); // 500,000 PEN + vm.setEnv("DAILY_CAP", "1000000000000000000000000"); // 1,000,000 PEN vm.setEnv("EARLIEST_SWEEP_TS", vm.toString(SWEEP_FLOOR)); } @@ -139,9 +139,31 @@ contract DeployScriptsTest is Test { // A production deploy on Base mainnet. vm.chainId(8453); _expectDeployRefused("TEST_DEPLOY", "true", "TEST_DEPLOY is refused on Base mainnet"); + string memory capTooLow = "PER_RELEASE_CAP is below 100 PEN (18-decimal units expected)"; + _expectDeployRefused("PER_RELEASE_CAP", "0", capTooLow); + _expectDeployRefused("PER_RELEASE_CAP", "500000", capTooLow); // whole PEN + _expectDeployRefused("PER_RELEASE_CAP", "99999999999999999999", capTooLow); + string memory capsInverted = "PER_RELEASE_CAP is above DAILY_CAP"; + _expectDeployRefused("DAILY_CAP", "0", capsInverted); + _expectDeployRefused("PER_RELEASE_CAP", "1000000000000000000000001", capsInverted); + string memory dailyTooHigh = "DAILY_CAP is above 3M PEN, 2% of the supply"; + _expectDeployRefused("DAILY_CAP", "3000000000000000000000001", dailyTooHigh); + _expectDeployRefused("DAILY_CAP", vm.toString(SUPPLY), dailyTooHigh); + _expectDeployRefused("GUARDIAN_SAFE", vm.toString(address(this)), "GUARDIAN_SAFE must not be the deployer"); + _expectDeployRefused( + "GUARDIAN_SAFE", vm.toString(makeAddr("attestor3")), "GUARDIAN_SAFE must not be an attestor" + ); + _expectDeployRefused("ATTESTOR_2", vm.toString(address(this)), "an attestor must not be the deployer"); + _expectDeployRefused("ATTESTOR_4", vm.toString(makeAddr("attestor1")), "ATTESTOR_1..4 must be distinct"); + // The superseded 2026-12-01 floor, 48 days after this deploy. + _expectDeployRefused( + "EARLIEST_SWEEP_TS", "1796083200", "EARLIEST_SWEEP_TS is before the decided 2027-03-01 00:00 UTC" + ); _setValidDeployEnv(); (PEN newPen, MigrationVault newVault) = deployScript.run(); vm.chainId(31337); + assertEq(newVault.perReleaseCap(), 500_000e18); + assertEq(newVault.dailyCap(), 1_000_000e18); assertEq(address(newVault.token()), address(newPen)); assertEq(newPen.totalSupply(), 150_000_000e18); assertEq(newPen.balanceOf(address(newVault)), 150_000_000e18); @@ -167,9 +189,9 @@ contract DeployScriptsTest is Test { vm.setEnv("TIMELOCK_DELAY", "172800"); vm.setEnv("VOTING_DELAY", "86400"); vm.setEnv("VOTING_PERIOD", "432000"); - vm.setEnv("PROPOSAL_THRESHOLD", "1000000000000000000000"); // 1,000 PEN + vm.setEnv("PROPOSAL_THRESHOLD", "50000000000000000000000"); // 50,000 PEN vm.setEnv("QUORUM_FRACTION", "2"); - vm.setEnv("QUORUM_FLOOR", "100000000000000000000000"); // 100,000 PEN + vm.setEnv("QUORUM_FLOOR", "250000000000000000000000"); // 250,000 PEN vm.setEnv("TIMELOCK_CANCELLER", vm.toString(canceller)); } @@ -247,6 +269,15 @@ contract DeployScriptsTest is Test { // A production deploy on Base mainnet. vm.chainId(8453); _expectGovernanceRefused("TEST_DEPLOY", "true", "TEST_DEPLOY is refused on Base mainnet"); + // Zeros slips in the permanent floor and in the threshold. + string memory floorRange = "QUORUM_FLOOR must be 100,000 to 1,000,000 PEN"; + _expectGovernanceRefused("QUORUM_FLOOR", "250000000000000000000", floorRange); // 250 PEN + _expectGovernanceRefused("QUORUM_FLOOR", "99999999999999999999999", floorRange); + _expectGovernanceRefused("QUORUM_FLOOR", "5000000000000000000000000", floorRange); // 5M PEN + _expectGovernanceRefused("QUORUM_FLOOR", "100000000000000000000000000", floorRange); // 100M PEN + string memory thresholdRange = "PROPOSAL_THRESHOLD must be 10,000 to 1,000,000 PEN"; + _expectGovernanceRefused("PROPOSAL_THRESHOLD", "50000000000000000000", thresholdRange); // 50 PEN + _expectGovernanceRefused("PROPOSAL_THRESHOLD", "5000000000000000000000000", thresholdRange); // 5M PEN _setValidGovernanceEnv(); (TimelockController timelock, PENGovernor governor) = governanceScript.run(); vm.chainId(31337); @@ -265,9 +296,9 @@ contract DeployScriptsTest is Test { assertEq(address(governor.token()), address(pen)); assertEq(governor.votingDelay(), 1 days); assertEq(governor.votingPeriod(), 5 days); - assertEq(governor.proposalThreshold(), 1_000e18); + assertEq(governor.proposalThreshold(), 50_000e18); assertEq(governor.quorumNumerator(), 2); - assertEq(governor.quorumFloor(), 100_000e18); + assertEq(governor.quorumFloor(), 250_000e18); // Testnet drills: short delays and voting, no quorum fraction or floor // and the guardian key, not a Safe, as canceller. diff --git a/docs/pen-migration-security.md b/docs/pen-migration-security.md index e4ab6b42c..bcf18c025 100644 --- a/docs/pen-migration-security.md +++ b/docs/pen-migration-security.md @@ -31,8 +31,8 @@ team, and the safeguards below limit what a compromise can do. ## Safeguards - **Release caps.** A per-release cap and a rolling daily cap limit how much - can leave the vault (1,000,000 PEN each for the soft launch, raised by - governance later). + can leave the vault (500,000 PEN per release and 1,000,000 PEN per day for + the soft launch, raised by governance later). - **Pause.** A guardian can pause releases in a single transaction but can never unpause; unpausing requires the vault admin. - **Admin changes.** Admin transfers are two-step. After the governance