Sophon Documentation

This guide is retained only for maintaining an existing Sophon v1 deployment. Do not start a new production deployment on the chain.

Installing Foundry

On your command line, run:

curl -L https://raw.githubusercontent.com/matter-labs/foundry-zksync/main/install-foundry-zksync | bash

You can find more info on the official ZKsync Foundry website.

Create a New Project

forge init
forge build --zksync

This will create a new simple Foundry project with a Counter contract.

Set Configs

A full baseline Foundry example can be found on our GitHub here.

Set your foundry.toml and .env as follows:

# The Default Profile
[profile.default]
solc_version = "0.8.24"
zksolc_version = "1.5.11"
src = "src"
out = "out"
libs = ["lib"]
remappings = [
    "@openzeppelin/contracts/=lib/openzeppelin-contracts/contracts/",
]

[etherscan]
sepoliaTestnet = { key = "${ETHERSCAN_API_KEY}", url = "${SEPOLIA_VERIFIER_URL}", chain = 11155111 }
testnet = { key = "${ETHERSCAN_API_KEY}", url = "${SOPHON_TESTNET_VERIFIER_URL}", chain = 531050104 }
sophon = { key = "${ETHERSCAN_API_KEY}", url = "${SOPHON_VERIFIER_URL}", chain = 50104 }
ethereum = { key = "${ETHERSCAN_API_KEY}", url = "${VERIFIER_URL}", chain = 1 }

[rpc_endpoints]
sepoliaTestnet = "${SEPOLIA_RPC_URL}"
testnet = "${SOPHON_TESTNET_RPC_URL}"
sophon = "${SOPHON_RPC_URL}"
ethereum = "${RPC_URL}"

# See more config options https://github.com/foundry-rs/foundry/blob/master/crates/config/README.md#all-options

PRIVATE_KEY="" # YOUR_PRIVATE_KEY your developer private key here
ETHERSCAN_API_KEY="YOUR_ETHERSCAN_API_KEY" # your Sophscan API gey obtained from sophscan
PAYMASTER_ADDRESS=0x98546B226dbbA8230cf620635a1e4ab01F6A99B2 # the paymaster address you want to use

# ethereum sepolia
SEPOLIA_RPC_URL=https://eth-sepolia.g.alchemy.com/v2/sp2BM_VFMURcKWMWg8HDVSBgvnm75_NS
SEPOLIA_VERIFIER_URL=https://api.etherscan.io/api
SEPOLIA_CHAIN_ID="11155111"

# ethereum
RPC_URL=https://ethereum-rpc.publicnode.com
VERIFIER_URL=https://api.etherscan.io/api
CHAIN_ID="1"

# sophon testnet
SOPHON_TESTNET_RPC_URL=https://rpc.testnet.sophon.xyz
SOPHSCAN_TESTNET_VERIFIER_URL="https://api-sepolia.etherscan.io/api"
SOPHON_TESTNET_VERIFIER_URL=https://api-explorer-verify.testnet.sophon.xyz/contract_verification
SOPHON_TESTNET_CHAIN_ID="531050104"

# sophon
SOPHON_RPC_URL=https://rpc.sophon.xyz
SOPHSCAN_MAINNET_VERIFIER_URL="https://api.sophscan.xyz/api"
SOPHON_VERIFIER_URL=https://verification-explorer.sophon.xyz/contract_verification
SOPHON_CHAIN_ID="50104"

In order to obtain a Sophscan API Key, you need to create an account and get an API Key here.

Counter Contract Deployment

Basic Deployment

If you run into deployment or interaction issues, always check for possible short-circuit errors caused by environment variables not being properly exposed to the foundry script. You can do so by running source .env before running the script or check the variable in your env by running echo $VARIABLE_NAME.

source .env && forge create ./src/Counter.sol:Counter \
--rpc-url testnet --private-key $PRIVATE_KEY --zksync

Deployment and Verification

