V6

Accounts

Overview

zksync-ethers exports following classes that can sign transactions on ZKsync:

  • Wallet class is an extension of the ethers.Wallet with additional ZKsync features.
  • EIP712Signer class that is used to sign EIP712-typed ZKsync transactions.
  • Signer and L1Signer classes, which should be used for browser integration.
  • VoidSigner and L1VoidSigner classes, which should be used for designed to allow an address to be used in any API which accepts a Signer, but for which there are no credentials available to perform any actual signing.
  • SmartAccount which provides better support for account abstraction. There are following factory classes:
    • ECDSASmartAccount: uses a single ECDSA key for signing payload.
    • MultisigECDSASmartAccount: uses multiple ECDSA keys for signing payloads.

Wallet

constructor

Inputs

ParameterTypeDescription
privateKeystring or ethers.SigningKeyThe private key of the Ethereum account.
providerL2?ProviderA ZKsync node provider. Needed for interaction with ZKsync (optional).
providerL1?ethers.ProviderAn Ethereum node provider. Needed for interaction with L1 (optional).
constructor(privateKey: string | ethers.SigningKey, providerL2?: Provider, providerL1?: ethers.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);

fromMnemonic

Creates a Wallet with the provider as L1 provider and a private key that is built from the mnemonic passphrase.

Inputs

ParameterTypeDescription
mnemonicstringThe mnemonic of the private key.
provider?ethers.ProviderAn Ethereum node provider. Needed for interaction with L1 (optional).
static fromMnemonic(mnemonic: string, provider?: ethers.Provider): Wallet

Example

import { Wallet, Provider, utils } from "zksync-ethers";
import { ethers } from "ethers";

const MNEMONIC = "stuff slice staff easily soup parent arm payment cotton hammer scatter struggle";

const ethProvider = ethers.getDefaultProvider("sepolia");
const wallet = Wallet.fromMnemonic(MNEMONIC, ethProvider);

fromEncryptedJson

Creates a Wallet from encrypted json file using provided password.

Inputs

ParameterTypeDescription
jsonstringEncrypted json file.
passwordstring or Uint8ArrayPassword for encrypted json file.
callback?ProgressCallbackIf callback is provided, it is called periodically during decryption so that any UI can be updated (optional).
static async fromEncryptedJson(json: string, password: string | Uint8Array, callback? : ProgressCallback): Promise<Wallet>

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

ParameterTypeDescription
jsonstringEncrypted json file.
passwordstring or Uint8ArrayPassword for encrypted json file.
static fromEncryptedJsonSync(json: string, password: string | Uint8Array): Wallet

Example

import { Wallet } from "zksync-ethers";
import * as fs from "fs";

const wallet = Wallet.fromEncryptedJsonSync(fs.readFileSync("tests/files/wallet.json", "utf8"), "password");

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

ParameterTypeDescription
providerProviderA 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

ParameterTypeDescription
providerethers.ProviderAn 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);

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()}`);

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();

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();

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()}`);

getBalance

Returns the amount of the token the Wallet has.

Inputs

ParameterTypeDescription
token?AddressThe address of the token. ETH by default (optional).
blockTagBlockTagIn 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<bigint>

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

ParameterTypeDescription
token?AddressThe address of the token. ETH by default (optional).
blockTag?BlockTagIn which block a balance should be checked on. committed, i.e. the latest processed one is the default option (optional).
async getBalanceL1(token?: Address, blockTag?: BlockTag): Promise<bigint>

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)}`);

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();

getNonce

Returns account's nonce number.

Inputs

ParameterTypeDescription
blockTag?BlockTagIn which block a balance should be checked on. committed, i.e. the latest processed one is the default option (optional).
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()}`);

getDeploymentNonce

Returns account's deployment nonce number.

async getDeploymentNonce(): Promise<bigint>

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()}`);

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();

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.

Only works for tokens bridged on default ZKsync Era bridges.

Inputs

ParameterTypeDescription
tokenAddressThe 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.

ParameterTypeDescription
transactionTransactionRequestTransaction 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.parseEther("0.01"),
});

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

ParameterTypeDescription
transactionTransactionRequestTransaction 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.parseEther("1"),
});

sendTransaction

Broadcast the transaction to the network. Throws an error when tx.from is mismatched from the private key.

Inputs

ParameterTypeDescription
txTransactionRequestTransaction request.
async sendTransaction(tx: 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.parseEther("1"),
});

transfer

For convenience, the Wallet class has transfer method, which can transfer ETH or any ERC20 token within the same interface.

Inputs

ParameterTypeDescription
transaction.toAddressThe address of the recipient.
transaction.amountBigNumberishThe amount of the token to transfer.
transaction.token?AddressThe address of the token. ETH by default (optional).
transaction.paymasterParams?PaymasterParamsPaymaster parameters (optional).
transaction.overrides?ethers.OverridesTransaction's overrides which may be used to pass L2 gasLimit, gasPrice, value, etc (optional).
async transfer(transaction: {
  to: Address;
  amount: BigNumberish;
  token?: Address;
  paymasterParams?: PaymasterParams;
  overrides?: ethers.Overrides;
}): Promise<TransactionResponse>

Examples

Transfer ETH.

import { Wallet, Provider, 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 recipient = Wallet.createRandom();

const transferTx = await wallet.transfer({
  to: recipient.address,
  amount: ethers.parseEther("0.01"),
});

const receipt = await transferTx.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, 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 recipient = Wallet.createRandom();

const transferTx = await wallet.transfer({
  to: Wallet.createRandom().address,
  amount: ethers.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 } 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.parseEther("0.01"),
});

const receipt = await transferTx.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 } 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.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}`);

