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
3 changes: 2 additions & 1 deletion .cspell.json
Original file line number Diff line number Diff line change
Expand Up @@ -189,6 +189,7 @@
"publicnode",
"drpc",
"apikey",
"Firestore"
"Firestore",
"adjoe"
]
}
68 changes: 68 additions & 0 deletions ops/deploy_payment_zksync.sh
Original file line number Diff line number Diff line change
@@ -0,0 +1,68 @@
#!/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 <testnet|mainnet> [--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/<chainId>/run-latest.json; verify afterwards with
# python3 ops/verify_zksync_contracts.py --broadcast <that file>.
set -euo pipefail
cd "$(dirname "$0")/.."

NETWORK="${1:-}"; BROADCAST="${2:-}"
case "$BROADCAST" in
""|--broadcast) ;;
*) echo "usage: $0 <testnet|mainnet> [--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 <testnet|mainnet> [--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
Comment thread
Copilot marked this conversation as resolved.
Resolved
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="$(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/
[ -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() {
[ -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}
86 changes: 86 additions & 0 deletions ops/payouts-deployments.md
Original file line number Diff line number Diff line change
@@ -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`.
27 changes: 27 additions & 0 deletions ops/safe/payouts-paymaster-whitelist.json
Original file line number Diff line number Diff line change
@@ -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
}
]
}
4 changes: 4 additions & 0 deletions ops/verify_zksync_contracts.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -130,6 +131,9 @@
"DeployArcadeEscrow.s.sol": [
"ArcadeEscrow",
],
"DeployPaymentZkSync.s.sol": [
"Payment",
],
}


Expand Down
92 changes: 92 additions & 0 deletions script/DeployPaymentZkSync.s.sol
Original file line number Diff line number Diff line change
@@ -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");
}
}
Loading
Loading