Skip to content
NodleCodePublic

About

Nodle Network on zkSync/EVM

Resources

Stars

11 stars

Watchers

4 watching

Forks

Repository files navigation

Nodle's Eth L2 rollup powered by zkSync stack

Banner

Development setup

Note

We recommend you run within the provided devcontainer to ensure you have all the necessary tooling installed such zksync-cli, and forge.

For subquery utilization refer to Nodle-zksync-subquery

Repo organization

  • ./ contains Nodle's constellation of smart contracts, tools and services for L1 Ethereum and L2 ZkSync operations.
    • ./lib contains libraries we depend on.
    • ./src contains contract sources.
    • ./script contains forge scripts.
    • ./hardhat-deploy contains typescript deployment scripts compiled and run by hardhat.
    • ./test contains unit tests.
    • ./subquery contains a custom subquery for this project.
    • ./utils contains typescript utilities such as batch-register for clk names.
    • ./ops contains shell scripts for operational tasks like deployment orchestration, maintenance, and chain interaction

Conventions

  • all files should be licensed under the BSD 3 Clear Clause license with the required file header // SPDX-License-Identifier: BSD-3-Clause-Clear
  • when writing scripts, ensure that:
    • input environment variables are prefixed with N_ to differentiate them from forge environment variables
    • an example usage is added to this readme file
    • naming aligns with existing script files
  • when writing new contracts, ensure that:
    • proper unit tests are written, no PR should be merged without proper unit testing
    • OpenZeppelin is used extensively whenever possible as to reduce audit risk
  • while we do have a compatibility layer with hardhat, scripts, tests and contracts need to be fully usable via forge itself by default
  • if deploying a contract, ensure it is verified on Etherscan

Mainnet Deployments

Please refer to the Nodle on ZKsync documentation for main contract addresses.

Usage

Build

$ forge build --zksync --zk-optimizer

Test

$ forge test

Format

$ forge fmt

Deployment

Please see scripts in ./scripts and refer to the forge documentation for additional arguments. You will need to specify additional arguments when deploying to mainnet or verifying the contracts on Etherscan such as --rpc-url and --broadcast.

Deploying Click contracts

Please define the following environment variables:

  • N_WHITELIST_ADMIN: address of the whitelist admin on the paymaster whitelist contract (typically the onboard or sponsorship API address).
  • N_WITHDRAWER: address of the account allowed to withdraw ETH from the paymaster contract.
  • deployer address will be set as super admin.
$ forge script script/DeployClick.s.sol --zksync
[⠒] Compiling...
[⠆] Compiling 1 files with 0.8.20
[⠰] Solc 0.8.20 finished in 8.47s

Script ran successfully.
Gas used: 1821666

== Logs ==
  Deployed ClickContentSign at 0x90193C961A926261B756D1E5bb255e67ff9498A1
  Deployed WhitelistPaymaster at 0x34A1D3fff3958843C43aD80F30b94c510645C316
  Please ensure you fund the paymaster contract with enough ETH!

If you wish to simulate on-chain transactions pass a RPC URL.

Deploying ContentSign Enterprise contracts

Please define the following environment variables:

  • N_NAME: name of the NFT contract deployed.
  • N_SYMBOL: symbol of the NFT contract deployed.

Here is a full example for a Sepolia deployment: N_NAME=ExampleContentSign N_SYMBOL=ECS forge script script/DeployContentSignEnterprise.s.sol --zksync --rpc-url https://sepolia.era.zksync.dev --zk-optimizer -i 1 --broadcast.

Once deployed, the script will output the contract address, and the account you deployed with will be set as the administrator of this contract with the possibility to grant other users minting access. You may onboard a new user with cast via the following command template:

export ETH_RPC_URL=https://sepolia.era.zksync.dev     # use the appropriate RPC here
export NFT=0x195e4E251c41e8Ae9E9E961366C73e2CFbfB115A # use your own contract address here
export ROLE=`cast call $NFT "WHITELISTED_ROLE()(bytes32)"`

# Of course, replace 0x68e3981280792A19cC03B5A770B82a6497f0A464 with the address of
# the user whom you'd like to onboard - this is only here for example
cast send -i $NFT "grantRole(bytes32,address)" $ROLE 0x68e3981280792A19cC03B5A770B82a6497f0A464

Deploying NODL and NODLMigration contract

In the following example N_VOTER1_ADDR is the public address of the bridge oracle whose role is going to be a voter for funds coming from the parachain side. Similarly N_VOTER2_ADDR and N_VOTER3_ADDR are addresses of the other two voter oracles. The closer oracle does not need special permissions and thus need not to be mentioned. NOTE: i flag in the command will make the tool prompt you for the private key of the deployer. So remember to have that handy but you don't need to define it in your environment.