getAllowanceL1

Returns the amount of approved tokens for a specific L1 bridge.

Inputs

ParameterTypeDescription
tokenAddressThe Ethereum address of the token.
bridgeAddress?AddressThe address of the bridge contract to be used. Defaults to the default ZKsync bridge, either L1EthBridge or L1Erc20Bridge (optional).
blockTag?BlockTagIn which block an allowance should be checked on. committed, i.e. the latest processed one is the default option (optional).
async getAllowanceL1(
  token: Address,
  bridgeAddress?: Address,
  blockTag?: ethers.BlockTag
): Promise<bigint>

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)}`);

approveERC20

Bridging ERC20 tokens from Ethereum requires approving the tokens to the ZKsync Ethereum smart contract.

Inputs

ParameterTypeDescription
tokenAddressThe Ethereum address of the token.
amountBigNumberishThe amount of the token to be approved.
overrides?ethers.OverridesTransaction's overrides which may be used to pass L1 gasLimit, gasPrice, value, etc (optional).
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();

getBaseCost

Returns base cost for L2 transaction.

Inputs

NameTypeDescription
params.gasLimitBigNumberishThe gasLimit for the L2 contract call.
params.gasPerPubdataByte?BigNumberishThe L2 gas price for each published L1 calldata byte (optional).
params.gasPrice?BigNumberishThe L1 gas price of the L1 transaction that will send the request for an execute call (optional).
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()}`);

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()}`);

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

ParameterTypeDescription
tokenAddressThe address of the token to deposit.
amountBigNumberishThe 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();

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

ParameterTypeDescription
transaction.tokenAddressThe address of the token to deposit. ETH by default.
transaction.amountBigNumberishThe amount of the token to deposit.
transaction.to?AddressThe address that will receive the deposited tokens on L2 (optional).
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 (optional).
transaction.bridgeAddress?AddressThe address of the bridge contract to be used. Defaults to the default ZKsync bridge (either L1EthBridge or L1Erc20Bridge) (optional).
transaction.approveERC20?booleanWhether 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 (optional).
transaction.approveBaseERC20?booleanWhether 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 (optional).
transaction.l2GasLimit?BigNumberishMaximum amount of L2 gas that transaction can consume during execution on L2 (optional).
transaction.gasPerPubdataByte?BigNumberishWhether 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 (optional).
transaction.refundRecipient?AddressThe address on L2 that will receive the refund for the transaction. If the transaction fails, it will also be the address to receive l2Value (optional).
transaction.overrides?ethers.OverridesTransaction's overrides which may be used to pass L1 gasLimit, gasPrice, value, etc (optional).
transaction.approveOverrides?ethers.OverridesTransaction's overrides which may be used to pass L1 gasLimit, gasPrice, value, etc (optional).
transaction.approveBaseOverrides?ethers.OverridesTransaction's overrides which may be used to pass L1 gasLimit, gasPrice, value, etc (optional).
transaction.customBridgeData?BytesLikeAdditional data that can be sent to a bridge (optional).
async deposit(transaction: {
  token: Address;
  amount: BigNumberish;
  to?: Address;
  operatorTip?: BigNumberish;
  bridgeAddress?: Address;
  approveERC20?: boolean;
  approveBaseERC20?: boolean;
  l2GasLimit?: BigNumberish;
  gasPerPubdataByte?: BigNumberish;
  refundRecipient?: Address;
  overrides?: Overrides;
  approveOverrides?: Overrides;
  approveBaseOverrides?: 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_000n,
});
// 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_000n,
  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_000n,
  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_000n,
  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_000n,
  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();

getDepositTx

Returns populated deposit transaction.

Inputs

ParameterTypeDescription
transaction.tokenAddressThe address of the token to deposit. ETH by default.
transaction.amountBigNumberishThe amount of the token to deposit.
transaction.to?AddressThe address that will receive the deposited tokens on L2 (optional).
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 (optional).
transaction.bridgeAddress?AddressThe address of the bridge contract to be used. Defaults to the default ZKsync bridge (either L1EthBridge or L1Erc20Bridge) (optional).
transaction.l2GasLimit?BigNumberishMaximum amount of L2 gas that transaction can consume during execution on L2 (optional).
transaction.gasPerPubdataByte?BigNumberishWhether 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 (optional).
transaction.customBridgeData?BytesLikeAdditional data that can be sent to a bridge (optional).
transaction.refundRecipient?AddressThe address on L2 that will receive the refund for the transaction. If the transaction fails, it will also be the address to receive l2Value (optional).
transaction.overrides?ethers.OverridesTransaction's overrides which may be used to pass L1 gasLimit, gasPrice, value, etc (optional).
async getDepositTx(transaction: {
  token: Address;
  amount: BigNumberish;
  to?: Address;
  operatorTip?: BigNumberish;
  bridgeAddress?: Address;
  l2GasLimit?: BigNumberish;
  gasPerPubdataByte?: BigNumberish;
  customBridgeData?: BytesLike;
  refundRecipient?: Address;
  overrides?: ethers.Overrides;
}): 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",
});

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

ParameterTypeDescription
transaction.tokenAddressThe address of the token to deposit. ETH by default.
transaction.amountBigNumberishThe amount of the token to deposit.
transaction.to?AddressThe address that will receive the deposited tokens on L2 (optional).
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 (optional).
transaction.bridgeAddress?AddressThe address of the bridge contract to be used. Defaults to the default ZKsync bridge (either L1EthBridge or L1Erc20Bridge) (optional).
transaction.l2GasLimit?BigNumberishMaximum amount of L2 gas that transaction can consume during execution on L2 (optional).
transaction.gasPerPubdataByte?BigNumberishWhether 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 (optional).
transaction.customBridgeData?BytesLikeAdditional data that can be sent to a bridge (optional).
transaction.refundRecipient?AddressThe address on L2 that will receive the refund for the transaction. If the transaction fails, it will also be the address to receive l2Value (optional).
transaction.overrides?ethers.OverridesTransaction's overrides which may be used to pass L1 gasLimit, gasPrice, value, etc (optional).
async estimateGasDeposit(transaction:
  token: Address;
  amount: BigNumberish;
  to?: Address;
  operatorTip?: BigNumberish;
  bridgeAddress?: Address;
  customBridgeData?: BytesLike;
  l2GasLimit?: BigNumberish;
  gasPerPubdataByte?: BigNumberish;
  refundRecipient?: Address;
  overrides?: ethers.Overrides;
 }): Promise<bigint>

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}`);

