From 76a03741ecaa4a704a21777574aa23cb06139e25 Mon Sep 17 00:00:00 2001 From: douglasacost Date: Tue, 3 Nov 2026 14:29:58 -0400 Subject: [PATCH 1/7] feat(payment): forge deploy script for Payment instances, with input checks --- script/DeployPaymentZkSync.s.sol | 92 +++++++++++++++++++++++ test/DeployPaymentZkSync.t.sol | 122 +++++++++++++++++++++++++++++++ 2 files changed, 214 insertions(+) create mode 100644 script/DeployPaymentZkSync.s.sol create mode 100644 test/DeployPaymentZkSync.t.sol diff --git a/script/DeployPaymentZkSync.s.sol b/script/DeployPaymentZkSync.s.sol new file mode 100644 index 00000000..465f0cfa --- /dev/null +++ b/script/DeployPaymentZkSync.s.sol @@ -0,0 +1,92 @@ +// SPDX-License-Identifier: BSD-3-Clause-Clear + +pragma solidity ^0.8.26; + +import {Script, console} from "forge-std/Script.sol"; +import {IERC20Metadata} from "@openzeppelin/contracts/token/ERC20/extensions/IERC20Metadata.sol"; + +import {Payment} from "../src/Payment.sol"; + +/** + * @title DeployPaymentZkSync + * @notice Deployment script for a general-purpose `Payment` instance (the payouts contract) on ZkSync Era. + * @dev The contract pays NODL out to recipients in batches, capped by a per-period quota. The admin + * (a Safe) funds it, tunes the quota and period, and can withdraw. The oracle (the payer key) + * calls `pay`. The deployer ends up holding no role: both roles go to the constructor arguments. + * + * Gas sponsorship for the oracle is not part of this deployment. It is a separate Safe batch on + * `BondTreasuryPaymaster`. + * + * Usage: + * forge script script/DeployPaymentZkSync.s.sol \ + * --rpc-url $L2_RPC --broadcast --zksync + * + * Environment Variables: + * - DEPLOYER_PRIVATE_KEY: Private key with ETH for gas. Must not be the payer key. + * - N_TOKEN_ADDR: NODL token address. + * - N_PAYMENT_ADMIN: Multisig that will hold DEFAULT_ADMIN_ROLE. + * - N_PAYMENT_ORACLE: Payer key, granted ORACLE_ROLE. + * - N_PAYMENT_QUOTA: Total NODL (wei) that may be paid per period. + * - N_PAYMENT_PERIOD: Optional quota period in seconds, defaults to 1 day. + */ +contract DeployPaymentZkSync is Script { + /// @dev Mirrors `QuotaControl.MAX_PERIOD`. Solidity cannot read a contract's constant without an + /// instance, so the test suite pins this value to the deployed contract's constant. + uint256 public constant MAX_PERIOD = 30 days; + + struct Params { + address token; + address admin; + address oracle; + uint256 quota; + uint256 period; + } + + function run() external returns (Payment) { + uint256 deployerPrivateKey = vm.envUint("DEPLOYER_PRIVATE_KEY"); + Params memory p = Params({ + token: vm.envAddress("N_TOKEN_ADDR"), + admin: vm.envAddress("N_PAYMENT_ADMIN"), + oracle: vm.envAddress("N_PAYMENT_ORACLE"), + quota: vm.envUint("N_PAYMENT_QUOTA"), + period: vm.envOr("N_PAYMENT_PERIOD", uint256(1 days)) + }); + + return deployWith(p, deployerPrivateKey); + } + + function deployWith(Params memory p, uint256 deployerKey) public returns (Payment) { + address deployer = vm.addr(deployerKey); + validate(p, deployer); + + console.log("=== Deploying Payment on ZkSync ==="); + console.log("NODL:", p.token); + console.log("Admin:", p.admin); + console.log("Oracle:", p.oracle); + console.log("Quota / period:", p.quota, p.period); + + vm.startBroadcast(deployerKey); + Payment payment = new Payment(p.oracle, p.token, p.quota, p.period, p.admin); + vm.stopBroadcast(); + + require(payment.hasRole(payment.DEFAULT_ADMIN_ROLE(), p.admin), "admin role not granted"); + require(payment.hasRole(payment.ORACLE_ROLE(), p.oracle), "oracle role not granted"); + require(!payment.hasRole(payment.DEFAULT_ADMIN_ROLE(), deployer), "deployer holds the admin role"); + require(!payment.hasRole(payment.ORACLE_ROLE(), deployer), "deployer holds the oracle role"); + + console.log(""); + console.log("Payment:", address(payment)); + + return payment; + } + + /// @notice Rejects inputs that would deploy a misconfigured instance; the token cannot be changed afterwards. + function validate(Params memory p, address deployer) public view { + require(p.token != address(0) && p.admin != address(0) && p.oracle != address(0), "zero address"); + require(p.admin != p.oracle, "N_PAYMENT_ADMIN equals N_PAYMENT_ORACLE"); + require(deployer != p.oracle, "deploy with a key other than the payer"); + require(p.quota >= 1 ether, "N_PAYMENT_QUOTA is below 1 NODL, amounts are in wei"); + require(p.period != 0 && p.period <= MAX_PERIOD, "N_PAYMENT_PERIOD out of range"); + require(keccak256(bytes(IERC20Metadata(p.token).symbol())) == keccak256("NODL"), "N_TOKEN_ADDR is not NODL"); + } +} diff --git a/test/DeployPaymentZkSync.t.sol b/test/DeployPaymentZkSync.t.sol new file mode 100644 index 00000000..97329e33 --- /dev/null +++ b/test/DeployPaymentZkSync.t.sol @@ -0,0 +1,122 @@ +// SPDX-License-Identifier: BSD-3-Clause-Clear +pragma solidity ^0.8.26; + +import {Test} from "forge-std/Test.sol"; +import {ERC20} from "@openzeppelin/contracts/token/ERC20/ERC20.sol"; + +import {DeployPaymentZkSync} from "../script/DeployPaymentZkSync.s.sol"; +import {Payment} from "../src/Payment.sol"; + +contract MockNodl is ERC20 { + constructor() ERC20("Nodle", "NODL") {} +} + +contract MockOther is ERC20 { + constructor() ERC20("Other", "MTK") {} +} + +/// @dev These tests call `validate` and `deployWith` directly and never set env vars: +/// `forge test` runs tests in parallel and `vm.setEnv` would race between them. +contract DeployPaymentZkSyncTest is Test { + uint256 internal constant DEPLOYER_KEY = 0xA11CE; + + DeployPaymentZkSync internal deployScript; + MockNodl internal nodl; + MockOther internal other; + address internal deployer; + address internal admin; + address internal oracle; + + function setUp() public { + deployScript = new DeployPaymentZkSync(); + nodl = new MockNodl(); + other = new MockOther(); + deployer = vm.addr(DEPLOYER_KEY); + admin = makeAddr("safe"); + oracle = makeAddr("payer"); + } + + function _baseParams() internal view returns (DeployPaymentZkSync.Params memory) { + return DeployPaymentZkSync.Params({ + token: address(nodl), admin: admin, oracle: oracle, quota: 200_000 ether, period: 1 days + }); + } + + function test_deployWith_setsTokenQuotaPeriodAndRoles() public { + Payment payment = deployScript.deployWith(_baseParams(), DEPLOYER_KEY); + + assertEq(address(payment.token()), address(nodl)); + assertEq(payment.quota(), 200_000 ether); + assertEq(payment.period(), 1 days); + assertTrue(payment.hasRole(payment.ORACLE_ROLE(), oracle)); + assertTrue(payment.hasRole(payment.DEFAULT_ADMIN_ROLE(), admin)); + } + + function test_deployWith_deployerHoldsNoRole() public { + Payment payment = deployScript.deployWith(_baseParams(), DEPLOYER_KEY); + + assertFalse(payment.hasRole(payment.DEFAULT_ADMIN_ROLE(), deployer)); + assertFalse(payment.hasRole(payment.ORACLE_ROLE(), deployer)); + } + + function test_validate_rejectsAdminEqualsOracle() public { + DeployPaymentZkSync.Params memory p = _baseParams(); + p.admin = p.oracle; + + vm.expectRevert(bytes("N_PAYMENT_ADMIN equals N_PAYMENT_ORACLE")); + deployScript.validate(p, deployer); + } + + function test_validate_rejectsDeployerIsOracle() public { + DeployPaymentZkSync.Params memory p = _baseParams(); + p.oracle = deployer; + + vm.expectRevert(bytes("deploy with a key other than the payer")); + deployScript.validate(p, deployer); + } + + function test_validate_rejectsQuotaBelowOneNodl() public { + DeployPaymentZkSync.Params memory p = _baseParams(); + p.quota = 200_000; + + vm.expectRevert(bytes("N_PAYMENT_QUOTA is below 1 NODL, amounts are in wei")); + deployScript.validate(p, deployer); + } + + function test_validate_rejectsPeriodOutOfRange() public { + DeployPaymentZkSync.Params memory p = _baseParams(); + + p.period = 0; + vm.expectRevert(bytes("N_PAYMENT_PERIOD out of range")); + deployScript.validate(p, deployer); + + p.period = 31 days; + vm.expectRevert(bytes("N_PAYMENT_PERIOD out of range")); + deployScript.validate(p, deployer); + + // The script's bound must track QuotaControl.MAX_PERIOD: the limit itself is accepted, one second over is not. + Payment deployed = deployScript.deployWith(_baseParams(), DEPLOYER_KEY); + assertEq(deployScript.MAX_PERIOD(), deployed.MAX_PERIOD()); + p.period = deployed.MAX_PERIOD(); + deployScript.validate(p, deployer); + p.period = deployed.MAX_PERIOD() + 1; + vm.expectRevert(bytes("N_PAYMENT_PERIOD out of range")); + deployScript.validate(p, deployer); + } + + function test_validate_rejectsNonNodlToken() public { + DeployPaymentZkSync.Params memory p = _baseParams(); + p.token = address(other); + + vm.expectRevert(bytes("N_TOKEN_ADDR is not NODL")); + deployScript.validate(p, deployer); + } + + function test_validate_rejectsZeroAddress() public { + DeployPaymentZkSync.Params memory p = _baseParams(); + p.admin = address(0); + + vm.expectRevert(bytes("zero address")); + deployScript.validate(p, deployer); + } +} From 2949d317c64a61ee671fd285643e52563d47df9c Mon Sep 17 00:00:00 2001 From: douglasacost Date: Tue, 3 Nov 2026 14:35:19 -0400 Subject: [PATCH 2/7] ops(payment): zkSync deploy wrapper for Payment instances --- ops/deploy_payment_zksync.sh | 62 ++++++++++++++++++++++++++++++++++++ 1 file changed, 62 insertions(+) create mode 100755 ops/deploy_payment_zksync.sh diff --git a/ops/deploy_payment_zksync.sh b/ops/deploy_payment_zksync.sh new file mode 100755 index 00000000..07531b2e --- /dev/null +++ b/ops/deploy_payment_zksync.sh @@ -0,0 +1,62 @@ +#!/usr/bin/env bash +# Deploys a general-purpose Payment instance (the payouts contract) on zkSync (Sepolia or mainnet) +# with forge --zksync. zksolc cannot compile the L1-only SwarmRegistryL1Upgradeable (EXTCODECOPY), so +# the L1-only files are moved aside for the compile and restored on exit, exactly as +# ops/deploy_collection_factory_zksync.sh and ops/upgrade_collection_factory_zksync.sh do. +# +# Usage: +# DEPLOYER_PRIVATE_KEY=0x… N_TOKEN_ADDR=0x… N_PAYMENT_ADMIN=0x… N_PAYMENT_ORACLE=0x… \ +# N_PAYMENT_QUOTA=… \ +# ops/deploy_payment_zksync.sh [--broadcast] +# +# N_PAYMENT_QUOTA is in wei. N_PAYMENT_PERIOD (seconds, default 1 day) is optional. See +# script/DeployPaymentZkSync.s.sol for the input checks it applies before it broadcasts. +# +# Without --broadcast the script simulates only. The broadcast JSON lands in +# broadcast/DeployPaymentZkSync.s.sol//run-latest.json; verify afterwards with +# python3 ops/verify_zksync_contracts.py --broadcast . +set -euo pipefail +cd "$(dirname "$0")/.." + +NETWORK="${1:-}"; BROADCAST="${2:-}" +case "$BROADCAST" in + ""|--broadcast) ;; + *) echo "usage: $0 [--broadcast] (second argument must be exactly --broadcast or omitted)"; exit 1 ;; +esac +case "$NETWORK" in + testnet) RPC_URL="${L2_RPC:-https://sepolia.era.zksync.dev}" ;; + mainnet) RPC_URL="${L2_RPC:-https://mainnet.era.zksync.io}" ;; + *) echo "usage: $0 [--broadcast]"; exit 1 ;; +esac +: "${DEPLOYER_PRIVATE_KEY:?}" "${N_TOKEN_ADDR:?}" "${N_PAYMENT_ADMIN:?}" "${N_PAYMENT_ORACLE:?}" "${N_PAYMENT_QUOTA:?}" +[[ "$DEPLOYER_PRIVATE_KEY" == 0x* ]] || export DEPLOYER_PRIVATE_KEY="0x${DEPLOYER_PRIVATE_KEY}" +if [[ "$NETWORK" == "mainnet" && "$BROADCAST" == "--broadcast" && "${CONFIRM_MAINNET:-}" != "YES" ]]; then + echo "mainnet broadcast requires CONFIRM_MAINNET=YES"; exit 1 +fi + +L1_BACKUP_DIR="/tmp/rollup-l1-backup-payment" +restore_l1_contracts() { + [ -d "$L1_BACKUP_DIR" ] || return 0 + [ -f "$L1_BACKUP_DIR/SwarmRegistryL1Upgradeable.sol" ] && mv "$L1_BACKUP_DIR/SwarmRegistryL1Upgradeable.sol" src/swarms/ + [ -f "$L1_BACKUP_DIR/SwarmRegistryL1.t.sol" ] && mv "$L1_BACKUP_DIR/SwarmRegistryL1.t.sol" test/ + [ -d "$L1_BACKUP_DIR/upgrade-demo" ] && mv "$L1_BACKUP_DIR/upgrade-demo" test/ + [ -f "$L1_BACKUP_DIR/DeploySwarmUpgradeable.s.sol" ] && mv "$L1_BACKUP_DIR/DeploySwarmUpgradeable.s.sol" script/ + [ -f "$L1_BACKUP_DIR/UpgradeSwarm.s.sol" ] && mv "$L1_BACKUP_DIR/UpgradeSwarm.s.sol" script/ + rm -rf "$L1_BACKUP_DIR" + echo "L1-only contracts restored" +} +move_l1_contracts() { + [ -d "$L1_BACKUP_DIR" ] && restore_l1_contracts + mkdir -p "$L1_BACKUP_DIR" + [ -f src/swarms/SwarmRegistryL1Upgradeable.sol ] && mv src/swarms/SwarmRegistryL1Upgradeable.sol "$L1_BACKUP_DIR/" + [ -f test/SwarmRegistryL1.t.sol ] && mv test/SwarmRegistryL1.t.sol "$L1_BACKUP_DIR/" + [ -d test/upgrade-demo ] && mv test/upgrade-demo "$L1_BACKUP_DIR/" + [ -f script/DeploySwarmUpgradeable.s.sol ] && mv script/DeploySwarmUpgradeable.s.sol "$L1_BACKUP_DIR/" + [ -f script/UpgradeSwarm.s.sol ] && mv script/UpgradeSwarm.s.sol "$L1_BACKUP_DIR/" + echo "L1-only contracts moved aside for the zksync compile" +} +trap restore_l1_contracts EXIT +move_l1_contracts + +echo "network=$NETWORK rpc=$RPC_URL admin=$N_PAYMENT_ADMIN oracle=$N_PAYMENT_ORACLE broadcast=${BROADCAST:-no}" +forge script script/DeployPaymentZkSync.s.sol --rpc-url "$RPC_URL" --zksync --skip test ${BROADCAST:+--broadcast --slow} From 9f899bdf7cc518cb6918be63a80f72875dd7613d Mon Sep 17 00:00:00 2001 From: douglasacost Date: Wed, 4 Nov 2026 09:51:12 -0400 Subject: [PATCH 3/7] docs(payment): describe the Payment contract --- src/doc/Payment.md | 130 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 130 insertions(+) create mode 100644 src/doc/Payment.md diff --git a/src/doc/Payment.md b/src/doc/Payment.md new file mode 100644 index 00000000..178184c2 --- /dev/null +++ b/src/doc/Payment.md @@ -0,0 +1,130 @@ +# Payment + +`src/Payment.sol`, built on `src/QuotaControl.sol` + +## Purpose + +`Payment` holds a balance of one ERC-20 token. Accounts with `ORACLE_ROLE` pay that balance out to recipients, and the total they can pay is capped per period. The admin sets the cap and can withdraw the balance. + +## Constructor + +```solidity +constructor(address oracle, address _token, uint256 initialQuota, uint256 initialPeriod, address admin) +``` + +| Param | Purpose | +| --------------- | ------------------------------------------------------------------------------------------------------- | +| `oracle` | First account granted `ORACLE_ROLE`. | +| `_token` | The ERC-20 token the contract pays in. Immutable. | +| `initialQuota` | The most that `pay` can send in one period, in the token's smallest unit. | +| `initialPeriod` | The period length in seconds. It must be greater than 0 and at most `MAX_PERIOD` (30 days). | +| `admin` | Account granted `DEFAULT_ADMIN_ROLE`. | + +The first period ends at deployment time plus `initialPeriod`. + +## Roles + +| Role | Can call | +| -------------------- | ------------------------------------------------------------------------------ | +| `DEFAULT_ADMIN_ROLE` | `setQuota`, `setPeriod`, `withdraw`, and `grantRole` / `revokeRole` for both roles | +| `ORACLE_ROLE` | `pay` | + +`ORACLE_ROLE` can be held by several accounts at once. They all draw on the same balance and the same quota. An account that sends transactions from more than one process needs its own nonce handling, so giving each independent caller its own oracle account is simpler. + +## State + +| Variable | Meaning | +| ----------------------- | -------------------------------------------------------------------------- | +| `token` | The token paid out. Immutable. | +| `quota` | The most that can be paid in the current period. | +| `period` | The period length in seconds. | +| `quotaRenewalTimestamp` | When the current period ends. | +| `claimed` | The amount paid in the current period, as of the last `pay`. | +| `MAX_PERIOD` | 30 days, a constant. | + +## Paying + +```solidity +function pay(address[] calldata recipients, uint256 amount) external onlyRole(ORACLE_ROLE) +``` + +`pay` sends the same `amount` to every address in `recipients`. Paying different amounts takes one call per amount. In order, it: + +1. Requires `ORACLE_ROLE`, or reverts with `AccessControlUnauthorizedAccount`. +2. Computes `needed = recipients.length * amount`. If the contract's token balance is below `needed`, it reverts with `InsufficientBalance(balance, needed)`. +3. Starts a new period if the current one has ended (see below). +4. Adds `needed` to `claimed`. If the result is above `quota`, it reverts with `QuotaExceeded`. +5. Transfers `amount` to each recipient in list order, using `SafeERC20`. + +A recipient listed twice is paid twice. The contract keeps no record of who was paid or why, so calling `pay` twice with the same arguments pays twice. A caller that must not pay twice needs its own record of what it sent. + +The contract emits no payment event of its own. Each payment shows up as the token's `Transfer` event from the contract's address to the recipient. + +## Quota periods + +A period does not roll over on a timer. The first `pay` at or after `quotaRenewalTimestamp` resets `claimed` to 0 and moves `quotaRenewalTimestamp` to the next boundary on the original schedule: + +``` +quotaRenewalTimestamp = now + period - ((now - quotaRenewalTimestamp) % period) +``` + +For example, with a period of 1 day, a contract deployed at `T` has period boundaries at `T + 1 day`, `T + 2 days`, and so on. A first `pay` at `T + 2.5 days` starts the period that ends at `T + 3 days`. Boundaries follow the deployment time, not midnight. + +- **`setQuota(newQuota)`** applies at once, to the current period too. Setting it below `claimed` blocks `pay` until the period ends, and setting it to 0 blocks `pay` entirely. It emits `QuotaSet`. +- **`setPeriod(newPeriod)`** changes the length of periods from the next reset on. It does not move the current `quotaRenewalTimestamp`. It reverts with `ZeroPeriod` for 0 and `TooLongPeriod` above `MAX_PERIOD`, and emits `PeriodSet`. + +## Funding and withdrawing + +There is no deposit function. The contract is funded by a plain token transfer to its address, from any account. + +```solidity +function withdraw(address recipient, uint256 amount) external onlyRole(DEFAULT_ADMIN_ROLE) +``` + +`withdraw` sends `amount` of the token to `recipient`. It does not count toward the quota. + +## Stopping payments + +There is no pause function. The admin can stop payments in two ways: + +- Set the quota to 0. This stops every oracle at once. +- Revoke `ORACLE_ROLE` from one account. This stops only that account. + +Withdrawing the balance also makes every later `pay` revert with `InsufficientBalance`. + +## Events and errors + +| Event / error | When | +| ------------------------------------------------------ | ------------------------------------------------- | +| `QuotaSet(uint256 quota)` | `setQuota` | +| `PeriodSet(uint256 period)` | `setPeriod` | +| `RoleGranted` / `RoleRevoked` | Role changes (OpenZeppelin `AccessControl`) | +| `InsufficientBalance(uint256 balance, uint256 needed)` | `pay` needs more than the contract holds | +| `QuotaExceeded()` | `pay` would take `claimed` above `quota` | +| `ZeroPeriod()` / `TooLongPeriod()` | A period of 0, or above `MAX_PERIOD` | +| `AccessControlUnauthorizedAccount(account, role)` | A caller without the required role | + +## Gas sponsorship + +`Payment` does not depend on how its callers pay for gas. On ZkSync, an oracle can send `pay` through a general-flow paymaster that sponsors the contract and the oracle, such as `WhitelistPaymaster` or `BondTreasuryPaymaster` in `src/paymasters/`. Whitelisting the contract on such a paymaster lets every whitelisted user call it for free. That opens nothing new: every function that changes state requires a role, except `renounceRole`, which only drops the caller's own role. + +## Deploying on ZkSync + +`ops/deploy_payment_zksync.sh [--broadcast]` runs `script/DeployPaymentZkSync.s.sol` with `forge script --zksync`. Without `--broadcast` it only simulates. A mainnet broadcast also needs `CONFIRM_MAINNET=YES`. + +| Variable | Value | +| ---------------------- | ----------------------------------------------------------- | +| `DEPLOYER_PRIVATE_KEY` | The deploying account. It ends up holding no role. | +| `N_TOKEN_ADDR` | The token. Its `symbol()` must be `NODL`. | +| `N_PAYMENT_ADMIN` | `DEFAULT_ADMIN_ROLE` holder. | +| `N_PAYMENT_ORACLE` | First `ORACLE_ROLE` holder. Not the admin, not the deployer.| +| `N_PAYMENT_QUOTA` | Quota in wei. At least 1 token (`1e18`). | +| `N_PAYMENT_PERIOD` | Optional period in seconds. Defaults to 1 day. | + +The script refuses invalid inputs before anything is sent. After the simulated deployment, it checks that the admin and the oracle hold their roles and that the deployer holds neither. + +Verify the deployed source with: + +```bash +python3 ops/verify_zksync_contracts.py --broadcast broadcast/DeployPaymentZkSync.s.sol//run-latest.json --verifier-url +``` From eff6384c1918aaa598ab0fbc83a957f730fb7c10 Mon Sep 17 00:00:00 2001 From: douglasacost Date: Thu, 5 Nov 2026 09:36:40 -0400 Subject: [PATCH 4/7] ops(payment): let verify_zksync_contracts.py verify a Payment broadcast Map DeployPaymentZkSync.s.sol's single unnamed deployment to src/Payment.sol:Payment, so the verify command in src/doc/Payment.md works. --- ops/verify_zksync_contracts.py | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/ops/verify_zksync_contracts.py b/ops/verify_zksync_contracts.py index 2d7deca0..41ea5780 100755 --- a/ops/verify_zksync_contracts.py +++ b/ops/verify_zksync_contracts.py @@ -93,6 +93,7 @@ "FundraiserFactory": "src/fundraising/FundraiserFactory.sol:FundraiserFactory", "Fundraiser": "src/fundraising/Fundraiser.sol:Fundraiser", "ArcadeEscrow": "src/arcade/ArcadeEscrow.sol:ArcadeEscrow", + "Payment": "src/Payment.sol:Payment", } # Some zkSync forge broadcasts record deployments as calls to ContractDeployer @@ -130,6 +131,9 @@ "DeployArcadeEscrow.s.sol": [ "ArcadeEscrow", ], + "DeployPaymentZkSync.s.sol": [ + "Payment", + ], } From 247cd73366192d39c4ecbb595be2a87c3d8f53d4 Mon Sep 17 00:00:00 2001 From: douglasacost Date: Thu, 5 Nov 2026 11:19:40 -0400 Subject: [PATCH 5/7] ops(payment): record the payouts contract deployments and its paymaster whitelist batch Mainnet 0x4D5e78077BC149bC1c8ED8BEd1Cb4b973a975f5B and Sepolia 0x0E1Afd9e7e5f505193d67206e2c2aD544F5c2376, both verified. The Safe batch whitelists the mainnet contract and its oracle on BondTreasuryPaymaster. --- .cspell.json | 3 +- ops/payouts-deployments.md | 86 +++++++++++++++++++++++ ops/safe/payouts-paymaster-whitelist.json | 27 +++++++ 3 files changed, 115 insertions(+), 1 deletion(-) create mode 100644 ops/payouts-deployments.md create mode 100644 ops/safe/payouts-paymaster-whitelist.json diff --git a/.cspell.json b/.cspell.json index c8ccfe89..dd778162 100644 --- a/.cspell.json +++ b/.cspell.json @@ -189,6 +189,7 @@ "publicnode", "drpc", "apikey", - "Firestore" + "Firestore", + "adjoe" ] } diff --git a/ops/payouts-deployments.md b/ops/payouts-deployments.md new file mode 100644 index 00000000..055a02ae --- /dev/null +++ b/ops/payouts-deployments.md @@ -0,0 +1,86 @@ +# Payouts contract — deployments + +Deployment record for the payouts contract, an instance of [`src/Payment.sol`](../src/Payment.sol) described in [`src/doc/Payment.md`](../src/doc/Payment.md). Backend programs pay users NODL from it, each through its own `ORACLE_ROLE` key. + +## Mainnet (ZKsync Era, chain 324) + +| Contract | Address | Verified | +|---|---|---| +| `Payment` | [`0x4D5e78077BC149bC1c8ED8BEd1Cb4b973a975f5B`](https://explorer.zksync.io/address/0x4D5e78077BC149bC1c8ED8BEd1Cb4b973a975f5B#contract) | yes | + +- Deployed 2026-11-05 in tx [`0xa802693a…e3d8`](https://explorer.zksync.io/tx/0xa802693a2c974cc3630db2a136e56d95633bce01145ca9b9f26248dcd3fde3d8) from `0x0cC73B6E713DdFc1c2B26C841C45ddad60AA772A`, which holds no role. +- Token: L2 NODL `0xBD4372e44c5eE654dd838304006E1f0f69983154`. +- Admin (`DEFAULT_ADMIN_ROLE`): `0x5e097AC1BCF81E7Ff2657045F72cAa6cF06486C9`, the 2-of-4 Safe. It alone can withdraw, change the quota or period, and grant or revoke `ORACLE_ROLE`. +- Funded by plain NODL transfers to the contract's address. It held 0 NODL at deploy. + +| Parameter | Value | +|---|---| +| `quota` / `period` | 200,000 NODL / 1 day | +| Period boundary | 14:51:15 UTC daily, the deploy time | +| `MAX_PERIOD` | 30 days (constant) | + +### Oracles + +Each program that pays from the contract holds its own `ORACLE_ROLE` key, so no two services share a nonce. All of them draw on the same balance and the same quota. + +| Oracle | Held by | Private key | Program | +|---|---|---|---| +| `0xD49f0d1c1D058e0ceA178113500b939f4BD02eFf` | multi-token-api | GCP Secret Manager `multi-token-api-payouts-oracle-key` (project `nodle-network-production`) | adjoe rewards | + +### Adding a program + +1. The program creates its own oracle key. It never reuses another program's key. +2. The Safe grants it `ORACLE_ROLE` on the contract, and adds it to the paymaster with `addWhitelistedUsers([oracle])`. +3. The Safe raises `quota` by the program's daily volume, and treasury adds its funding. +4. Add a row to the oracles table above. + +### Gas sponsorship + +Oracles pay no gas: their `pay` transactions use the general flow of `BondTreasuryPaymaster` [`0xb253528104D8C23eE14647410deDf70A9092bfFE`](https://explorer.zksync.io/address/0xb253528104D8C23eE14647410deDf70A9092bfFE). The paymaster checks only that the sender is a whitelisted user and the destination a whitelisted contract. The Safe holds its `WHITELIST_ADMIN_ROLE`, so one Safe transaction covers both: + +- `addWhitelistedContracts([payouts contract])` +- `addWhitelistedUsers([oracle])` + +Import [`safe/payouts-paymaster-whitelist.json`](safe/payouts-paymaster-whitelist.json) in the Safe Transaction Builder. No bond allowance is needed: an oracle never calls `consumeSponsoredBond`. Neither address was whitelisted at deploy. + +Whitelisting is shared across the paymaster's lists. An oracle can also send sponsored transactions to the other whitelisted contracts, but every state-changing function on this contract requires a role, so other whitelisted users gain nothing here. + +On Sepolia, a sponsored one-recipient `pay` from the oracle estimated at 315,196 gas on 2026-11-05. + +## Sepolia (ZKsync Era Sepolia, chain 300) + +| Contract | Address | Verified | +|---|---|---| +| `Payment` | [`0x0E1Afd9e7e5f505193d67206e2c2aD544F5c2376`](https://sepolia.explorer.zksync.io/address/0x0E1Afd9e7e5f505193d67206e2c2aD544F5c2376#contract) | yes | + +- Deployed 2026-11-05 in tx [`0xac781a62…8e57`](https://sepolia.explorer.zksync.io/tx/0xac781a62f379a080bb3eefc0e9d0736949f79f41935f72e42b8af46e5fba8e57) from `0x81df54C68DDE05CB1Bf988bc2433ae5A5da01B51`, which holds no role. +- Token: Sepolia NODL `0xb4B74C2BfeA877672B938E408Bae8894918fE41C`. +- Admin (`DEFAULT_ADMIN_ROLE`): `0xc1F2A7b888e4837aFACfc5E914AB647476ceCD46`. +- `quota` / `period`: 200,000 NODL / 1 day, with the period boundary at 14:15:34 UTC. +- Funded with 1,000 NODL in tx [`0xb36b0864…870c`](https://sepolia.explorer.zksync.io/tx/0xb36b0864a07580709c0de81a173d61c7e71b5866f2ddfdce7a9f1e606ebe870c). + +| Oracle | Held by | Private key | Program | +|---|---|---|---| +| `0x9386B99cfeaA0C146EAFC4a6773de1513b084A7A` | multi-token-api (staging) | GCP Secret Manager `multi-token-api-payouts-oracle-key` (project `staging-309410`) | adjoe rewards | + +Both are whitelisted on the Sepolia `BondTreasuryPaymaster` [`0x6FFD3a0C03f6Fb55406C2E1b71a35Cf2997F13A5`](https://sepolia.explorer.zksync.io/address/0x6FFD3a0C03f6Fb55406C2E1b71a35Cf2997F13A5), sent from its whitelist admin `0xc1F2…cD46`: the contract in tx `0xfd3cbc68…e76e` and the oracle in tx `0xcdafbcd1…d345`. + +## Deploy and verify + +The deployer must not be the oracle, and must not be the admin: the script refuses a deployer that ends up holding either role. + +```bash +CONFIRM_MAINNET=YES DEPLOYER_PRIVATE_KEY=0x… \ +N_TOKEN_ADDR=0xBD4372e44c5eE654dd838304006E1f0f69983154 \ +N_PAYMENT_ADMIN=0x5e097AC1BCF81E7Ff2657045F72cAa6cF06486C9 \ +N_PAYMENT_ORACLE=0xD49f0d1c1D058e0ceA178113500b939f4BD02eFf \ +N_PAYMENT_QUOTA=200000000000000000000000 \ +N_PAYMENT_PERIOD=86400 \ + ops/deploy_payment_zksync.sh mainnet --broadcast +``` + +```bash +python3 ops/verify_zksync_contracts.py --broadcast broadcast/DeployPaymentZkSync.s.sol/324/run-latest.json --verifier-url https://zksync2-mainnet-explorer.zksync.io/contract_verification +``` + +For Sepolia, use `testnet` without `CONFIRM_MAINNET`, the Sepolia values above, `broadcast/DeployPaymentZkSync.s.sol/300/run-latest.json` and `--verifier-url https://explorer.sepolia.era.zksync.dev/contract_verification`. diff --git a/ops/safe/payouts-paymaster-whitelist.json b/ops/safe/payouts-paymaster-whitelist.json new file mode 100644 index 00000000..ac3e959e --- /dev/null +++ b/ops/safe/payouts-paymaster-whitelist.json @@ -0,0 +1,27 @@ +{ + "version": "1.0", + "chainId": "324", + "createdAt": 1793891897000, + "meta": { + "name": "Payouts contract: sponsor oracle gas via BondTreasuryPaymaster", + "description": "Whitelist the payouts Payment contract 0x4D5e78077BC149bC1c8ED8BEd1Cb4b973a975f5B as a destination and its oracle 0xD49f0d1c1D058e0ceA178113500b939f4BD02eFf as a user on BondTreasuryPaymaster 0xb253528104D8C23eE14647410deDf70A9092bfFE.", + "txBuilderVersion": "1.18.0", + "createdFromSafeAddress": "0x5e097AC1BCF81E7Ff2657045F72cAa6cF06486C9" + }, + "transactions": [ + { + "to": "0xb253528104D8C23eE14647410deDf70A9092bfFE", + "value": "0", + "data": "0x25daffef000000000000000000000000000000000000000000000000000000000000002000000000000000000000000000000000000000000000000000000000000000010000000000000000000000004d5e78077bc149bc1c8ed8bed1cb4b973a975f5b", + "contractMethod": null, + "contractInputsValues": null + }, + { + "to": "0xb253528104D8C23eE14647410deDf70A9092bfFE", + "value": "0", + "data": "0x6496d3fc00000000000000000000000000000000000000000000000000000000000000200000000000000000000000000000000000000000000000000000000000000001000000000000000000000000d49f0d1c1d058e0cea178113500b939f4bd02eff", + "contractMethod": null, + "contractInputsValues": null + } + ] +} From a67a115406d7885e4ae998e0149a1e2113321fdb Mon Sep 17 00:00:00 2001 From: Alex Sedighi Date: Mon, 9 Nov 2026 13:03:04 +1300 Subject: [PATCH 6/7] Implement network chain ID validation in deploy script Add network validation for mainnet and testnet in deployment script. Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- ops/deploy_payment_zksync.sh | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/ops/deploy_payment_zksync.sh b/ops/deploy_payment_zksync.sh index 07531b2e..d7df5d62 100755 --- a/ops/deploy_payment_zksync.sh +++ b/ops/deploy_payment_zksync.sh @@ -33,6 +33,14 @@ esac if [[ "$NETWORK" == "mainnet" && "$BROADCAST" == "--broadcast" && "${CONFIRM_MAINNET:-}" != "YES" ]]; then echo "mainnet broadcast requires CONFIRM_MAINNET=YES"; exit 1 fi +case "$NETWORK" in + testnet) EXPECTED_CHAIN_ID=300 ;; + mainnet) EXPECTED_CHAIN_ID=324 ;; +esac +ACTUAL_CHAIN_ID="$(cast chain-id --rpc-url "$RPC_URL")" +if [[ "$ACTUAL_CHAIN_ID" != "$EXPECTED_CHAIN_ID" ]]; then + echo "RPC chain ID $ACTUAL_CHAIN_ID does not match $NETWORK ($EXPECTED_CHAIN_ID)"; exit 1 +fi L1_BACKUP_DIR="/tmp/rollup-l1-backup-payment" restore_l1_contracts() { From 619de3b722cfadff49b2773f22134cae54c911ef Mon Sep 17 00:00:00 2001 From: Alex Sedighi Date: Mon, 9 Nov 2026 13:04:04 +1300 Subject: [PATCH 7/7] Use temporary directory for L1 backup Replace static backup directory with a temporary one created using mktemp. Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- ops/deploy_payment_zksync.sh | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/ops/deploy_payment_zksync.sh b/ops/deploy_payment_zksync.sh index d7df5d62..a379050d 100755 --- a/ops/deploy_payment_zksync.sh +++ b/ops/deploy_payment_zksync.sh @@ -42,7 +42,7 @@ if [[ "$ACTUAL_CHAIN_ID" != "$EXPECTED_CHAIN_ID" ]]; then echo "RPC chain ID $ACTUAL_CHAIN_ID does not match $NETWORK ($EXPECTED_CHAIN_ID)"; exit 1 fi -L1_BACKUP_DIR="/tmp/rollup-l1-backup-payment" +L1_BACKUP_DIR="$(mktemp -d "${TMPDIR:-/tmp}/rollup-l1-backup-payment.XXXXXX")" restore_l1_contracts() { [ -d "$L1_BACKUP_DIR" ] || return 0 [ -f "$L1_BACKUP_DIR/SwarmRegistryL1Upgradeable.sol" ] && mv "$L1_BACKUP_DIR/SwarmRegistryL1Upgradeable.sol" src/swarms/ @@ -54,8 +54,6 @@ restore_l1_contracts() { echo "L1-only contracts restored" } move_l1_contracts() { - [ -d "$L1_BACKUP_DIR" ] && restore_l1_contracts - mkdir -p "$L1_BACKUP_DIR" [ -f src/swarms/SwarmRegistryL1Upgradeable.sol ] && mv src/swarms/SwarmRegistryL1Upgradeable.sol "$L1_BACKUP_DIR/" [ -f test/SwarmRegistryL1.t.sol ] && mv test/SwarmRegistryL1.t.sol "$L1_BACKUP_DIR/" [ -d test/upgrade-demo ] && mv test/upgrade-demo "$L1_BACKUP_DIR/"