Wallet
The Wallet module provides functionalities for integrating, creating, and managing wallets within the ZKsync ecosystem.
approveERC20
Bridging ERC20 tokens from Ethereum requires approving the tokens to the ZKsync Ethereum smart contract.
Inputs
Parameter | Type | Description |
---|---|---|
token | Address | The Ethereum address of the token. |
amount | BigNumberish | The amount of the token to be approved. |
overrides? | ethers.Overrides? | Transaction's overrides which may be used to pass L1 gasLimit , gasPrice , value , etc. |
async approveERC20(
token: Address,
amount: BigNumberish,
overrides?: ethers.Overrides & { bridgeAddress?: Address }
): Promise<ethers.TransactionResponse>
Example
import { Wallet, Provider, utils } from "zksync-ethers";
import { ethers } from "ethers";
const PRIVATE_KEY = "<WALLET_PRIVATE_KEY>";
const provider = Provider.getDefaultProvider(types.Network.Sepolia);
const ethProvider = ethers.getDefaultProvider("sepolia");
const wallet = new Wallet(PRIVATE_KEY, provider, ethProvider);
const tokenL1 = "0x56E69Fa1BB0d1402c89E3A4E3417882DeA6B14Be";
const txHandle = await wallet.approveERC20(tokenL1, "10000000");
await txHandle.wait();
claimFailedDeposit
The claimFailedDeposit
method withdraws funds from the initiated deposit, which failed when finalizing on L2.
If the deposit L2 transaction has failed, it sends an L1 transaction calling claimFailedDeposit
method of the L1 bridge, which results in returning L1 tokens back to the depositor, otherwise throws the error.
Inputs
Parameter | Type | Description |
---|---|---|
depositHash | bytes32 | The L2 transaction hash of the failed deposit. |
async claimFailedDeposit(depositHash: BytesLike): Promise<ethers.ContractTransaction>
Example
import { Wallet, Provider, utils } from "zksync-ethers";
import { ethers } from "ethers";
const PRIVATE_KEY = "<WALLET_PRIVATE_KEY>";
const provider = Provider.getDefaultProvider(types.Network.Sepolia);
const ethProvider = ethers.getDefaultProvider("sepolia");
const wallet = new Wallet(PRIVATE_KEY, provider, ethProvider);
const FAILED_DEPOSIT_HASH = "<FAILED_DEPOSIT_TX_HASH>";
const claimFailedDepositHandle = await wallet.claimFailedDeposit(FAILED_DEPOSIT_HASH);
connect
To interact with the ZKsync network, the Wallet
object should be connected to a Provider
by either passing it to the constructor or with the connect
method.
Inputs
Parameter | Type | Description |
---|---|---|
provider | Provider | A ZKsync node provider. |
Wallet.connect(provider:Provider): Wallet
Example
import { Wallet, Provider, types } from "zksync-ethers";
const PRIVATE_KEY = "<WALLET_PRIVATE_KEY>";
const unconnectedWallet = new Wallet(PRIVATE_KEY);
const provider = Provider.getDefaultProvider(types.Network.Sepolia);
const wallet = unconnectedWallet.connect(provider);
It is possible to chain connect
and connectToL1
methods:
const wallet = unconnectedWallet.connect(zkSyncProvider).connectToL1(ethProvider);
connectToL1
To perform L1 operations, the Wallet
object needs to be connected to an ethers.Provider
object.
Inputs
Parameter | Type | Description |
---|---|---|
provider | ethers.providers.Provider | An Ethereum node provider. |
Wallet.connectToL1(provider: ethers.Provider): Wallet
Example
import { Wallet } from "zksync-ethers";
import { ethers } from "ethers";
const PRIVATE_KEY = "<WALLET_PRIVATE_KEY>";
const unconnectedWallet = new Wallet(PRIVATE_KEY);
const ethProvider = ethers.getDefaultProvider("sepolia");
const wallet = unconnectedWallet.connectToL1(ethProvider);
It is possible to chain connect
and connectToL1
methods:
const wallet = unconnectedWallet.connect(zkSyncProvider).connectToL1(ethProvider);
constructor
The constructor initializes a wallet instance using a private key, and optionally connects it to L1 and L2 providers.
Inputs
Parameter | Type | Description |
---|---|---|
privateKey | BytesLike or ethers.utils.SigningKey | The private key of the Ethereum account. |
providerL2? | Provider | A ZKsync node provider. Needed for interaction with ZKsync. |
providerL1? | ethers.providers.Provider | An Ethereum node provider. Needed for interaction with L1. |
constructor (privateKey: ethers.utils.BytesLike | ethers.utils.SigningKey,
providerL2?: Provider,
providerL1?: ethers.providers.Provider)
Example
import { Wallet, Provider, utils } from "zksync-ethers";
import { ethers } from "ethers";
const PRIVATE_KEY = "<WALLET_PRIVATE_KEY>";
const provider = Provider.getDefaultProvider(types.Network.Sepolia);
const ethProvider = ethers.getDefaultProvider("sepolia");
const wallet = new Wallet(PRIVATE_KEY, provider, ethProvider);
deposit
Transfers the specified token from the associated account on the L1 network to the target account on the L2 network.
The token can be either ETH or any ERC20 token. For ERC20 tokens, enough approved tokens must be associated with the
specified L1 bridge (default one or the one defined in transaction.bridgeAddress
).
In this case, depending on is the chain ETH-based or not transaction.approveERC20
or transaction.approveBaseERC20
can be enabled to perform token approval.
If there are already enough approved tokens for the L1 bridge, token approval will be skipped.
To check the amount of approved tokens for a specific bridge, use
the allowanceL1
method.
Inputs
Parameter | Type | Description |
---|---|---|
transaction.token | Address | The address of the token to deposit. ETH by default. |
transaction.amount | BigNumberish | The amount of the token to deposit. |
transaction.to? | Address | The address that will receive the deposited tokens on L2. |
transaction.operatorTip? | BigNumberish | (currently is not used) If the ETH value passed with the transaction is not explicitly stated in the overrides, this field will be equal to the tip the operator will receive on top of the base cost of the transaction. |
transaction.bridgeAddress? | Address | The address of the bridge contract to be used. Defaults to the default ZKsync bridge (either L1EthBridge or L1Erc20Bridge ). |
transaction.approveERC20? | boolean | Whether or not should the token approval be performed under the hood. Set this flag to true if you bridge an ERC20 token and didn't call the approveERC20 function beforehand. |
transaction.approveBaseERC20? | boolean | Whether or not should the base token approval be performed under the hood. Set this flag to true if you bridge a base token and didn't call the approveERC20 function beforehand. |
transaction.l2GasLimit? | BigNumberish | Maximum amount of L2 gas that transaction can consume during execution on L2. |
transaction.gasPerPubdataByte? | BigNumberish | Whether or not should the token approval be performed under the hood. Set this flag to true if you bridge an ERC20 token and didn't call the approveERC20 function beforehand. |
transaction.refundRecipient? | Address | The address on L2 that will receive the refund for the transaction. If the transaction fails, it will also be the address to receive l2Value. |
transaction.overrides? | ethers.PayableOverrides | Transaction's overrides which may be used to pass L1 gasLimit , gasPrice , value , etc. |
transaction.approveOverrides? | ethers.Overrides | Transaction's overrides which may be used to pass L1 gasLimit , gasPrice , value , etc. |
transaction.approveBaseOverrides? | ethers.Overrides | Transaction's overrides which may be used to pass L1 gasLimit , gasPrice , value , etc. |
transaction.customBridgeData? | BytesLike | Additional data that can be sent to a bridge. |
async deposit(transaction: {
token: Address;
amount: BigNumberish;
to?: Address;
operatorTip?: BigNumberish;
bridgeAddress?: Address;
approveERC20?: boolean;
approveBaseERC20?: boolean;
l2GasLimit?: BigNumberish;
gasPerPubdataByte?: BigNumberish;
refundRecipient?: Address;
overrides?: ethers.PayableOverrides;
approveOverrides?: ethers.Overrides;
approveBaseOverrides?: ethers.Overrides;
customBridgeData?: BytesLike;
}): Promise<PriorityOpResponse>
Example
Deposit ETH on ETH-based chain.
import { Wallet, Provider, types, utils } from "zksync-ethers";
import { ethers } from "ethers";
const PRIVATE_KEY = "<WALLET_PRIVATE_KEY>";
const provider = Provider.getDefaultProvider(types.Network.Sepolia);
const ethProvider = ethers.getDefaultProvider("sepolia");
const wallet = new Wallet(PRIVATE_KEY, provider, ethProvider);
const depositTx = await wallet.deposit({
token: utils.ETH_ADDRESS,
amount: 10_000_000,
});
// Note that we wait not only for the L1 transaction to complete but also for it to be
// processed by ZKsync. If we want to wait only for the transaction to be processed on L1,
// we can use `await depositTx.waitL1Commit()`
await depositTx.wait();
Deposit token on ETH-based chain.
import { Wallet, Provider, types, utils } from "zksync-ethers";
import { ethers } from "ethers";
const PRIVATE_KEY = "<WALLET_PRIVATE_KEY>";
const provider = Provider.getDefaultProvider(types.Network.Sepolia);
const ethProvider = ethers.getDefaultProvider("sepolia");
const wallet = new Wallet(PRIVATE_KEY, provider, ethProvider);
const tokenL1 = "0x56E69Fa1BB0d1402c89E3A4E3417882DeA6B14Be";
const depositTx = await wallet.deposit({
token: tokenL1,
amount: 10_000_000,
approveERC20: true,
});
// Note that we wait not only for the L1 transaction to complete but also for it to be
// processed by ZKsync. If we want to wait only for the transaction to be processed on L1,
// we can use `await depositTx.waitL1Commit()`
await depositTx.wait();
Deposit ETH on non-ETH-based chain.
import { Wallet, Provider, types, utils } from "zksync-ethers";
import { ethers } from "ethers";
const PRIVATE_KEY = "<WALLET_PRIVATE_KEY>";
const provider = Provider.getDefaultProvider(types.Network.Sepolia);
const ethProvider = ethers.getDefaultProvider("sepolia");
const wallet = new Wallet(PRIVATE_KEY, provider, ethProvider);
const depositTx = await wallet.deposit({
token: utils.ETH_ADDRESS,
amount: 10_000_000,
approveBaseERC20: true,
});
// Note that we wait not only for the L1 transaction to complete but also for it to be
// processed by ZKsync. If we want to wait only for the transaction to be processed on L1,
// we can use `await depositTx.waitL1Commit()`
await depositTx.wait();
Deposit base token on non-ETH-based chain.
import { Wallet, Provider, types, utils } from "zksync-ethers";
import { ethers } from "ethers";
const PRIVATE_KEY = "<WALLET_PRIVATE_KEY>";
const provider = Provider.getDefaultProvider(types.Network.Sepolia);
const ethProvider = ethers.getDefaultProvider("sepolia");
const wallet = new Wallet(PRIVATE_KEY, provider, ethProvider);
const depositTx = await wallet.deposit({
token: await wallet.getBaseToken(),
amount: 10_000_000,
approveERC20: true, // or approveBaseERC20: true
});
// Note that we wait not only for the L1 transaction to complete but also for it to be
// processed by ZKsync. If we want to wait only for the transaction to be processed on L1,
// we can use `await depositTx.waitL1Commit()`
await depositTx.wait();
Deposit non-base token on non-ETH-based chain.
import { Wallet, Provider, types, utils } from "zksync-ethers";
import { ethers } from "ethers";
const PRIVATE_KEY = "<WALLET_PRIVATE_KEY>";
const provider = Provider.getDefaultProvider(types.Network.Sepolia);
const ethProvider = ethers.getDefaultProvider("sepolia");
const wallet = new Wallet(PRIVATE_KEY, provider, ethProvider);
const tokenL1 = "0x56E69Fa1BB0d1402c89E3A4E3417882DeA6B14Be";
const depositTx = await wallet.deposit({
token: tokenL1,
amount: 10_000_000,
approveERC20: true,
approveBaseERC20: true,
});
// Note that we wait not only for the L1 transaction to complete but also for it to be
// processed by ZKsync. If we want to wait only for the transaction to be processed on L1,
// we can use `await depositTx.waitL1Commit()`
await depositTx.wait();
estimateGasDeposit
Estimates the amount of gas required for a deposit transaction on L1 network. Gas of approving ERC20 token is not included in estimation.
Inputs
Parameter | Type | Description |
---|---|---|
transaction.token | Address | The address of the token to deposit. ETH by default. |
transaction.amount | BigNumberish | The amount of the token to deposit. |
transaction.to? | Address | The address that will receive the deposited tokens on L2. |
transaction.operatorTip? | BigNumberish | (currently is not used) If the ETH value passed with the transaction is not explicitly stated in the overrides, this field will be equal to the tip the operator will receive on top of the base cost of the transaction. |
transaction.bridgeAddress? | Address | The address of the bridge contract to be used. Defaults to the default ZKsync bridge (either L1EthBridge or L1Erc20Bridge ). |
transaction.l2GasLimit? | BigNumberish | Maximum amount of L2 gas that transaction can consume during execution on L2. |
transaction.gasPerPubdataByte? | BigNumberish | Whether or not should the token approval be performed under the hood. Set this flag to true if you bridge an ERC20 token and didn't call the approveERC20 function beforehand. |
transaction.customBridgeData? | BytesLike | Additional data that can be sent to a bridge. |
transaction.refundRecipient? | Address | The address on L2 that will receive the refund for the transaction. If the transaction fails, it will also be the address to receive l2Value. |
transaction.overrides? | ethers.PayableOverrides | Transaction's overrides which may be used to pass L1 gasLimit , gasPrice , value , etc. |
async estimateGasDeposit(transaction:
token: Address;
amount: BigNumberish;
to?: Address;
operatorTip?: BigNumberish;
bridgeAddress?: Address;
customBridgeData?: BytesLike;
l2GasLimit?: BigNumberish;
gasPerPubdataByte?: BigNumberish;
refundRecipient?: Address;
overrides?: ethers.PayableOverrides;
}): Promise<BigNumber>
Example
import { Wallet, Provider, utils } from "zksync-ethers";
import { ethers } from "ethers";
const PRIVATE_KEY = "<WALLET_PRIVATE_KEY>";
const provider = Provider.getDefaultProvider(types.Network.Sepolia);
const ethProvider = ethers.getDefaultProvider("sepolia");
const wallet = new Wallet(PRIVATE_KEY, provider, ethProvider);
const tokenL1 = "0x5C221E77624690fff6dd741493D735a17716c26B";
const gas = await wallet.estimateGasDeposit({
token: tokenL1,
amount: "10000000",
});
console.log(`Gas: ${gas}`);
estimateGasRequestExecute
Estimates the amount of gas required for a request execute transaction.
Inputs
Name | Type | Description |
---|---|---|
transaction.contractAddress | Address | The L2 contract to be called. |
transaction.calldata | BytesLike | The input of the L2 transaction. |
transaction.l2GasLimit? | BigNumberish | Maximum amount of L2 gas that transaction can consume during execution on L2. |
transaction.mintValue? | BigNumberish | The amount of base token that needs to be minted on non-ETH-based L2.. |
transaction.l2Value? | BigNumberish | msg.value of L2 transaction. |
transaction.factoryDeps? | ethers.BytesLike[] | An array of L2 bytecodes that will be marked as known on L2. |
transaction.operatorTip? | BigNumberish | (currently is not used) If the ETH value passed with the transaction is not explicitly stated in the overrides, this field will be equal to the tip the operator will receive on top of the base cost of the transaction. |
transaction.gasPerPubdataByte? | BigNumberish | The L2 gas price for each published L1 calldata byte. |
transaction.refundRecipient? | Address | The address on L2 that will receive the refund for the transaction. If the transaction fails, it will also be the address to receive l2Value . |
transaction.overrides? | ethers.PayableOverrides | Transaction's overrides which may be used to pass L1 gasLimit , gasPrice , value , etc. |
async estimateGasRequestExecute(transaction: {
contractAddress: Address;
calldata: BytesLike;
l2GasLimit?: BigNumberish;
mintValue?: BigNumberish;
l2Value?: BigNumberish;
factoryDeps?: BytesLike[];
operatorTip?: BigNumberish;
gasPerPubdataByte?: BigNumberish;
refundRecipient?: Address;
overrides?: ethers.PayableOverrides;
}): Promise<BigNumber>
Example
import { Wallet, Provider, utils } from "zksync-ethers";
import { ethers } from "ethers";
const PRIVATE_KEY = "<WALLET_PRIVATE_KEY>";
const CONTRACT_ADDRESS = "<CONTRACT_ADDRESS>";
const provider = Provider.getDefaultProvider(types.Network.Sepolia);
const ethProvider = ethers.getDefaultProvider("sepolia");
const wallet = new Wallet(PRIVATE_KEY, provider, ethProvider);
const gasPrice = await wallet.providerL1.getGasPrice();
// The calldata can be encoded the same way as for Ethereum.
// Here is an example of how to get the calldata from an ABI:
const abi = [
{
inputs: [],
name: "increment",
outputs: [],
stateMutability: "nonpayable",
type: "function",
},
];
const contractInterface = new ethers.utils.Interface(abi);
const calldata = contractInterface.encodeFunctionData("increment", []);
const l2GasLimit = BigNumber.from(1000);
const txCostPrice = await wallet.getBaseCost({
gasPrice,
calldataLength: ethers.utils.arrayify(calldata).length,
l2GasLimit,
});
console.log(`Executing the transaction will cost ${ethers.utils.formatEther(txCostPrice)} ETH`);
const executeTx = await wallet.getRequestExecuteTx({
contractAddress: CONTRACT_ADDRESS,
calldata,
l2Value: 1,
l2GasLimit,
overrides: {
gasPrice,
value: txCostPrice,
},
});
ethWallet
You can get an ethers.Wallet
object with the same private key with ethWallet()
method.
ethWallet(): ethers.Wallet
Example
import { Wallet, Provider, utils } from "zksync-ethers";
import { ethers } from "ethers";
const PRIVATE_KEY = "<WALLET_PRIVATE_KEY>";
const provider = Provider.getDefaultProvider(types.Network.Sepolia);
const ethProvider = ethers.getDefaultProvider("sepolia");
const wallet = new Wallet(PRIVATE_KEY, provider, ethProvider);
const ethWallet = wallet.ethWallet();
finalizeWithdrawal
Proves the inclusion of the L2 -> L1 withdrawal message.
Inputs
Name | Type | Description |
---|---|---|
withdrawalHash | BytesLike | Hash of the L2 transaction where the withdrawal was initiated. |
index? | number | In case there were multiple withdrawals in one transaction, you may pass an index of the withdrawal you want to finalize. Defaults to 0. |
async finalizeWithdrawal(withdrawalHash: BytesLike, index: number = 0): Promise<ethers.ContractTransactionResponse>
Example
import { Wallet, Provider, utils } from "zksync-ethers";
import { ethers } from "ethers";
const PRIVATE_KEY = "<WALLET_PRIVATE_KEY>";
const provider = Provider.getDefaultProvider(types.Network.Sepolia);
const ethProvider = ethers.getDefaultProvider("sepolia");
const wallet = new Wallet(PRIVATE_KEY, provider, ethProvider);
const WITHDRAWAL_HASH = "<WITHDRAWAL_TX_HASH>";
const finalizeWithdrawHandle = await wallet.finalizeWithdrawal(WITHDRAWAL_HASH);
finalizeWithdrawalParams
Returns the parameters required for finalizing a withdrawal from the withdrawal transaction's log on the L1 network.
Inputs
Name | Type | Description |
---|---|---|
withdrawalHash | BytesLike | Hash of the L2 transaction where the withdrawal was initiated. |
index? | number | In case there were multiple withdrawals in one transaction, you may pass an index of the withdrawal you want to finalize. Defaults to 0. |
async finalizeWithdrawalParams(withdrawalHash: BytesLike, index: number = 0): Promise<FinalizeWithdrawalParams>
Example
import { Wallet, Provider, utils } from "zksync-ethers";
import { ethers } from "ethers";
const PRIVATE_KEY = "<WALLET_PRIVATE_KEY>";
const provider = Provider.getDefaultProvider(types.Network.Sepolia);
const ethProvider = ethers.getDefaultProvider("sepolia");
const wallet = new Wallet(PRIVATE_KEY, provider, ethProvider);
const WITHDRAWAL_HASH = "<WITHDRAWAL_TX_HASH>";
const params = await wallet.finalizeWithdrawalParams(WITHDRAWAL_HASH);
fromEncryptedJson
Creates a Wallet
from encrypted json
file using provided password
.
Inputs
Parameter | Type | Description |
---|---|---|
json | string | Encrypted json file. |
password | string or ethers.Bytes | Password for encrypted json file. |
callback? | ProgressCallback | If callback is provided, it is called periodically during decryption so that any UI can be updated. |
static async fromEncryptedJsonSync(json: string, password?: string | ethers.Bytes)
Example
import { Wallet, Provider, utils } from "zksync-ethers";
import * as fs from "fs";
const wallet = await Wallet.fromEncryptedJson(fs.readFileSync("wallet.json", "utf8"), "password");
fromEncryptedJsonSync
Creates a Wallet
from encrypted json
file using provided password
.
Inputs
Parameter | Type | Description |
---|---|---|
json | string | Encrypted json file. |
password | string or ethers.Bytes | Password for encrypted json file. |
static fromEncryptedJsonSync(json: string, password?: string | ethers.Bytes)
Example
import { Wallet } from "zksync-ethers";
import * as fs from "fs";
const wallet = Wallet.fromEncryptedJsonSync(fs.readFileSync("tests/files/wallet.json", "utf8"), "password");
fromMnemonic
Creates a Wallet
with the provider
as L1 provider and a private key that is built from the mnemonic
passphrase.
Inputs
Parameter | Type | Description |
---|---|---|
mnemonic | string | The mnemonic of the private key. |
path? | string | If path is not specified, the Ethereum default path is used. |
wordlist? | ethers.Worldlist | If wordlist is not specified, the English Wordlist is used. |
static fromMnemonic(mnemonic: string, path?: string, wordlist?: ethers.Wordlist)
Example
import { Wallet } from "zksync-ethers";
const MNEMONIC = "stuff slice staff easily soup parent arm payment cotton hammer scatter struggle";
const wallet = Wallet.fromMnemonic(MNEMONIC);
getAddress
Returns the wallet address.
async getAddress(): Promise<Address>;
Example
import { Wallet, Provider, utils } from "zksync-ethers";
import { ethers } from "ethers";
const PRIVATE_KEY = "<WALLET_PRIVATE_KEY>";
const provider = Provider.getDefaultProvider(types.Network.Sepolia);
const ethProvider = ethers.getDefaultProvider("sepolia");
const wallet = new Wallet(PRIVATE_KEY, provider, ethProvider);
console.log(`Address: ${await wallet.getAddress()}`);
getAllBalances
Returns all balances for confirmed tokens given by an account address.
async getAllBalances(): Promise<BalancesMap>
Example
import { Wallet, Provider, utils } from "zksync-ethers";
import { ethers } from "ethers";
const PRIVATE_KEY = "<WALLET_PRIVATE_KEY>";
const provider = Provider.getDefaultProvider(types.Network.Sepolia);
const ethProvider = ethers.getDefaultProvider("sepolia");
const wallet = new Wallet(PRIVATE_KEY, provider, ethProvider);
const allBalances = await wallet.getAllBalances();
getAllowanceL1
Returns the amount of approved tokens for a specific L1 bridge.
Inputs
Parameter | Type | Description |
---|---|---|
token | Address | The Ethereum address of the token. |
bridgeAddress? | Address | The address of the bridge contract to be used. Defaults to the default ZKsync bridge, either L1EthBridge or L1Erc20Bridge . |
blockTag? | BlockTag | In which block an allowance should be checked on. committed , i.e. the latest processed one is the default option. |
async getAllowanceL1(
token: Address,
bridgeAddress?: Address,
blockTag?: ethers.BlockTag
): Promise<BigNumber>
Example
import { Wallet, Provider, utils } from "zksync-ethers";
import { ethers } from "ethers";
const PRIVATE_KEY = "<WALLET_PRIVATE_KEY>";
const provider = Provider.getDefaultProvider(types.Network.Sepolia);
const ethProvider = ethers.getDefaultProvider("sepolia");
const wallet = new Wallet(PRIVATE_KEY, provider, ethProvider);
const tokenL1 = "0x5C221E77624690fff6dd741493D735a17716c26B";
console.log(`Token allowance: ${await wallet.getAllowanceL1(tokenL1)}`);
getBalance
Returns the amount of the token the Wallet
has.
Inputs
Parameter | Type | Description |
---|---|---|
token? | Address | The address of the token. ETH by default. |
blockTag | BlockTag | In which block a balance should be checked on. committed , i.e. the latest processed one is the default option. |
async getBalance(token?: Address, blockTag: BlockTag = 'committed'): Promise<BigNumber>
Example
import { Wallet, Provider, utils } from "zksync-ethers";
import { ethers } from "ethers";
const PRIVATE_KEY = "<WALLET_PRIVATE_KEY>";
const provider = Provider.getDefaultProvider(types.Network.Sepolia);
const ethProvider = ethers.getDefaultProvider("sepolia");
const wallet = new Wallet(PRIVATE_KEY, provider, ethProvider);
const tokenL2 = "0x6a4Fb925583F7D4dF82de62d98107468aE846FD1";
console.log(`Token balance: ${await wallet.getBalance(tokenL2)}`);
getBalanceL1
Returns the amount of the token the Wallet
has on Ethereum.
Inputs
Parameter | Type | Description |
---|---|---|
token? | Address | The address of the token. ETH by default. |
blockTag? | BlockTag | In which block a balance should be checked on. committed , i.e. the latest processed one is the default option. |
async getBalanceL1(token?: Address, blockTag?: BlockTag): Promise<BigNumber>
Example
import { Wallet, Provider, utils } from "zksync-ethers";
import { ethers } from "ethers";
const PRIVATE_KEY = "<WALLET_PRIVATE_KEY>";
const provider = Provider.getDefaultProvider(types.Network.Sepolia);
const ethProvider = ethers.getDefaultProvider("sepolia");
const wallet = new Wallet(PRIVATE_KEY, provider, ethProvider);
const tokenL1 = "0x56E69Fa1BB0d1402c89E3A4E3417882DeA6B14Be";
console.log(`Token balance: ${await wallet.getBalanceL1(tokenL1)}`);
getBaseCost
Returns base cost for L2 transaction.
Inputs
Name | Type | Description |
---|---|---|
params.gasLimit | BigNumberish | The gasLimit for the L2 contract call. |
params.gasPerPubdataByte? | BigNumberish | The L2 gas price for each published L1 calldata byte. |
params.gasPrice? | BigNumberish | The L1 gas price of the L1 transaction that will send the request for an execute call. |
async getBaseCost(params: {
gasLimit: BigNumberish;
gasPerPubdataByte?: BigNumberish;
gasPrice?: BigNumberish;
}): Promise<BigNumber>
Example
import { Wallet, Provider, utils } from "zksync-ethers";
import { ethers } from "ethers";
const PRIVATE_KEY = "<WALLET_PRIVATE_KEY>";
const provider = Provider.getDefaultProvider(types.Network.Sepolia);
const ethProvider = ethers.getDefaultProvider("sepolia");
const wallet = new Wallet(PRIVATE_KEY, provider, ethProvider);
console.log(`Base cost: ${await wallet.getBaseCost({ gasLimit: 100_000 })}`);
getBaseToken
Returns the address of the base token on L1.
async getBaseToken(): Promise<string>
Example
import { Wallet, Provider, types, utils } from "zksync-ethers";
import { ethers } from "ethers";
const PRIVATE_KEY = "<WALLET_PRIVATE_KEY>";
const provider = Provider.getDefaultProvider(types.Network.Sepolia);
const ethProvider = ethers.getDefaultProvider("sepolia");
const wallet = new Wallet(PRIVATE_KEY, provider, ethProvider);
console.log(`Base token: ${await wallet.getBaseToken()}`);
getBridgehubContract
Returns Contract
wrapper of the Bridgehub smart contract.
async getBridgehubContract(): Promise<IBridgehub>
Example
import { Wallet, Provider, types, utils } from "zksync-ethers";
import { ethers } from "ethers";
const PRIVATE_KEY = "<WALLET_PRIVATE_KEY>";
const provider = Provider.getDefaultProvider(types.Network.Sepolia);
const ethProvider = ethers.getDefaultProvider("sepolia");
const wallet = new Wallet(PRIVATE_KEY, provider, ethProvider);
const bridgehub = await wallet.getBridgehubContract();
getDeploymentNonce
Returns account's deployment nonce number.
async getDeploymentNonce(): Promise<BigNumber>
Example
import { Wallet, Provider, utils } from "zksync-ethers";
import { ethers } from "ethers";
const PRIVATE_KEY = "<WALLET_PRIVATE_KEY>";
const provider = Provider.getDefaultProvider(types.Network.Sepolia);
const ethProvider = ethers.getDefaultProvider("sepolia");
const wallet = new Wallet(PRIVATE_KEY, provider, ethProvider);
console.log(`Nonce: ${await wallet.getDeploymentNonce()}`);
getDepositAllowanceParams
Returns the parameters for the approval token transaction based on the deposit token and amount. Some deposit transactions require multiple approvals. Existing allowance for the bridge is not checked; allowance is calculated solely based on the specified amount.
Inputs
Parameter | Type | Description |
---|---|---|
token | Address | The address of the token to deposit. |
amount | BigNumberish | The amount of the token to deposit. |
async getDepositAllowanceParams(
token: Address,
amount: BigNumberish
): Promise<
{
token: Address;
allowance: BigNumberish;
}[]
>
Example
Get allowance parameters for depositing token on ETH-based chain.
import { Wallet, Provider, types, utils } from "zksync-ethers";
import { ethers } from "ethers";
const PRIVATE_KEY = "<WALLET_PRIVATE_KEY>";
const provider = Provider.getDefaultProvider(types.Network.Sepolia);
const ethProvider = ethers.getDefaultProvider("sepolia");
const wallet = new Wallet(PRIVATE_KEY, provider, ethProvider);
const token = "<L1_TOKEN>";
const amount = 5;
const approveParams = await wallet.getDepositAllowanceParams(token, amount);
await (
await wallet.approveERC20(
approveParams[0].token,
approveParams[0].allowance
)
).wait();
Get allowance parameters for depositing ETH on non-ETH-based chain.
import { Wallet, Provider, types, utils } from "zksync-ethers";
import { ethers } from "ethers";
const PRIVATE_KEY = "<WALLET_PRIVATE_KEY>";
const provider = Provider.getDefaultProvider(types.Network.Sepolia);
const ethProvider = ethers.getDefaultProvider("sepolia");
const wallet = new Wallet(PRIVATE_KEY, provider, ethProvider);
const token = utils.LEGACY_ETH_ADDRESS;
const amount = 5;
const approveParams = await wallet.getDepositAllowanceParams(token, amount);
await (
await wallet.approveERC20(
approveParams[0].token,
approveParams[0].allowance
)
).wait();
Get allowance parameters for depositing base token on non-ETH-based chain.
import { Wallet, Provider, types, utils } from "zksync-ethers";
import { ethers } from "ethers";
const PRIVATE_KEY = "<WALLET_PRIVATE_KEY>";
const provider = Provider.getDefaultProvider(types.Network.Sepolia);
const ethProvider = ethers.getDefaultProvider("sepolia");
const wallet = new Wallet(PRIVATE_KEY, provider, ethProvider);
const token = await wallet.getBaseToken();
const amount = 5;
const approveParams = await wallet.getDepositAllowanceParams(token, amount);
await (
await wallet.approveERC20(
approveParams[0].token,
approveParams[0].allowance
)
).wait();
Get allowance parameters for depositing non-base token on non-ETH-based chain.
import { Wallet, Provider, types, utils } from "zksync-ethers";
import { ethers } from "ethers";
const PRIVATE_KEY = "<WALLET_PRIVATE_KEY>";
const provider = Provider.getDefaultProvider(types.Network.Sepolia);
const ethProvider = ethers.getDefaultProvider("sepolia");
const wallet = new Wallet(PRIVATE_KEY, provider, ethProvider);
const token = "<L1_TOKEN>";
const amount = 5;
const approveParams = await wallet.getDepositAllowanceParams(token, amount);
await (
await wallet.approveERC20(
approveParams[0].token,
approveParams[0].allowance
)
).wait();
await (
await wallet.approveERC20(
approveParams[1].token,
approveParams[1].allowance
)
).wait();
getDepositTx
Returns populated deposit transaction.
Inputs
Parameter | Type | Description |
---|---|---|
transaction.token | Address | The address of the token to deposit. ETH by default. |
transaction.amount | BigNumberish | The amount of the token to deposit. |
transaction.to? | Address | The address that will receive the deposited tokens on L2. |
transaction.operatorTip? | BigNumberish | (currently is not used) If the ETH value passed with the transaction is not explicitly stated in the overrides, this field will be equal to the tip the operator will receive on top of the base cost of the transaction. |
transaction.bridgeAddress? | Address | The address of the bridge contract to be used. Defaults to the default ZKsync bridge (either L1EthBridge or L1Erc20Bridge ). |
transaction.l2GasLimit? | BigNumberish | Maximum amount of L2 gas that transaction can consume during execution on L2. |
transaction.gasPerPubdataByte? | BigNumberish | Whether or not should the token approval be performed under the hood. Set this flag to true if you bridge an ERC20 token and didn't call the approveERC20 function beforehand. |
transaction.customBridgeData? | BytesLike | Additional data that can be sent to a bridge. |
transaction.refundRecipient? | Address | The address on L2 that will receive the refund for the transaction. If the transaction fails, it will also be the address to receive l2Value. |
transaction.overrides? | ethers.PayableOverrides | Transaction's overrides which may be used to pass L1 gasLimit , gasPrice , value , etc. |
async getDepositTx(transaction: {
token: Address;
amount: BigNumberish;
to?: Address;
operatorTip?: BigNumberish;
bridgeAddress?: Address;
l2GasLimit?: BigNumberish;
gasPerPubdataByte?: BigNumberish;
customBridgeData?: BytesLike;
refundRecipient?: Address;
overrides?: ethers.PayableOverrides;
}): Promise<any>
Example
import { Wallet, Provider, utils } from "zksync-ethers";
import { ethers } from "ethers";
const PRIVATE_KEY = "<WALLET_PRIVATE_KEY>";
const provider = Provider.getDefaultProvider(types.Network.Sepolia);
const ethProvider = ethers.getDefaultProvider("sepolia");
const wallet = new Wallet(PRIVATE_KEY, provider, ethProvider);
const tokenL1 = "0x56E69Fa1BB0d1402c89E3A4E3417882DeA6B14Be";
const tx = await wallet.getDepositTx({
token: tokenL1,
amount: "10000000",
});
getFullRequiredDepositFee
Retrieves the full needed ETH fee for the deposit. Returns the L1 fee and the L2 fee FullDepositFee
.
Inputs
Parameter | Type | Description |
---|---|---|
transaction.token | Address | The address of the token to deposit. ETH by default. |
transaction.to? | Address | The address that will receive the deposited tokens on L2. |
transaction.bridgeAddress? | Address | The address of the bridge contract to be used. Defaults to the default ZKsync bridge (either L1EthBridge or L1Erc20Bridge ). |
transaction.customBridgeData? | BytesLike | Additional data that can be sent to a bridge. |
transaction.gasPerPubdataByte? | BigNumberish | Whether or not should the token approval be performed under the hood. Set this flag to true if you bridge an ERC20 token and didn't call the approveERC20 function beforehand. |
transaction.overrides? | ethers.PayableOverrides | Transaction's overrides which may be used to pass L1 gasLimit , gasPrice , value , etc. |
async getFullRequiredDepositFee(transaction: {
token: Address;
to?: Address;
bridgeAddress?: Address;
customBridgeData?: BytesLike;
gasPerPubdataByte?: BigNumberish;
overrides?: ethers.PayableOverrides;
}): Promise<FullDepositFee>
Example
import { Wallet, Provider, utils } from "zksync-ethers";
import { ethers } from "ethers";
const PRIVATE_KEY = "<WALLET_PRIVATE_KEY>";
const provider = Provider.getDefaultProvider(types.Network.Sepolia);
const ethProvider = ethers.getDefaultProvider("sepolia");
const wallet = new Wallet(PRIVATE_KEY, provider, ethProvider);
const tokenL1 = "0x56E69Fa1BB0d1402c89E3A4E3417882DeA6B14Be";
const fee = await wallet.getFullRequiredDepositFee({
token: tokenL1,
to: await wallet.getAddress(),
});
console.log(`Fee: ${fee}`);
getL1BridgeContracts
Returns L1 bridge contracts.
async getL1BridgeContracts(): Promise<{
erc20: IL1ERC20Bridge;
weth: IL1ERC20Bridge;
shared: IL1SharedBridge;
}>
Example
import { Wallet, Provider, utils } from "zksync-ethers";
import { ethers } from "ethers";
const PRIVATE_KEY = "<WALLET_PRIVATE_KEY>";
const provider = Provider.getDefaultProvider(types.Network.Sepolia);
const ethProvider = ethers.getDefaultProvider("sepolia");
const wallet = new Wallet(PRIVATE_KEY, provider, ethProvider);
const l1BridgeContracts = await wallet.getL1BridgeContracts();
getL2BridgeContracts
Returns L2 bridge contracts.
async getL2BridgeContracts(): Promise<{
erc20: IL2Bridge;
weth: IL2Bridge;
shared: IL2Bridge;
}>
Example
import { Wallet, Provider, utils } from "zksync-ethers";
import { ethers } from "ethers";
const PRIVATE_KEY = "<WALLET_PRIVATE_KEY>";
const provider = Provider.getDefaultProvider(types.Network.Sepolia);
const ethProvider = ethers.getDefaultProvider("sepolia");
const wallet = new Wallet(PRIVATE_KEY, provider, ethProvider);
const l2BridgeContracts = await wallet.getL2BridgeContracts();
getMainContract
Returns Contract
wrapper of the ZKsync smart contract.
async getMainContract(): Promise<IZkSyncStateTransition>
Example
import { Wallet, Provider, utils } from "zksync-ethers";
import { ethers } from "ethers";
const PRIVATE_KEY = "<WALLET_PRIVATE_KEY>";
const provider = Provider.getDefaultProvider(types.Network.Sepolia);
const ethProvider = ethers.getDefaultProvider("sepolia");
const wallet = new Wallet(PRIVATE_KEY, provider, ethProvider);
console.log(`Main contract: ${await wallet.getMainContract()}`);
getNonce
Returns whether the withdrawal transaction is finalized on the L1 network.
Inputs
Parameter | Type | Description |
---|---|---|
blockTag? | BlockTag | In which block a balance should be checked on. committed , i.e. the latest processed one is the default option. |
async getNonce(blockTag?: BlockTag): Promise<number>
Example
import { Wallet, Provider, utils } from "zksync-ethers";
import { ethers } from "ethers";
const PRIVATE_KEY = "<WALLET_PRIVATE_KEY>";
const provider = Provider.getDefaultProvider(types.Network.Sepolia);
const ethProvider = ethers.getDefaultProvider("sepolia");
const wallet = new Wallet(PRIVATE_KEY, provider, ethProvider);
console.log(`Nonce: ${await wallet.getNonce()}`);
getPriorityOpConfirmation
Returns the transaction confirmation data that is part of L2->L1
message.
Inputs
Name | Type | Description |
---|---|---|
txHash | BytesLike | Hash of the L2 transaction where the withdrawal was initiated. |
index? | number | In case there were multiple transactions in one message, you may pass an index of the transaction which confirmation data should be fetched. Defaults to 0. |
async getPriorityOpConfirmation(txHash: string, index: number = 0): Promise<{
l1BatchNumber: number;
l2MessageIndex: number;
l2TxNumberInBlock: number;
proof: string[]
}>
Example
import { Wallet, Provider, types, utils } from "zksync-ethers";
import { ethers } from "ethers";
const PRIVATE_KEY = "<WALLET_PRIVATE_KEY>";
const provider = Provider.getDefaultProvider(types.Network.Sepolia);
const wallet = new Wallet(PRIVATE_KEY, provider);
// Any L2 -> L1 transaction can be used.
// In this case, withdrawal transaction is used.
const tx = "0x2a1c6c74b184965c0cb015aae9ea134fd96215d2e4f4979cfec12563295f610e";
console.log(`Confirmation data: ${utils.toJSON(await wallet.getPriorityOpConfirmation(tx, 0))}`);
getRequestExecuteAllowanceParams
Returns the parameters for the approval token transaction based on the request execute transaction. Existing allowance for the bridge is not checked; allowance is calculated solely based on the specified transaction.
Inputs
Name | Type | Description |
---|---|---|
transaction.contractAddress | Address | The L2 contract to be called. |
transaction.calldata | BytesLike | The input of the L2 transaction. |
transaction.l2GasLimit? | BigNumberish | Maximum amount of L2 gas that transaction can consume during execution on L2. |
transaction.l2Value? | BigNumberish | msg.value of L2 transaction. |
transaction.factoryDeps? | ethers.BytesLike[] | An array of L2 bytecodes that will be marked as known on L2. |
transaction.operatorTip? | BigNumberish | (currently is not used) If the ETH value passed with the transaction is not explicitly stated in the overrides, this field will be equal to the tip the operator will receive on top of the base cost of the transaction. |
transaction.gasPerPubdataByte? | BigNumberish | The L2 gas price for each published L1 calldata byte. |
transaction.refundRecipient? | Address | The address on L2 that will receive the refund for the transaction. If the transaction fails, it will also be the address to receive l2Value . |
transaction.overrides? | ethers.PayableOverrides | Transaction's overrides which may be used to pass L2 gasLimit , gasPrice , value , etc. |
async getRequestExecuteAllowanceParams(transaction: {
contractAddress: Address;
calldata: BytesLike;
l2GasLimit?: BigNumberish;
l2Value?: BigNumberish;
factoryDeps?: BytesLike[];
operatorTip?: BigNumberish;
gasPerPubdataByte?: BigNumberish;
refundRecipient?: Address;
overrides?: ethers.PayableOverrides;
}): Promise<{token: Address; allowance: BigNumberish}>
Example
import { Wallet, Provider, types, utils } from "zksync-ethers";
import { ethers } from "ethers";
const PRIVATE_KEY = "<WALLET_PRIVATE_KEY>";
const provider = Provider.getDefaultProvider(types.Network.Sepolia);
const ethProvider = ethers.getDefaultProvider("sepolia");
const wallet = new Wallet(PRIVATE_KEY, provider, ethProvider);
const tx = {
contractAddress: await wallet.getAddress(),
calldata: '0x',
l2Value: 7_000_000_000,
};
const approveParams = await wallet.getRequestExecuteAllowanceParams(tx);
await (
await wallet.approveERC20(
approveParams.token,
approveParams.allowance
)
).wait();
getRequestExecuteTx
Returns populated request execute transaction.
Inputs
Name | Type | Description |
---|---|---|
transaction.contractAddress | Address | The L2 contract to be called. |
transaction.calldata | BytesLike | The input of the L2 transaction. |
transaction.l2GasLimit? | BigNumberish | Maximum amount of L2 gas that transaction can consume during execution on L2. |
transaction.mintValue? | BigNumberish | The amount of base token that needs to be minted on non-ETH-based L2.. |
transaction.l2Value? | BigNumberish | msg.value of L2 transaction. |
transaction.factoryDeps? | ethers.BytesLike[] | An array of L2 bytecodes that will be marked as known on L2. |
transaction.operatorTip? | BigNumberish | (currently is not used) If the ETH value passed with the transaction is not explicitly stated in the overrides, this field will be equal to the tip the operator will receive on top of the base cost of the transaction. |
transaction.gasPerPubdataByte? | BigNumberish | The L2 gas price for each published L1 calldata byte. |
transaction.refundRecipient? | Address | The address on L2 that will receive the refund for the transaction. If the transaction fails, it will also be the address to receive l2Value . |
transaction.overrides? | ethers.PayableOverrides | Transaction's overrides which may be used to pass L1 gasLimit , gasPrice , value , etc. |
async getRequestExecuteTx(transaction: {
contractAddress: Address;
calldata: BytesLike;
l2GasLimit?: BigNumberish;
mintValue?: BigNumberish;
l2Value?: BigNumberish;
factoryDeps?: BytesLike[];
operatorTip?: BigNumberish;
gasPerPubdataByte?: BigNumberish;
refundRecipient?: Address;
overrides?: ethers.PayableOverrides;
}): Promise<PopulatedTransaction>
Example
import { Wallet, Provider, utils } from "zksync-ethers";
import { ethers } from "ethers";
const PRIVATE_KEY = "<WALLET_PRIVATE_KEY>";
const CONTRACT_ADDRESS = "<CONTRACT_ADDRESS>";
const provider = Provider.getDefaultProvider(types.Network.Sepolia);
const ethProvider = ethers.getDefaultProvider("sepolia");
const wallet = new Wallet(PRIVATE_KEY, provider, ethProvider);
const gasPrice = await wallet.providerL1.getGasPrice();
// The calldata can be encoded the same way as for Ethereum.
// Here is an example of how to get the calldata from an ABI:
const abi = [
{
inputs: [],
name: "increment",
outputs: [],
stateMutability: "nonpayable",
type: "function",
},
];
const contractInterface = new ethers.utils.Interface(abi);
const calldata = contractInterface.encodeFunctionData("increment", []);
const l2GasLimit = BigNumber.from(1000);
const txCostPrice = await wallet.getBaseCost({
gasPrice,
calldataLength: ethers.utils.arrayify(calldata).length,
l2GasLimit,
});
console.log(`Executing the transaction will cost ${ethers.utils.formatEther(txCostPrice)} ETH`);
const executeTx = await wallet.getRequestExecuteTx({
contractAddress: CONTRACT_ADDRESS,
calldata,
l2Value: 1,
l2GasLimit,
overrides: {
gasPrice,
value: txCostPrice,
},
});
isETHBasedChain
Returns whether the chain is ETH-based.
async isETHBasedChain(): Promise<boolean>
Example
import { Wallet, Provider, types, utils } from "zksync-ethers";
import { ethers } from "ethers";
const PRIVATE_KEY = "<WALLET_PRIVATE_KEY>";
const provider = Provider.getDefaultProvider(types.Network.Sepolia);
const ethProvider = ethers.getDefaultProvider("sepolia");
const wallet = new Wallet(PRIVATE_KEY, provider, ethProvider);
console.log(`Is ETH-based chain: ${await wallet.isETHBasedChain()}`);
isWithdrawalFinalized
Returns whether the withdrawal transaction is finalized on the L1 network.
Inputs
Name | Type | Description |
---|---|---|
withdrawalHash | BytesLike | Hash of the L2 transaction where the withdrawal was initiated. |
index? | number | In case there were multiple withdrawals in one transaction, you may pass an index of the withdrawal you want to finalize. Defaults to 0. |
async isWithdrawalFinalized(withdrawalHash: BytesLike, index: number = 0): Promise<boolean>
Example
import { Wallet, Provider, utils } from "zksync-ethers";
import { ethers } from "ethers";
const PRIVATE_KEY = "<WALLET_PRIVATE_KEY>";
const provider = Provider.getDefaultProvider(types.Network.Sepolia);
const ethProvider = ethers.getDefaultProvider("sepolia");
const wallet = new Wallet(PRIVATE_KEY, provider, ethProvider);
const WITHDRAWAL_HASH = "<WITHDRAWAL_TX_HASH>";
const isFinalized = await wallet.isWithdrawalFinalized(WITHDRAWAL_HASH);
l2TokenAddress
Returns the L2 token address equivalent for a L1 token address as they are not equal. ETH's address is set to zero address.
Inputs
Parameter | Type | Description |
---|---|---|
token | Address | The address of the token on L1. |
async l2TokenAddress(token: Address): Promise<string>
Example
import { Wallet, Provider, utils } from "zksync-ethers";
import { ethers } from "ethers";
const PRIVATE_KEY = "<WALLET_PRIVATE_KEY>";
const provider = Provider.getDefaultProvider(types.Network.Sepolia);
const ethProvider = ethers.getDefaultProvider("sepolia");
const wallet = new Wallet(PRIVATE_KEY, provider, ethProvider);
const tokenL1 = "0x5C221E77624690fff6dd741493D735a17716c26B";
console.log(`Token L2 address: ${await wallet.l2TokenAddress(tokenL1)}`);
populateTransaction
Designed for users who prefer a simplified approach by providing only the necessary
data to create a valid transaction. The only required fields are transaction.to
and either transaction.data
or transaction.value
(or both, if the method is payable).
Any other fields that are not set will be prepared by this method.
Parameter | Type | Description |
---|---|---|
transaction | TransactionRequest | Transaction request. |
async populateTransaction(transaction: TransactionRequest): Promise<TransactionLike>
Example
import { Wallet, Provider, utils } from "zksync-ethers";
import { ethers } from "ethers";
const PRIVATE_KEY = "<WALLET_PRIVATE_KEY>";
const provider = Provider.getDefaultProvider(types.Network.Sepolia);
const ethProvider = ethers.getDefaultProvider("sepolia");
const wallet = new Wallet(PRIVATE_KEY, provider, ethProvider);
const recipient = Wallet.createRandom();
const tx = wallet.populateTransaction({
to: recipient.address,
amount: ethers.utils.parseEther("0.01"),
});
requestExecute
Request execution of L2 transaction from L1.
Inputs
Name | Type | Description |
---|---|---|
transaction.contractAddress | Address | The L2 contract to be called. |
transaction.calldata | BytesLike | The input of the L2 transaction. |
transaction.l2GasLimit? | BigNumberish | Maximum amount of L2 gas that transaction can consume during execution on L2. |
transaction.mintValue? | BigNumberish | The amount of base token that needs to be minted on non-ETH-based L2.. |
transaction.l2Value? | BigNumberish | msg.value of L2 transaction. |
transaction.factoryDeps? | ethers.BytesLike[] | An array of L2 bytecodes that will be marked as known on L2. |
transaction.operatorTip? | BigNumberish | (currently is not used) If the ETH value passed with the transaction is not explicitly stated in the overrides, this field will be equal to the tip the operator will receive on top of the base cost of the transaction. |
transaction.gasPerPubdataByte? | BigNumberish | The L2 gas price for each published L1 calldata byte. |
transaction.refundRecipient? | Address | The address on L2 that will receive the refund for the transaction. If the transaction fails, it will also be the address to receive l2Value . |
transaction.overrides? | ethers.PayableOverrides | Transaction's overrides which may be used to pass L2 gasLimit , gasPrice , value , etc. |
async requestExecute(transaction: {
contractAddress: Address;
calldata: BytesLike;
l2GasLimit?: BigNumberish;
mintValue?: BigNumberish;
l2Value?: BigNumberish;
factoryDeps?: BytesLike[];
operatorTip?: BigNumberish;
gasPerPubdataByte?: BigNumberish;
refundRecipient?: Address;
overrides?: ethers.PayableOverrides;
}): Promise<PriorityOpResponse>
Example
import { Wallet, Provider, utils } from "zksync-ethers";
import { ethers } from "ethers";
const PRIVATE_KEY = "<WALLET_PRIVATE_KEY>";
const CONTRACT_ADDRESS = "<CONTRACT_ADDRESS>";
const provider = Provider.getDefaultProvider(types.Network.Sepolia);
const ethProvider = ethers.getDefaultProvider("sepolia");
const wallet = new Wallet(PRIVATE_KEY, provider, ethProvider);
const gasPrice = await wallet.providerL1.getGasPrice();
// The calldata can be encoded the same way as for Ethereum.
// Here is an example of how to get the calldata from an ABI:
const abi = [
{
inputs: [],
name: "increment",
outputs: [],
stateMutability: "nonpayable",
type: "function",
},
];
const contractInterface = new ethers.utils.Interface(abi);
const calldata = contractInterface.encodeFunctionData("increment", []);
const l2GasLimit = BigNumber.from(1000);
const txCostPrice = await wallet.getBaseCost({
gasPrice,
calldataLength: ethers.utils.arrayify(calldata).length,
l2GasLimit,
});
console.log(`Executing the transaction will cost ${ethers.utils.formatEther(txCostPrice)} ETH`);
const executeTx = await wallet.requestExecute({
contractAddress: CONTRACT_ADDRESS,
calldata,
l2Value: 1,
l2GasLimit,
overrides: {
gasPrice,
value: txCostPrice,
},
});
await executeTx.wait();
sendTransaction
Broadcast the transaction to the network.
Throws an error when tx.from
is mismatched from the private key.
Inputs
Parameter | Type | Description |
---|---|---|
tx | ethers.providers.TransactionRequest | Transaction request. |
async sendTransaction(tx: ethers.providers.TransactionRequest): Promise<TransactionResponse>
Example
import { Wallet, Provider, utils } from "zksync-ethers";
import { ethers } from "ethers";
const PRIVATE_KEY = "<WALLET_PRIVATE_KEY>";
const provider = Provider.getDefaultProvider(types.Network.Sepolia);
const ethProvider = ethers.getDefaultProvider("sepolia");
const wallet = new Wallet(PRIVATE_KEY, provider);
const recipient = Wallet.createRandom();
const tx = await wallet.sendTransaction({
type: utils.EIP712_TX_TYPE,
to: recipient.address,
value: ethers.utils.parseEther("1"),
});
signTransaction
Signs the transaction and serializes it to be ready to be broadcast to the network.
Throws an error when transaction.from
is mismatched from the private key.
Inputs
Parameter | Type | Description |
---|---|---|
transaction | TransactionRequest | Transaction request. |
async signTransaction(transaction: TransactionRequest): Promise<string>
Example
import { Wallet, Provider, utils } from "zksync-ethers";
import { ethers } from "ethers";
const PRIVATE_KEY = "<WALLET_PRIVATE_KEY>";
const provider = Provider.getDefaultProvider(types.Network.Sepolia);
const ethProvider = ethers.getDefaultProvider("sepolia");
const wallet = new Wallet(PRIVATE_KEY, provider);
const recipient = Wallet.createRandom();
const tx = await wallet.signTransaction({
type: utils.EIP712_TX_TYPE,
to: recipient.address,
value: ethers.utils.parseEther("1"),
});
transfer
For convenience, the Wallet
class has transfer
method, which can transfer
ETH
or any ERC20
token within the same interface.
Inputs
Parameter | Type | Description |
---|---|---|
transaction.to | Address | The address of the recipient. |
transaction.amount | BigNumberish | The amount of the token to transfer. |
transaction.token? | Address | The address of the token. ETH by default. |
transaction.paymasterParams? | PaymasterParams | Paymaster parameters. |
transaction.overrides? | ethers.CallOverrides | Transaction's overrides which may be used to pass L2 gasLimit , gasPrice , value , etc. |
async transfer(transaction: {
to: Address;
amount: BigNumberish;
token?: Address;
overrides?: ethers.CallOverrides;
}): Promise<TransactionResponse>
Examples
Transfer ETH.
import { Wallet, Provider, types, utils } from "zksync-ethers";
import { ethers } from "ethers";
const PRIVATE_KEY = "<WALLET_PRIVATE_KEY>";
const provider = Provider.getDefaultProvider(types.Network.Sepolia);
const wallet = new Wallet(PRIVATE_KEY, provider);
const transferTx = await wallet.transfer({
to: Wallet.createRandom().address,
amount: ethers.utils.parseEther("0.01"),
});
const receipt = await transferHandle.wait();
console.log(`The sum of ${receipt.value} ETH was transferred to ${receipt.to}`);
Transfer ETH using paymaster to facilitate fee payment with an ERC20 token.
import { Wallet, Provider, types, utils } from "zksync-ethers";
import { ethers } from "ethers";
const PRIVATE_KEY = "<WALLET_PRIVATE_KEY>";
const token = "0x927488F48ffbc32112F1fF721759649A89721F8F"; // Crown token which can be minted for free
const paymaster = "0x13D0D8550769f59aa241a41897D4859c87f7Dd46"; // Paymaster for Crown token
const provider = Provider.getDefaultProvider(types.Network.Sepolia);
const wallet = new Wallet(PRIVATE_KEY, provider);
const transferTx = await wallet.transfer({
to: Wallet.createRandom().address,
amount: ethers.utils.parseEther("0.01"),
paymasterParams: utils.getPaymasterParams(paymaster, {
type: "ApprovalBased",
token: token,
minimalAllowance: 1,
innerInput: new Uint8Array(),
}),
});
const receipt = await transferTx.wait();
console.log(`The sum of ${receipt.value} ETH was transferred to ${receipt.to}`);
Transfer token.
import { Wallet, Provider, types, utils } from "zksync-ethers";
import { ethers } from "ethers";
const PRIVATE_KEY = "<WALLET_PRIVATE_KEY>";
const provider = Provider.getDefaultProvider(types.Network.Sepolia);
const wallet = new Wallet(PRIVATE_KEY, provider);
const tokenL2 = "0x6a4Fb925583F7D4dF82de62d98107468aE846FD1";
const transferTx = await wallet.transfer({
token: tokenL2,
to: Wallet.createRandom().address,
amount: ethers.utils.parseEther("0.01"),
});
const receipt = await transferHandle.wait();
console.log(`The sum of ${receipt.value} token was transferred to ${receipt.to}`);
Transfer token using paymaster to facilitate fee payment with an ERC20 token.
import { Wallet, Provider, types, utils } from "zksync-ethers";
import { ethers } from "ethers";
const PRIVATE_KEY = "<WALLET_PRIVATE_KEY>";
const token = "0x927488F48ffbc32112F1fF721759649A89721F8F"; // Crown token which can be minted for free
const paymaster = "0x13D0D8550769f59aa241a41897D4859c87f7Dd46"; // Paymaster for Crown token
const provider = Provider.getDefaultProvider(types.Network.Sepolia);
const wallet = new Wallet(PRIVATE_KEY, provider);
const tokenL2 = "0x6a4Fb925583F7D4dF82de62d98107468aE846FD1";
const transferTx = await wallet.transfer({
token: tokenL2,
to: Wallet.createRandom().address,
amount: ethers.utils.parseEther("0.01"),
paymasterParams: utils.getPaymasterParams(paymaster, {
type: "ApprovalBased",
token: token,
minimalAllowance: 1,
innerInput: new Uint8Array(),
}),
});
const receipt = await transferTx.wait();
console.log(`The sum of ${receipt.value} token was transferred to ${receipt.to}`);
withdraw
Initiates the withdrawal process which withdraws ETH or any ERC20 token from the associated account on L2 network to the target account on L1 network.
Inputs
Parameter | Type | Description |
---|---|---|
transaction.token | Address | The address of the token. ETH by default. |
transaction.amount | BigNumberish | The amount of the token to withdraw. |
transaction.to? | Address | The address of the recipient on L1. |
transaction.bridgeAddress? | Address | The address of the bridge contract to be used. |
transaction.paymasterParams? | PaymasterParams | Paymaster parameters. |
transaction.overrides? | ethers.CallOverrides | Transaction's overrides which may be used to pass L2 gasLimit , gasPrice , value , etc. |
async withdraw(transaction: {
token: Address;
amount: BigNumberish;
to?: Address;
bridgeAddress?: Address;
paymasterParams?: PaymasterParams;
overrides?: ethers.CallOverrides;
}): Promise<TransactionResponse>
Examples
Withdraw ETH.
import { Wallet, Provider, types, utils } from "zksync-ethers";
const PRIVATE_KEY = "<WALLET_PRIVATE_KEY>";
const provider = Provider.getDefaultProvider(types.Network.Sepolia);
const wallet = new Wallet(PRIVATE_KEY, provider);
const withdrawTx = await wallet.withdraw({
token: utils.ETH_ADDRESS,
amount: 10_000_000,
});
Withdraw ETH using paymaster to facilitate fee payment with an ERC20 token.
import { Wallet, Provider, types, utils } from "zksync-ethers";
const PRIVATE_KEY = "<WALLET_PRIVATE_KEY>";
const token = "0x927488F48ffbc32112F1fF721759649A89721F8F"; // Crown token which can be minted for free
const paymaster = "0x13D0D8550769f59aa241a41897D4859c87f7Dd46"; // Paymaster for Crown token
const provider = Provider.getDefaultProvider(types.Network.Sepolia);
const wallet = new Wallet(PRIVATE_KEY, provider);
const withdrawTx = await wallet.withdraw({
token: utils.ETH_ADDRESS,
amount: 10_000_000,
paymasterParams: utils.getPaymasterParams(paymaster, {
type: "ApprovalBased",
token: token,
minimalAllowance: 1,
innerInput: new Uint8Array(),
}),
});
Withdraw token.
import { Wallet, Provider, types, utils } from "zksync-ethers";
const PRIVATE_KEY = "<WALLET_PRIVATE_KEY>";
const provider = Provider.getDefaultProvider(types.Network.Sepolia);
const wallet = new Wallet(PRIVATE_KEY, provider);
const tokenL2 = "0x6a4Fb925583F7D4dF82de62d98107468aE846FD1";
const withdrawTx = await wallet.withdraw({
token: tokenL2,
amount: 10_000_000,
});
Withdraw token using paymaster to facilitate fee payment with an ERC20 token.
import { Wallet, Provider, types, utils } from "zksync-ethers";
const PRIVATE_KEY = "<WALLET_PRIVATE_KEY>";
const token = "0x927488F48ffbc32112F1fF721759649A89721F8F"; // Crown token which can be minted for free
const paymaster = "0x13D0D8550769f59aa241a41897D4859c87f7Dd46"; // Paymaster for Crown token
const provider = Provider.getDefaultProvider(types.Network.Sepolia);
const wallet = new Wallet(PRIVATE_KEY, provider);
const tokenL2 = "0x6a4Fb925583F7D4dF82de62d98107468aE846FD1";
const withdrawTx = await wallet.withdraw({
token: tokenL2,
amount: 10_000_000,
paymasterParams: utils.getPaymasterParams(paymaster, {
type: "ApprovalBased",
token: token,
minimalAllowance: 1,
innerInput: new Uint8Array(),
}),
});