getFullRequiredDepositFee

Retrieves the full needed ETH fee for the deposit. Returns the L1 fee and the L2 fee FullDepositFee.

Inputs

ParameterTypeDescription
transaction.tokenAddressThe address of the token to deposit. ETH by default.
transaction.to?AddressThe address that will receive the deposited tokens on L2 (optional).
transaction.bridgeAddress?AddressThe address of the bridge contract to be used. Defaults to the default ZKsync bridge (either L1EthBridge or L1Erc20Bridge) (optional).
transaction.customBridgeData?BytesLikeAdditional data that can be sent to a bridge (optional).
transaction.gasPerPubdataByte?BigNumberishWhether 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 (optional).
transaction.overrides?ethers.OverridesTransaction's overrides which may be used to pass L1 gasLimit, gasPrice, value, etc (optional).
async getFullRequiredDepositFee(transaction: {
  token: Address;
  to?: Address;
  bridgeAddress?: Address;
  customBridgeData?: BytesLike;
  gasPerPubdataByte?: BigNumberish;
  overrides?: ethers.Overrides;
}): 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}`);

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

ParameterTypeDescription
depositHashbytes32The 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);

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

ParameterTypeDescription
transaction.tokenAddressThe address of the token. ETH by default.
transaction.amountBigNumberishThe amount of the token to withdraw.
transaction.to?AddressThe address of the recipient on L1 (optional).
transaction.bridgeAddress?AddressThe address of the bridge contract to be used (optional).
transaction.paymasterParams?PaymasterParamsPaymaster parameters (optional).
transaction.overrides?ethers.OverridesTransaction's overrides which may be used to pass L2 gasLimit, gasPrice, value, etc (optional).
async withdraw(transaction: {
  token: Address;
  amount: BigNumberish;
  to?: Address;
  bridgeAddress?: Address;
  paymasterParams?: PaymasterParams;
  overrides?: ethers.Overrides;
}): 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_000n,
});

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_000n,
  paymasterParams: utils.getPaymasterParams(paymaster, {
    type: "ApprovalBased",
    token: token,
    minimalAllowance: 1,
    innerInput: new Uint8Array(),
  }),
});

Withdraw token.

import { Wallet, Provider, types } 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 =<