Skip to content
Merged
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
57 changes: 33 additions & 24 deletions contracts/.env.example
Original file line number Diff line number Diff line change
Expand Up @@ -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=
Expand All @@ -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.
#
Expand All @@ -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) ---
Expand All @@ -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
Expand All @@ -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=
7 changes: 3 additions & 4 deletions contracts/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
53 changes: 45 additions & 8 deletions contracts/script/Deploy.s.sol
Original file line number Diff line number Diff line change
Expand Up @@ -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).
Expand All @@ -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);
Expand All @@ -68,13 +83,35 @@ 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");
attestors[1] = vm.envAddress("ATTESTOR_2");
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);
Expand Down
26 changes: 22 additions & 4 deletions contracts/script/DeployGovernance.s.sol
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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;
Expand All @@ -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);
Expand Down Expand Up @@ -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");
Expand All @@ -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");
Expand Down
Loading
Loading