Same as Basic Deployment but you append the --verify flag and use the --verifier zksync flag to specify the verifier to use the Sophon Explorer or --verifier etherscan to use Sophscan.

This will only verify on Sophscan

source .env && forge create ./src/Counter.sol:Counter --rpc-url testnet \
 --private-key $PRIVATE_KEY --zksync --verifier zksync \
 --verifier-url $TESTNET_VERIFIER_URL  

Deployment Using Paymaster

Same as Basic Deployment but you append the --zk-paymaster-address flag

The paymaster allows you to perform gasless transactions, so there’s no need to have a SOPH balance

source .env && forge create ./src/Counter.sol:Counter \
--rpc-url testnet --private-key $PRIVATE_KEY --zksync \
--zk-paymaster-address $PAYMASTER_ADDRESS \
--zk-paymaster-input $(cast calldata "general(bytes)" "0x")

Deployment With Paymaster and Verification (All-in-One)

source .env && forge create ./src/Counter.sol:Counter \
--rpc-url testnet --private-key $PRIVATE_KEY --zksync \
--zk-paymaster-address $PAYMASTER_ADDRESS \
--zk-paymaster-input $(cast calldata "general(bytes)" "0x") --verify \
--verifier zksync --verifier-url $TESTNET_VERIFIER_URL

Deploy Contracts Using Foundry Scripts

Deployment Using Script

source .env && forge script ./script/Counter.s.sol \
--rpc-url testnet --private-key $PRIVATE_KEY --zksync --broadcast

Deployment Using Script and Verification

Same as Deployment Using Script but you append the --verify flag

This will only verify on Sophscan

source .env && forge create ./src/Counter.sol:Counter \
--rpc-url testnet --private-key $PRIVATE_KEY --zksync --verify \
--verifier zksync --verifier-url $TESTNET_VERIFIER_URL

Deployment Using Script With Paymaster

Same as Deployment Using Script but you append the --zk-paymaster-address flag

This will only verify on Sophscan

To use the paymaster within a script, you have 2 options: using a cheatcode or making a low-level call:

Using a Foundry Cheatcode

Install forge-zksync-std library
Use the vmExt.zkUsePaymaster cheatcode

For your convenience, you can copy-paste the following script:

// SPDX-License-Identifier: UNLICENSED
pragma solidity ^0.8.13;

import {Script, console} from "forge-std/Script.sol";
import {Counter} from "../src/Counter.sol";
import {TestExt} from "lib/forge-zksync-std/src/TestExt.sol";

contract CounterScript is Script, TestExt {
    Counter public counter;

    function setUp() public {}

    function run() public {
        vm.startBroadcast();

        // Encode paymaster input
        bytes memory paymaster_encoded_input = abi.encodeWithSelector(
            bytes4(keccak256("general(bytes)")),
            bytes("0x")
        );
        vmExt.zkUsePaymaster(vm.envAddress("PAYMASTER_ADDRESS"), paymaster_encoded_input);
        counter = new Counter();

        vm.stopBroadcast();
    }
}

You can now run the following command

source .env && forge script ./script/Counter.s.sol \
--rpc-url testnet --private-key $PRIVATE_KEY --zksync --broadcast

Using a Low-Level Call (in Case You Can’t Install the Cheatcode Library)

For your convenience, you can copy-paste the following script:

Here we use address(vm).call

// SPDX-License-Identifier: UNLICENSED
pragma solidity ^0.8.13;

import {Script, console} from "forge-std/Script.sol";
import {Counter} from "../src/Counter.sol";
import {TestExt} from "lib/forge-zksync-std/src/TestExt.sol";