N_VOTER1_ADDR="0x18AB6B4310d89e9cc5521D33D5f24Fb6bc6a215E" \
N_VOTER2_ADDR="0x571C969688991C6A35420C62d44666c47eB3F752" \
N_VOTER3_ADDR="0x0cBCE4Ab8ADe1398bA10Fca2A19B5Aa332312Fb1" \
forge script script/DeployNodlMigration.sol --zksync --rpc-url https://sepolia.era.zksync.dev --zk-optimizer -i 1 --broadcast

Afterwards the user you onboarded should be able to mint NFTs as usual via the safeMint(ownerAddress, metadataUri) function.

Deploying MigrationNFT contract

The MigrationNFT contract allows the minting of a reward SoulBound NFT when users bridge enough tokens through NODLMigration. Users can "level up" depending on the amount of tokens they bring in, with each levels being a sorted list of bridged amounts.

You will need to set the following environment variables:

  • N_MIGRATION: address of the NODLMigration contract
  • N_MAX_HOLDERS: maximum number of participants
  • N_LEVELS: number of levels to set
  • N_LEVELS_x where x is an integer from 0 to N_LEVELS - 1: actual number of tokens for each level
  • N_LEVELS_URI_x where x is an integer from 0 to N_LEVELS - 1: actual metadata URL for the NFTs

You can then run the script script/DeployMigrationNFT.s.sol very similarly to the below:

N_MIGRATION=0x1427d38B967435a3F8f476Cda0bc4F51fe66AF4D \
N_MAX_HOLDERS=10000 \
N_LEVELS=3 \
N_LEVELS_0=100 \
N_LEVELS_1=200 \
N_LEVELS_2=300 \
N_LEVELS_URI_0=example.com \
N_LEVELS_URI_1=example.com \
N_LEVELS_URI_2=example.com \
forge script script/DeployMigrationNFT.s.sol --zksync --rpc-url https://sepolia.era.zksync.dev --zk-optimizer -i 1 --broadcast

Deploying Staking contract

Allow users with at least 50,000 NODL (Dolphin level) to participate in a staking contract with the following characteristics:

Functional Requirements

  • Restricted access: Only users holding 50,000 NODL or more can stake.

  • Staking cap: The contract accepts a maximum total of 5 million NODL per staker. Additionally, the contract has a global staking cap MAX_POOL_STAKE.

  • Limited duration: Staking lasts the DURATION in seconds passed as a parameter.

  • Guaranteed yield: Users receive a fixed reward, predefined in the contract, at the end of the staking period.

  • Return: Once the staking period ends, both the staked tokens and the yield are returned to the user via a claim function.

Deployment

DEPLOYER_PRIVATE_KEY=0x... \
GOV_ADDR=0x2D1941280530027B6bA80Af0e7bD8c2135783368 \
STAKE_TOKEN=0xb4B74C2BfeA877672B938E408Bae8894918fE41C \
MIN_STAKE=50000 \
MAX_TOTAL_STAKE=5000000 \
DURATION=3600 \
REWARD_RATE=12 \
REQUIRED_HOLDING_TOKEN=50000 \
npx hardhat deploy-zksync --script deploy_staking.dp.ts --network zkSyncSepoliaTestnet
  • DEPLOYER_PRIVATE_KEY: Private key of the deploying account.
  • GOV_ADDR: Address of the governance contract (receives admin, rewards-manager, and emergency-manager roles).
  • STAKE_TOKEN: Address of the token to stake.
  • MIN_STAKE: Minimum amount of tokens a user can stake (whole tokens, scaled by 1e18 in the script).
  • MAX_TOTAL_STAKE: Maximum amount of tokens a single user can stake (whole tokens, scaled by 1e18).
  • DURATION: Duration of the staking period, in seconds.
  • REWARD_RATE: Reward rate as a whole-number percent of the staked amount, paid at the end of the period.
  • REQUIRED_HOLDING_TOKEN: Minimum token balance a user must hold to participate (whole tokens, scaled by 1e18).

Trust assumptions

The admin account (GOV_ADDR) holds the default-admin, rewards-manager, and emergency-manager roles. It can pause the contract (which blocks claim/unstake), toggle unstakeAllowed (which defaults to false, so before the period ends users can only exit once the admin enables it), and — while paused — call emergencyWithdraw to sweep the entire contract balance, including staked principal. Deployments intended for untrusted users should split these roles and/or place them behind a timelock or multisig.