contract CounterScript is Script, TestExt {
    Counter public counter;

    function setUp() public {}

    function run() public {
        vm.startBroadcast();

        // Encode paymaster input
        bytes memory paymaster_encoded_input = abi.encodeWithSelector(
            bytes4(keccak256("general(bytes)")),
            bytes("0x")
        );
        (bool success, ) = address(vm).call(
            abi.encodeWithSignature(
                "zkUsePaymaster(address,bytes)",
                vm.envAddress("PAYMASTER_ADDRESS"),
                paymaster_encoded_input
            )
        );
        require(success, "zkUsePaymaster() call failed");
        counter = new Counter();

        vm.stopBroadcast();
    }
}

You can now run the following command:

source .env && forge script ./script/Counter.s.sol \
--rpc-url testnet --private-key $PRIVATE_KEY --zksync --broadcast

Deployment Using Script With Paymaster and Verification

Same as Deployment Using Script With Paymaster but you append the --verify flag

This will only verify on Sophscan

source .env && forge script ./script/Counter.s.sol \
--rpc-url testnet --private-key $PRIVATE_KEY --zksync --broadcast --verify \
--verifier etherscan --verifier-url $SOPHSCAN_TESTNET_VERIFIER_URL

Contract Verification

If you want to verify an already deployed contract, you can do so on Sophscan (an Etherscan-like explorer) and/or on Sophon’s Explorer. On Sophscan

source .env && forge verify-contract COUNTER_CONTRACT_ADDRESS \
./src/Counter.sol:Counter:Counter --watch --rpc-url testnet --zksync \
--verifier zksync --verifier-url $SOPHSCAN_TESTNET_VERIFIER_URL

On Sophon’s Explorer

forge verify-contract COUNTER_CONTRACT_ADDRESS ./src/Counter.sol:Counter \
--watch --verifier zksync --verifier-url $SOPHON_VERIFIER_URL --zksync

Using Libraries

If your contract relies on external libraries, you need to build it with the linked libraries during deployment. For example:

If you deploy a library via the EVM Equivalence Module, you can’t link it to a zkEVM contract. We advise to keep your libraries inline, in possible. Check how to compile non-inlinable libraries here.

forge build --zksync --libraries ./contracts/util/SignatureChecker.sol:SignatureChecker:0xb0A2cf27Bf984bd0c56dCFb37C9DA0F2c5028844

This ensures the library is properly linked during the build and deploy process, enabling verification to succeed.

Contracts With Constructor Params

If your contract receives constructor params, you can use the --constructor-args flag: Modify your Counter contract to receive a constructor param:

// SPDX-License-Identifier: UNLICENSED
pragma solidity ^0.8.13;

contract Counter {
    uint256 public number;

    constructor(uint256 _number) {
        number = _number;
    }

    function setNumber(uint256 newNumber) public {
        number = newNumber;
    }

    function increment() public {
        number++;
    }
}

You can now run:

forge create ./src/CounterWithConstructorParams.sol:Counter \
--rpc-url testnet --private-key $PRIVATE_KEY --zksync \
--constructor-args "$(cast abi-encode "constructor(uint256)" "123")"

To verify or use the paymaster, you can use the flags --verify and/or ----zk-paymaster-address as explained above.

Check if a contract is whitelisted by the paymaster

Before making calls to a newly deployed contract using a paymaster, it’s important to verify that the contract has been added to the paymaster’s whitelist. Our automated contract whitelisting service typically takes 2-3 seconds to whitelist new contracts under normal network conditions. While optional, checking the whitelist status before proceeding makes deployment scripts more robust by ensuring contracts are ready to interact with the paymaster. The code below provides a reference implementation for checking the whitelist status:

// SPDX-License-Identifier: UNLICENSED
pragma solidity ^0.8.13;

import {Script, console} from "forge-std/Script.sol";
import {Counter} from "../src/Counter.sol";
import {TestExt} from "lib/forge-zksync-std/src/TestExt.sol";

interface IRestrictionContract {
    function contractWhitelist(address) external view returns (bool);
}