Deploying the fundraising contracts

Deploys FundraiserFactory, which creates one Fundraiser contract per fundraise. There is no implementation contract and no proxy to deploy — the factory creates each fundraise with new, and zksolc registers that bytecode as a factory dependency at compile time.

Please define the following environment variables:

  • N_FUNDRAISING_ADMIN: multisig that will hold DEFAULT_ADMIN_ROLE.
  • N_FUNDRAISING_TOKENS: comma-separated ERC-20 addresses allowed at launch, e.g. USDC and NODL for the network.
  • N_FUNDRAISING_FEE_BPS: optional, defaults to 0. Capped by MAX_FEE_BPS (500).
  • N_FUNDRAISING_FEE_RECIPIENT: optional, required only when the rate is non-zero.

The allow-list is seeded in the constructor because the admin is expected to be a multisig the deploy script cannot act for. A fee rate set with no recipient is rejected rather than silently collecting nothing.

export DEPLOYER_PRIVATE_KEY=0x...
export N_FUNDRAISING_ADMIN=0x...
export N_FUNDRAISING_TOKENS=0xUSDC...,0xNODL...

forge script script/DeployFundraiserFactory.s.sol \
    --rpc-url https://sepolia.era.zksync.dev --broadcast --zksync

Only the factory needs verifying; each fundraise is a full contract created from bytecode already published by the factory.

Verification uses the ZKsync explorer's own verifier rather than the manual Etherscan flow described further down:

export ARGS=$(cast abi-encode "constructor(address,uint16,address,address[])" \
    $N_FUNDRAISING_ADMIN 0 0x0000000000000000000000000000000000000000 "[$NODL]")

forge verify-contract <FACTORY_ADDRESS> src/fundraising/FundraiserFactory.sol:FundraiserFactory \
    --zksync --verifier zksync --verifier-url $L2_VERIFIER_URL \
    --constructor-args $ARGS --watch

Individual fundraises are created by the factory, so they never appear in a broadcast file. Their constructor parameters are all readable from the deployed contract, and ops/verify_fundraiser.sh reconstructs them from chain and submits through the same Python helper:

./ops/verify_fundraiser.sh <FUNDRAISER_ADDRESS> testnet   # or mainnet

Note

Run deployments through ops/deploy_fundraising_zksync.sh rather than calling forge script directly. forge build --zksync compiles the whole tree, and zksolc rejects an L1-only contract elsewhere in src/ that uses EXTCODECOPY; the ops script temporarily moves those files aside and restores them on exit, the same pattern the swarms and collections deploy scripts use. It also gates on factoryDependencies being populated — empty means createFundraiser would revert on EraVM while passing every EVM-profile test — and verifies source through ops/verify_zksync_contracts.py, which rewrites imports to project-rooted paths that the ZKsync verifier will accept.

Fees ship switched off. The capability exists — the rate is snapshotted into each fundraise at creation, so raising it later cannot reach anything already in flight — but turning it on is a product decision:

export ETH_RPC_URL=https://sepolia.era.zksync.dev
export FACTORY=0x...   # from the deploy output

# 250 = 2.5%
cast send -i $FACTORY "setFeeParams(uint16,address)" 250 0xFeeRecipient...

# allowing another token for future fundraises
cast send -i $FACTORY "setTokenAllowed(address,bool)" 0xToken... true

De-listing a token only stops new fundraises choosing it. Deposits, withdrawals and refunds on live fundraises are never affected, so de-listing cannot become a freeze switch.

Scripts

Checking on bridging proposals

Given a tracker id (proposal) and the bridge address you may run the script available in ./script/CheckBridge.s.sol. The script will output proposal details and outline expectations as to the proposal's execution timeline. Here is a simple example:

N_PROPOSAL_ID=c43005c880cad7b699122b403607187a78251b9850d387521ffb123c473e3392 \
N_BRIDGE=0x5de7fe085ee66Fb48447e75AA8fb0598a080AEe0 \
forge script script/CheckBridge.s.sol --zksync --rpc-url https://mainnet.era.zksync.io

Whitelisting new users on ContentSign contracts

Given a user and contract address, you can whitelist new users on contracts derived from EnterpriseContentSign with the ContentSignWhitelist script. Note that this assumes your own key has been granted admin permissions on this same contract. Here is a simple example for a testnet contract:

N_CONTENTSIGN=0x195e4E251c41e8Ae9E9E961366C73e2CFbfB115A \
N_WHITELIST=0x732e40223f57d7a1dbf340f5c0cc5b363b60428b \
forge script script/ContentSignWhitelist.s.sol -i 1 --zksync --rpc-url https://sepolia.era.zksync.dev --broadcast

Claiming vested grants manually

Vested NODL is held by the Grants contract. The Nodle client at zkclient.nodle.com (the "Grants" tab) is the easiest way to claim, but claiming is fully self-service on-chain and needs no app and no off-chain signature — you only need the wallet that holds the grant and a small amount of ETH on ZKsync Era for gas. This section shows how to claim directly with cast.

export ETH_RPC_URL=https://mainnet.era.zksync.io
# Grants contract — confirm the current address against the docs (see "Mainnet Deployments" above)
export GRANTS=0x5855c486d2381ba41762876f18684951d5902829
export ME=0xYourGranteeAddress

# How many vesting schedules does your address have, and how many pages they span?
cast call $GRANTS "getGrantsCount(address)(uint256)" $ME
cast call $GRANTS "currentPage(address)(uint256)" $ME

# Claim everything that has vested up to now, across all pages.
# claim(uint256 start, uint256 end) iterates pages [start, end); passing 0, 0 means "all pages".
cast send -i $GRANTS "claim(uint256,uint256)" 0 0

Notes:

  • claim transfers only what has vested up to the current block timestamp; you can call it again later as more periods vest. On success it emits Claimed(address who, uint256 amount, uint256 start, uint256 end).
  • If nothing is currently claimable the call reverts with NoOpIsFailure().
  • For large numbers of schedules you can claim a single page range (e.g. claim 0 1) to bound gas rather than sweeping every page at once.
  • Prefer a UI? The same claim call can be made from the Write Contract tab of the verified Grants contract on explorer.zksync.io.

DePIN rewards are different: they are minted via Rewards.mintReward against an oracle-signed voucher (domain rewards.depin.nodle), which is normally submitted for you by the Nodle backend, so the self-service path above applies to vested grants rather than reward issuance.

Contract verification

Caution

The below steps are not for the faint of heart. Contract verification is technically not supported yet by the zkSync foundry fork, and the instructions below are likely to break (in which case feel free to update them via a PR).

Verification on Etherscan is best done via the Solidity Json Input method as it is the least error prone and most reliable. To do so, you will need a few elements:

  1. Contract address, which you typically get from script outputs.
  2. solc and zksolc versions, which you can identify based on the pragma header of the solidity contracts, or by checking what binaries are on your system:
$ ls ~/.zksync/
solc-macosx-arm64-0.8.23-1.0.0 zksolc-macosx-arm64-v1.4.1

In the sample case above, we are using solc 0.8.23 and zksolc 1.4.1. 3. The Solidity Json Input file, which you can get by following the below instructions

  1. Build the contracts and ask for the build-info via forge build --zksync --zk-optimizer --build-info
  2. Access the said build-info at path ./out/build-info, you will find there a JSON file (if you have more than one, take the most recent one)
  3. Open the JSON file and select the value under the input key
  4. Due to some incompatibilities, normalize the JSON value by removing the keys settings.metadata and settings.viaIR
  5. The contract inputs, which you can regenerate if you know the input values you deployed the contract with. Or that you can fetch by viewing your deployment transaction on explorer.zksync.io. To do, you will need to:
  6. Open your deployment transaction on explorer.zksync.io (make sure to select the testnet if you are using the zkSync Era testnet)
  7. Look for the input data variable named _input
  8. Copy paste its value and strip the `0x prefix as Etherscan will throw an error otherwise

Use all these artifacts on the contract verification page on Etherscan for your given contract (open your contract on Etherscan, select Contract and the link starting with Verify). When prompted, enter the compiler versions, the license (we use BSD-3 Clause Clear). Then on the next page, enter your normalized JSON input file, and the contract constructor inputs.

Additional resources

ZkSync CLI useful commands

Approve

npx zksync-cli contract write --chain "zksync-sepolia" --contract "0xb4B74C2BfeA877672B938E408Bae8894918fE41C" --method "approve(address spender, uint256 amount)" --args "0x2D1941280530027B6bA80Af0e7bD8c2135783368" "1000000000000000000"

Stake

npx zksync-cli contract write --chain "zksync-sepolia" --contract "0xb974a544128Bc7fAB3447D48cd6ad377D6F62EcF" --method "stake(uint256 amount)" --args "1000000000000000000"

About

Nodle Network on zkSync/EVM

Resources

Stars

11 stars

Watchers

4 watching

Forks

Releases

Packages

Used by

Contributors

Languages