contract CounterScript is Script, TestExt {
    Counter public counter;

    function setUp() public {}

    function run() public {
        vm.startBroadcast();

        address restrictionContractAddress = vm.envAddress("RESTRICTION_CONTRACT");
        address paymasterAddress = vm.envAddress("PAYMASTER_ADDRESS");
        uint256 waitTime = 5_000; // wait time in milliseconds
        uint256 maxAttempts = 5;
        bool isWhitelisted = false;
        uint256 attempts = 0;

        if (restrictionContractAddress != address(0)) {
            IRestrictionContract restrictionContract = IRestrictionContract(restrictionContractAddress);
            while (!isWhitelisted && attempts < maxAttempts) {
                try restrictionContract.contractWhitelist(address(this)) returns (bool whitelisted) {
                    isWhitelisted = whitelisted;
                    if (isWhitelisted) {
                        console.log("Contract is whitelisted on restriction contract!");
                        break;
                    } else {
                        attempts++;
                        if (attempts < maxAttempts) {
                            console.log("Contract not yet whitelisted. Waiting before retrying...");
                            vm.sleep(waitTime);
                        } else {
                            console.log("Contract still not whitelisted after max attempts. Proceeding anyway.");
                        }
                    }
                } catch {
                    console.log("Error checking whitelist status. Retrying...");
                    attempts++;
                    if (attempts < maxAttempts) {
                        vm.sleep(waitTime);
                    }
                }
            }
        }

        // Encode paymaster input
        bytes memory paymaster_encoded_input = abi.encodeWithSelector(
            bytes4(keccak256("general(bytes)")),
            bytes("0x")
        );
        (bool success, ) = address(vm).call(
            abi.encodeWithSignature(
                "zkUsePaymaster(address,bytes)",
                paymasterAddress,
                paymaster_encoded_input
            )
        );
        require(success, "zkUsePaymaster() call failed");

        counter = new Counter();

        vm.stopBroadcast();
    }
}

Legacy Chain Development

Setup

EVM Compatibility

Deploy & Interact

Contracts

Tokens

Partners

Foundry

Installing Foundry

Create a New Project

Set Configs

Counter Contract Deployment

Basic Deployment

Deployment and Verification

Deployment Using Paymaster

Deployment With Paymaster and Verification (All-in-One)

Deploy Contracts Using Foundry Scripts

Deployment Using Script

Deployment Using Script and Verification

Deployment Using Script With Paymaster

Using a Foundry Cheatcode

Using a Low-Level Call (in Case You Can’t Install the Cheatcode Library)

Deployment Using Script With Paymaster and Verification

Contract Verification

Using Libraries

Contracts With Constructor Params

Check if a contract is whitelisted by the paymaster

​Installing Foundry

​Create a New Project

​Set Configs

​Counter Contract Deployment

​Basic Deployment

​Deployment and Verification

​Deployment Using Paymaster

​Deployment With Paymaster and Verification (All-in-One)

​Deploy Contracts Using Foundry Scripts

​Deployment Using Script

​Deployment Using Script and Verification

​Deployment Using Script With Paymaster

​Using a Foundry Cheatcode

​Using a Low-Level Call (in Case You Can’t Install the Cheatcode Library)

​Deployment Using Script With Paymaster and Verification

​Contract Verification

​Using Libraries

​Contracts With Constructor Params

​Check if a contract is whitelisted by the paymaster

Installing Foundry

Create a New Project

Set Configs

Counter Contract Deployment

Basic Deployment

Deployment and Verification

Deployment Using Paymaster

Deployment With Paymaster and Verification (All-in-One)

Deploy Contracts Using Foundry Scripts

Deployment Using Script

Deployment Using Script and Verification

Deployment Using Script With Paymaster

Using a Foundry Cheatcode

Using a Low-Level Call (in Case You Can’t Install the Cheatcode Library)

Deployment Using Script With Paymaster and Verification

Contract Verification

Using Libraries

Contracts With Constructor Params

Check if a contract is whitelisted by the paymaster