Provider - ZKsync Docs

Provider objects facilitate interaction with the ZKsync network, allowing users to manage transactions, estimate fees, and retrieve network information.

`connectL2Bridge`

Returns contract wrapper. If given address is shared bridge address it returns Il2SharedBridge and if its legacy it returns Il2Bridge.

Inputs

Parameter	Type	Description
`address`	'Address'	The bridge address.

async connectL2Bridge(address: Address): Promise<Il2SharedBridge | Il2Bridge>

Example

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

const provider = Provider.getDefaultProvider(types.Network.Sepolia);
const l2Bridge = await provider.connectL2Bridge("<L2_BRIDGE_ADDRESS>");

`constructor`

Initializes a ZKsync Era Provider object.

Inputs

Parameter	Type	Description
`url?`	string or `ConnectionInfo`	Network RPC URL
`network?`	`ethers.providers.Networkish`	Network name

constructor(url?: ConnectionInfo | string, network?: ethers.providers.Networkish)

Example

import { Provider } from "zksync-ethers";

const provider = new Provider("https://sepolia.era.zksync.dev");

`estimateFee`

Returns an estimated Fee for requested transaction.

Inputs

Parameter	Type	Description
`transaction`	`TransactionRequest`	Transaction request.

async estimateFee(transaction: TransactionRequest): Promise<Fee>

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

const provider = Provider.getDefaultProvider(types.Network.Sepolia);
const fee = await provider.estimateFee({
  from: "0x36615Cf349d7F6344891B1e7CA7C72883F5dc049",
  to: "0xa61464658AfeAf65CccaaFD3a512b69A83B77618",
  value: `0x${BigNumber.from(7_000_000_000).toString(16)}`,
});
console.log(`Fee: ${utils.toJSON(fee)}`);

`estimateGas`

Returns an estimate of the amount of gas required to submit a transaction to the network.

Parameter	Type	Description
`transaction`	`TransactionRequest`	Transaction request.

async estimateGas(transaction: utils.Deferrable<TransactionRequest>): Promise<BigNumber>

Example

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

const provider = Provider.getDefaultProvider(types.Network.Sepolia);
const gasTokenApprove = await provider.estimateGas({
  from: "0x36615Cf349d7F6344891B1e7CA7C72883F5dc049",
  to: "0x765F5AF819D818a8e8ee6ff63D8d0e8056DBE150",
  data: utils.IERC20.encodeFunctionData("approve", [RECEIVER, 1]),
});
console.log(`Gas for token approval tx: ${gasTokenApprove}`);

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

const ADDRESS = "0x36615Cf349d7F6344891B1e7CA7C72883F5dc049";
const RECEIVER = "0xa61464658AfeAf65CccaaFD3a512b69A83B77618";
const provider = Provider.getDefaultProvider(types.Network.Sepolia);
const tokenAddress = "0x927488F48ffbc32112F1fF721759649A89721F8F"; // Crown token which can be minted for free
const paymasterAddress = "0x13D0D8550769f59aa241a41897D4859c87f7Dd46"; // Paymaster for Crown token

const paymasterParams = utils.getPaymasterParams(paymasterAddress, {
  type: "ApprovalBased",
  token: tokenAddress,
  minimalAllowance: BigNumber.from(1),
  innerInput: new Uint8Array(),
});

const tokenApprove = await provider.estimateGas({
  from: ADDRESS,
  to: tokenAddress,
  data: utils.IERC20.encodeFunctionData("approve", [RECEIVER, 1]),
  customData: {
    gasPerPubdata: utils.DEFAULT_GAS_PER_PUBDATA_LIMIT,
    paymasterParams,
  },
});
console.log(`Gas for token approval using EIP-712 tx: ${tokenApprove}`);

`estimateGasL1`

Returns an estimate of the amount of gas required to submit a transaction from L1 to L2 as a BigNumber object.

Calls the zks_estimateL1ToL2 JSON-RPC method.

Inputs

Parameter	Type	Description
`transaction`	`TransactionRequest`	Transaction request.

async estimateGasL1(transaction: TransactionRequest): Promise<BigNumber>

Example

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

const provider = Provider.getDefaultProvider(types.Network.Sepolia);
const gasL1 = await provider.estimateGasL1({
  from: "0x36615Cf349d7F6344891B1e7CA7C72883F5dc049",
  to: await provider.getMainContractAddress(),
  value: 7_000_000_000,
  customData: {
    gasPerPubdata: 800,
  },
});
console.log(`L1 gas: ${BigNumber.from(gasL1)}`);

`estimateGasTransfer`

Returns the gas estimation for a transfer transaction.

Calls internal method getTransferTx to get the transfer transaction and sends it to the estimateGas method.

Inputs

Parameter	Type	Description
`token`	`Address`	Token address.
`amount`	`BigNumberish`	Amount of token.
`from?`	`Address`	From address.
`to?`	`Address`	To address.
`paymasterParams?`	`PaymasterParams`	Paymaster parameters.
`overrides?`	`ethers.CallOverrides`	Transaction's overrides which may be used to pass l2 `gasLimit`, `gasPrice`, `value`, etc.

async estimateGasTransfer(transaction: {
    to: Address;
    amount: BigNumberish;
    from?: Address;
    token?: Address;
    paymasterParams ?: PaymasterParams;
    overrides?: ethers.CallOverrides;
}): Promise<BigNumber>

Example

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

const provider = Provider.getDefaultProvider(types.Network.Sepolia);
const gasTransfer = await provider.estimateGasTransfer({
  token: utils.ETH_ADDRESS,
  amount: 7_000_000_000,
  to: "0xa61464658AfeAf65CccaaFD3a512b69A83B77618",
  from: "0x36615Cf349d7F6344891B1e7CA7C72883F5dc049",
});
console.log(`Gas for transfer tx: ${gasTransfer}`);

`estimateGasWithdraw`

Returns the gas estimation for a withdrawal transaction.

Calls internal method getWithdrawTx to get the withdrawal transaction and sends it to the estimateGas method.

Inputs

Parameter	Type	Description
`token`	`Address`	Token address.
`amount`	`BigNumberish`	Amount of token.
`from?`	`Address`	From address.
`to?`	`Address`	To address.
`bridgeAddress?`	`Address`	Bridge address.
`paymasterParams?`	`PaymasterParams`	Paymaster parameters.
`overrides?`	`ethers.CallOverrides`	Transaction's overrides which may be used to pass l2 `gasLimit`, `gasPrice`, `value`, etc.

async estimateGasWithdraw(transaction: {
    token: Address;
    amount: BigNumberish;
    from?: Address;
    to?: Address;
    bridgeAddress?: Address;
    paymasterParams ?: PaymasterParams;
    overrides?: ethers.CallOverrides;
}): Promise<BigNumber>

Example

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

const provider = Provider.getDefaultProvider(types.Network.Sepolia);
const gasWithdraw = await provider.estimateGasWithdraw({
  token: utils.ETH_ADDRESS,
  amount: 7_000_000,
  to: "0x36615Cf349d7F6344891B1e7CA7C72883F5dc049",
  from: "0x36615Cf349d7F6344891B1e7CA7C72883F5dc049",
});
console.log(`Gas for withdrawal tx: ${gasWithdraw}`);

`estimateL1ToL2Execute`

Returns gas estimation for an L1 to L2 execute operation.

Inputs

Parameter	Type	Description
`contractAddress`	`Address`	Address of contract.
`calldata`	`BytesLike`	The transaction call data.
`caller?`	`Address`	Caller address.
`l2Value?`	`BigNumberish`	The deposit amount.
`factoryDeps?`	`BytesLike[]`	Byte array containing contract bytecode.
`gasPerPubdataByte?`	`BigNumberish`	Constant representing current amount of gas per byte.
`overrides?`	`ethers.PayableOverrides`	Transaction's overrides which may be used to pass l2 `gasLimit`, `gasPrice`, `value`, etc.

async estimateL1ToL2Execute(transaction: {
    contractAddress: Address;
    calldata: BytesLike;
    caller?: Address;
    l2Value?: BigNumberish;
    factoryDeps?: ethers.BytesLike[];
    gasPerPubdataByte?: BigNumberish;
    overrides?: ethers.PayableOverrides;
}): Promise<BigNumber>

Example

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

const provider = Provider.getDefaultProvider(types.Network.Sepolia);
const gasL1ToL2 = await provider.estimateL1ToL2Execute({
  contractAddress: await provider.getMainContractAddress(),
  calldata: "0x",
  caller: "0x36615Cf349d7F6344891B1e7CA7C72883F5dc049",
  l2Value: 7_000_000_000,
});
console.log(`Gas L1 to L2: ${BigNumber.from(gasL1ToL2)}`);

`getAllAccountBalances`

Returns all balances for confirmed tokens given by an account address.

Calls the zks_getAllAccountBalances JSON-RPC method.

Inputs

Parameter	Type	Description
`address`	`Address`	Account address.

async getAllAccountBalances(address: Address): Promise<BalancesMap>

Example

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

const provider = Provider.getDefaultProvider(types.Network.Sepolia);
const balances = await provider.getAllAccountBalances("0x36615Cf349d7F6344891B1e7CA7C72883F5dc049");
console.log(`All balances: ${utils.toJSON(balances)}`);

`getBalance`

Returns the user's balance as a BigNumber object for an (optional) block tag and (optional) token.

When block and token are not supplied, committed and ETH are the default values.

Inputs

Parameter	Type	Description
`address`	`Address`	Account address.
`blockTag?`	`BlockTag`	Block tag for getting the balance on. Latest `committed` block is default.
`tokenAddress?`	`Address`	Token address. ETH is default.

async getBalance(address: Address, blockTag?: BlockTag, tokenAddress?: Address)

Example

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

const provider = Provider.getDefaultProvider(types.Network.Sepolia);
const account = "0x36615Cf349d7F6344891B1e7CA7C72883F5dc049";
const tokenAddress = "0x927488F48ffbc32112F1fF721759649A89721F8F"; // Crown token which can be minted for free
console.log(`ETH balance: ${await provider.getBalance(account)}`);
console.log(`Token balance: ${await provider.getBalance(account, "latest", tokenAddres)}`);

`getBaseTokenContractAddress`

Returns the L1 base token address.

Calls the zks_getBaseTokenL1Address JSON-RPC method.

async getBaseTokenContractAddress(): Promise<Address>

Example

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

const provider = Provider.getDefaultProvider(types.Network.Sepolia);
console.log(`Base token: ${await provider.getBaseTokenContractAddress()}`);

`getBlock`

Returns block from the network, or false if there is no block.

async getBlock(blockHashOrBlockTag: BlockTag | string | Promise<BlockTag | string>): Promise<Block>

Example

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

const provider = Provider.getDefaultProvider(types.Network.Sepolia);
console.log(`Block: ${utils.toJSON(await provider.getBlock("latest", true))}`);

`getBlockDetails`

Returns additional ZKsync-specific information about the L2 block.

Calls the zks_getBlockDetails JSON-RPC method.

Inputs

Parameter	Type	Description
`number`	`number`	Block number.

async getBlockDetails(number:number): Promise<BlockDetails>

Example

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

const provider = Provider.getDefaultProvider(types.Network.Sepolia);
console.log(`Block details: ${utils.toJSON(await provider.getBlockDetails(90_000))}`);

`getBridgehubContractAddress`

Returns the Bridgehub smart contract address.

Calls the zks_getBridgehubContract JSON-RPC method.

async getBridgehubContractAddress(): Promise<Address>

Example

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

const provider = Provider.getDefaultProvider(types.Network.Sepolia);
console.log(`Bridgehub: ${await provider.getBridgehubContractAddress()}`);

`getBytecodeByHash`

Returns bytecode of a contract given by its hash.

Calls the zks_getBytecodeByHash JSON-RPC method.

Inputs

Parameter	Type	Description
`bytecodeHash`	`BytesLike`	Bytecode hash.

async getBytecodeByHash(bytecodeHash: BytesLike): Promise<Uint8Array>

Example

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

// Bytecode hash can be computed by following these steps:
// const testnetPaymasterBytecode = await provider.getCode(await provider.getTestnetPaymasterAddress());
// const testnetPaymasterBytecodeHash = ethers.utils.hexlify(utils.hashBytecode(testnetPaymasterBytecode));

const testnetPaymasterBytecodeHash = "0x010000f16d2b10ddeb1c32f2c9d222eb1aea0f638ec94a81d4e916c627720e30";

const provider = Provider.getDefaultProvider(types.Network.Sepolia);
console.log(`Bytecode: ${await provider.getBytecodeByHash(testnetPaymasterBytecodeHash)}`);

`getConfirmedTokens`

Returns confirmed tokens. Confirmed token is any token bridged to ZKsync Era via the official bridge.

Calls the zks_getConfirmedTokens JSON-RPC method.

Inputs

Parameter	Type	Description
`start`	`Address`	The token id from which to start. Default 0.
`limit`	`Address`	The maximum number of tokens to list. Default 255.

async getConfirmedTokens(start: number = 0, limit: number = 255): Promise<Token[]>

Example

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

const provider = Provider.getDefaultProvider(types.Network.Sepolia);
const tokens = await provider.getConfirmedTokens();
console.log(`Confirmed tokens: ${utils.toJSON(tokens)}`);

`getContractAccountInfo`

Returns the version of the supported account abstraction and nonce ordering from a given contract address.

Inputs

Parameter	Type	Description
`address`	`Address`	Contract address.

async getContractAccountInfo(address:Address): Promise<ContractAccountInfo>

Example

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

const provider = Provider.getDefaultProvider(types.Network.Sepolia);
const tokenAddress = "0x927488F48ffbc32112F1fF721759649A89721F8F"; // Crown token which can be minted for free
console.log(`Contract account info: ${utils.toJSON(await provider.getContractAccountInfo(tokenAddress))}`);

`getDefaultBridgeAddresses`

Returns the addresses of the default ZKsync Era bridge contracts on both L1 and L2.

getDefaultBridgeAddresses(): Promise<{
  erc20L1: string;
  erc20L2: string;
  wethL1: string;
  wethL2: string;
  sharedL1: string;
  sharedL2: string;
}>

Example

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

const provider = Provider.getDefaultProvider(types.Network.Sepolia);
console.log(`Default bridges: ${utils.toJSON(await provider.getDefaultBridgeAddresses())}`);

`getDefaultProvider`

Static method which returns a Provider object from the RPC URL or localhost.

Inputs

Parameter	Type	Description
`zksyncNetwork`	`ZkSyncNetwork`	Type of ZKsync network. `Localhost` by default.

static getDefaultProvider(zksyncNetwork: ZkSyncNetwork = ZkSyncNetwork.Localhost)

Example

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

const providerMainnet = Provider.getDefaultProvider(types.Network.Mainnet);
const providerTestnet = Provider.getDefaultProvider(types.Network.Sepolia);
const providerLocalnet = Provider.getDefaultProvider(types.Network.Localhost);

`getFeeParams`

Returns the current fee parameters.

Calls the zks_getFeeParams JSON-RPC method.

async getFeeParams(): Promise<FeeParams>

Example

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

const provider = Provider.getDefaultProvider(types.Network.Sepolia);
const feeParams = await provider.getFeeParams();
console.log(`Fee: ${utils.toJSON(feeParams)}`);

`getFilterChanges`

Returns an array of logs by calling Ethereum method eth_getFilterChanges.

Inputs

Parameter	Type	Description
`idx`	`BigNumber`	Filter index.

async getFilterChanges(idx: BigNumber): Promise<Array<Log | string>>

Example

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

const provider = Provider.getDefaultProvider(types.Network.Sepolia);
const filter = await provider.newFilter({
  address: utils.L2_ETH_TOKEN_ADDRESS,
  topics: [ethers.id("Transfer(address,address,uint256)")],
});
const result = await provider.getFilterChanges(filter);

`getFormatter`

Static utility method that returns a Formatter object for processing readable block data.

static override getFormatter(): Formatter

Example

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

const formatter = Provider.getFormatter();

`getGasPrice`

Returns an estimate (best guess) of the gas price to use in a transaction.

async getGasPrice(): Promise<BigNumber>

Example

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

const provider = Provider.getDefaultProvider(types.Network.Sepolia);
console.log(`Gas price: ${await provider.getGasPrice()}`);

`getL1BatchBlockRange`

Returns the range of blocks contained within a batch given by batch number.

Calls the zks_getL1BatchBlockRange JSON-RPC method.

Inputs

Parameter	Type	Description
`l1BatchNumber`	`number`	L1 batch number.

async getL1BatchBlockRange(l1BatchNumber: number): Promise<[number, number] | null>

Example

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

const provider = Provider.getDefaultProvider(types.Network.Sepolia);
const l1BatchNumber = await provider.getL1BatchNumber();
console.log(`L1 batch block range: ${utils.toJSON(await provider.getL1BatchBlockRange(l1BatchNumber))}`);

`getL1BatchDetails`

Returns data pertaining to a given batch.

Calls the zks_getL1BatchDetails JSON-RPC method.

Inputs

Parameter	Type	Description
`number`	`number`	L1 batch number.

async getL1BatchDetails(number: number): Promise<BatchDetails>

Example

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

const provider = Provider.getDefaultProvider(types.Network.Sepolia);
const l1BatchNumber = await provider.getL1BatchNumber();
console.log(`L1 batch details: ${utils.toJSON(await provider.getL1BatchDetails(l1BatchNumber))}`);

`getL1BatchNumber`

Returns the latest L1 batch number.

Calls the zks_getL1BatchNumber JSON-RPC method.

async getL1BatchNumber(): Promise<number>

Example

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

const provider = Provider.getDefaultProvider(types.Network.Sepolia);
console.log(`L1 batch number: ${await provider.getL1BatchNumber()}`);

`getL2TransactionFromPriorityOp`

Returns a L2 transaction from L1 transaction response.

Inputs

Parameter	Type	Description
`l1TxResponse`	`TransactionResponse`	L1 transaction response.

async getL2TransactionFromPriorityOp(l1TxResponse: ethers.TransactionResponse): Promise<TransactionResponse>

Example

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

const provider = Provider.getDefaultProvider(types.Network.Sepolia);
const ethProvider = ethers.getDefaultProvider("sepolia");
const l1Tx = "0xcca5411f3e514052f4a4ae1c2020badec6e0998adb52c09959c5f5ff15fba3a8";
const l1TxResponse = await ethProvider.getTransaction(l1Tx);
if (l1TxResponse) {
  console.log(`Tx: ${utils.toJSON(await provider.getL2TransactionFromPriorityOp(l1TxResponse))}`);
}

`getLogProof`

Returns the proof for a transaction's L2 to L1 log sent via the L1Messenger system contract.

Calls the zks_getL2ToL1LogProof JSON-RPC method.

Inputs

Parameter	Type	Description
`txHash`	`BytesLike`	Hash of the L2 transaction the L2 to L1 log was produced within.
`index?`	`number`	The index of the L2 to L1 log in the transaction.

async getLogProof(txHash: BytesLike, index ? : number): Promise<MessageProof | null>

Example

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

const provider = Provider.getDefaultProvider(types.Network.Sepolia);
// Any L2 -> L1 transaction can be used.
// In this case, withdrawal transaction is used.
const tx = "0x2a1c6c74b184965c0cb015aae9ea134fd96215d2e4f4979cfec12563295f610e";
console.log(`Log ${utils.toJSON(await provider.getLogProof(tx, 0))}`);

`getLogs`

Returns an array of all logs that match a filter with a given id by calling Ethereum method eth_getLogs.

Inputs

Parameter	Type	Description
`filter`	`Filter` or `FilterByBlockHash` or `Promise<Filter, FilterByBlockHash>`	Filter query.

getLogs(filter: Filter | FilterByBlockHash | Promise<Filter | FilterByBlockHash>): Promise<Array<Log>>

Example

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

const provider = Provider.getDefaultProvider(types.Network.Sepolia);
console.log(`Logs: ${utils.toJSON(await provider.getLogs({ fromBlock: 0, toBlock: 5, address: utils.L2_ETH_TOKEN_ADDRESS }))}`);

`getMainContractAddress`

Returns the main ZKsync Era smart contract address.

Calls the zks_getMainContract JSON-RPC method.

async getMainContractAddress(): Promise<Address>

Example

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

const provider = Provider.getDefaultProvider(types.Network.Sepolia);
console.log(`Main contract: ${await provider.getMainContractAddress()}`);

`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 { Provider, types, utils } from "zksync-ethers";

const provider = Provider.getDefaultProvider(types.Network.Sepolia);
// Any L2 -> L1 transaction can be used.
// In this case, withdrawal transaction is used.
const tx = "0x2a1c6c74b184965c0cb015aae9ea134fd96215d2e4f4979cfec12563295f610e";
console.log(`Confirmation data: ${utils.toJSON(await provider.getPriorityOpConfirmation(tx, 0))}`);

`getPriorityOpResponse`

Returns a TransactionResponse as a PriorityOpResponse object.

Inputs

Parameter	Type	Description
`l1TxResponse`	`TransactionResponse`	L1 transaction response.

async getPriorityOpResponse(l1TxResponse: ethers.TransactionResponse): Promise<PriorityOpResponse>

Example

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

const provider = Provider.getDefaultProvider(types.Network.Sepolia);
const ethProvider = ethers.getDefaultProvider("sepolia");
const l1Tx = "0xcca5411f3e514052f4a4ae1c2020badec6e0998adb52c09959c5f5ff15fba3a8";
const l1TxResponse = await ethProvider.getTransaction(l1Tx);
if (l1TxResponse) {
  console.log(`Tx: ${utils.toJSON(await provider.getPriorityOpResponse(l1TxResponse))}`);
}

`getProof`

Returns Merkle proofs for one or more storage values at the specified account along with a Merkle proof of their authenticity.

Calls the zks_getProof JSON-RPC method.

Inputs

Parameter	Type	Description
`address`	`Address`	The account to fetch storage values and proofs for.
`keys`	`string[]`	Vector of storage keys in the account.
`l1BatchNumber`	`number`	Number of the L1 batch specifying the point in time at which the requested values are returned.

async getProof(address: Address, keys: string[], l1BatchNumber: number): Promise<StorageProof>

Example

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

const provider = Provider.getDefaultProvider(types.Network.Sepolia);
const address = "0x082b1BB53fE43810f646dDd71AA2AB201b4C6b04";

// Fetching the storage proof for rawNonces storage slot in NonceHolder system contract.
// mapping(uint256 => uint256) internal rawNonces;

// Ensure the address is a 256-bit number by padding it
// because rawNonces slot uses uint256 for mapping addresses and their nonces.
const addressPadded = ethers.utils.hexZeroPad(wallet.address, 32);

// Convert the slot number to a hex string and pad it to 32 bytes.
const slotPadded = ethers.utils.hexZeroPad(ethers.utils.hexlify(0), 32);

// Concatenate the padded address and slot number.
const concatenated = addressPadded + slotPadded.slice(2); // slice to remove '0x' from the slotPadded

// Hash the concatenated string using Keccak-256.
const storageKey = ethers.utils.keccak256(concatenated);

const l1BatchNumber = await provider.getL1BatchNumber();
const storageProof = await provider.getProof(utils.NONCE_HOLDER_ADDRESS, [storageKey], l1BatchNumber);
console.log(`Storage proof: ${utils.toJSON(storageProof)}`);

`getProtocolVersion`

Return the protocol version.

Calls the zks_getProtocolVersion JSON-RPC method.

Inputs

Parameter	Type	Description
`id`	`number`	Specific version ID (optional).

async getProtocolVersion(id?: number): Promise<ProtocolVersion>

Example

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

const provider = Provider.getDefaultProvider(types.Network.Sepolia);
console.log(`Protocol version: ${await provider.getProtocolVersion()}`);

`getRawBlockTransactions`

Returns data of transactions in a block.

Calls the zks_getRawBlockTransactions JSON-RPC method.

Inputs

Parameter	Type	Description
`number`	`number`	Block number.

async getRawBlockTransactions(number: number): Promise<RawBlockTransaction[]>

Example

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

const provider = Provider.getDefaultProvider(types.Network.Sepolia);
console.log(`Raw block transactions: ${utils.toJSON(await provider.getRawBlockTransactions(90_000))}`);

`getTestnetPaymasterAddress`

Returns the testnet paymaster address if available, or null.

async getTestnetPaymasterAddress(): Promise<Address | null>

Example

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

const provider = Provider.getDefaultProvider(types.Network.Sepolia);
console.log(`Testnet paymaster: ${await provider.getTestnetPaymasterAddress()}`);

`getTransaction`

Returns a specified L2 transaction response object by overriding the Ethers implementation.

Inputs

Parameter	Type	Description
`txHash`	`string`	Transaction hash.

async getTransaction(hash: string | Promise<string>): Promise<TransactionResponse>

Example

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

const provider = Provider.getDefaultProvider(types.Network.Sepolia);

const TX_HASH = "<YOUR_TX_HASH_ADDRESS>";
const txHandle = await provider.getTransaction(TX_HASH);

// Wait until the transaction is processed by the server.
await txHandle.wait();
// Wait until the transaction is finalized.
await txHandle.waitFinalize();

`getTransactionDetails`

Returns data from a specific transaction given by the transaction hash.

Calls the getTransactionDetails JSON-RPC method.

Inputs

Parameter	Type	Description
`txHash`	`BytesLike`	Transaction hash.

async getTransactionDetails(txHash: BytesLike): Promise<TransactionDetails>

Example

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

const provider = Provider.getDefaultProvider(types.Network.Sepolia);

const TX_HASH = "<YOUR_TX_HASH_ADDRESS>";
console.log(`Transaction details: ${utils.toJSON(await provider.getTransactionDetails(TX_HASH))}`);

`getTransactionReceipt`

Returns the transaction receipt from a given hash number.

Ethers implementation.

Inputs

Parameter	Type	Description
`txHash`	`string`	Transaction hash.

async getTransactionReceipt(transactionHash: string | Promise<string>): Promise<TransactionReceipt>

Example

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

const provider = Provider.getDefaultProvider(types.Network.Sepolia);
const TX_HASH = "<YOUR_TX_HASH_ADDRESS>";
console.log(`Transaction receipt: ${utils.toJSON(await provider.getTransactionReceipt(TX_HASH))}`);

`getTransactionStatus`

Returns the status of a specified transaction.

Inputs

Parameter	Type	Description
`txHash`	`string`	Transaction hash.

async getTransactionStatus(txHash: string): Promise<TransactionStatus>

Example

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

const provider = Provider.getDefaultProvider(types.Network.Sepolia);

const TX_HASH = "<YOUR_TX_HASH_ADDRESS>";
console.log(`Transaction status: ${utils.toJSON(await provider.getTransactionStatus(TX_HASH))}`);

`getTransferTx`

Returns the populated transfer transaction.

Inputs

Parameter	Type	Description
`token`	`Address`	Token address.
`amount`	`BigNumberish`	Amount of token.
`from?`	`Address`	From address.
`to?`	`Address`	To address.
`paymasterParams?`	`PaymasterParams`	Paymaster parameters.
`overrides?`	`ethers.CallOverrides`	Transaction's overrides which may be used to pass l2 `gasLimit`, `gasPrice`, `value`, etc.

async getTransferTx(transaction: {
  to: Address;
  amount: BigNumberish;
  from ? : Address;
  token ? : Address;
  paymasterParams?: PaymasterParams;
  overrides?: ethers.CallOverrides;
}): Promise<EthersTransactionRequest>

Examples

Retrieve populated ETH transfer transaction.

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

const provider = Provider.getDefaultProvider(types.Network.Sepolia);

const tx = await provider.getTransferTx({
  token: utils.ETH_ADDRESS,
  amount: 7_000_000_000,
  to: "0xa61464658AfeAf65CccaaFD3a512b69A83B77618",
  from: "0x36615Cf349d7F6344891B1e7CA7C72883F5dc049",
});
console.log(`Transfer tx: ${tx}`);

Retrieve populated ETH transfer transaction using paymaster to facilitate fee payment with an ERC20 token.

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

const provider = Provider.getDefaultProvider(types.Network.Sepolia);
const token = "0x927488F48ffbc32112F1fF721759649A89721F8F"; // Crown token which can be minted for free
const paymaster = "0x13D0D8550769f59aa241a41897D4859c87f7Dd46"; // Paymaster for Crown token

const tx = await provider.getTransferTx({
  token: utils.ETH_ADDRESS,
  amount: 7_000_000_000,
  to: "0xa61464658AfeAf65CccaaFD3a512b69A83B77618",
  from: "0x36615Cf349d7F6344891B1e7CA7C72883F5dc049",
  paymasterParams: utils.getPaymasterParams(paymaster, {
    type: "ApprovalBased",
    token: token,
    minimalAllowance: 1,
    innerInput: new Uint8Array(),
  }),
});
console.log(`Transfer tx: ${tx}`);

`getWithdrawTx`

Returns the populated withdrawal transaction.

Inputs

Parameter	Type	Description
`token`	`Address`	Token address.
`amount`	`BigNumberish`	Amount of token.
`from?`	`Address`	From address.
`to?`	`Address`	To address.
`bridgeAddress?`	`Address`	Bridge address.
`paymasterParams?`	`PaymasterParams`	Paymaster parameters.
`overrides?`	`ethers.CallOverrides`	Transaction's overrides which may be used to pass l2 `gasLimit`, `gasPrice`, `value`, etc.

async getWithdrawTx(transaction: {
  token: Address;
  amount: BigNumberish;
  from ? : Address;
  to ? : Address;
  bridgeAddress ? : Address;
  paymasterParams?: PaymasterParams;
  overrides?: ethers.CallOverrides;
}): Promise<EthersTransactionRequest>

Examples

Retrieve populated ETH withdrawal transactions.

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

const provider = Provider.getDefaultProvider(types.Network.Sepolia);

const tx = await provider.getWithdrawTx({
  token: utils.ETH_ADDRESS,
  amount: 7_000_000_000,
  to: "0x36615Cf349d7F6344891B1e7CA7C72883F5dc049",
  from: "0x36615Cf349d7F6344891B1e7CA7C72883F5dc049",
});
console.log(`Withdrawal tx: ${tx}`);

Retrieve populated ETH withdrawal transaction using paymaster to facilitate fee payment with an ERC20 token.

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

const provider = Provider.getDefaultProvider(types.Network.Sepolia);
const token = "0x927488F48ffbc32112F1fF721759649A89721F8F"; // Crown token which can be minted for free
const paymaster = "0x13D0D8550769f59aa241a41897D4859c87f7Dd46"; // Paymaster for Crown token

const tx = await provider.getWithdrawTx({
  token: utils.ETH_ADDRESS,
  amount: 7_000_000_000,
  to: "0x36615Cf349d7F6344891B1e7CA7C72883F5dc049",
  from: "0x36615Cf349d7F6344891B1e7CA7C72883F5dc049",
  paymasterParams: utils.getPaymasterParams(paymaster, {
    type: "ApprovalBased",
    token: token,
    minimalAllowance: 1,
    innerInput: new Uint8Array(),
  }),
});
console.log(`Withdrawal tx: ${tx}`);

`isBaseToken`

Returns whether the token is the base token.

Inputs

Parameter	Type	Description
`token`	`Address`	The address of the token.

async isBaseToken(token: Address): Promise<string>

Example

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

const provider = Provider.getDefaultProvider(types.Network.Sepolia);
console.log(`Is base token: ${await provider.isBaseToken("0x5C221E77624690fff6dd741493D735a17716c26B")}`);

`isEthBasedChain`

Returns whether the chain is ETH-based.

async isEthBasedChain(): Promise<boolean>

Example

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

const provider = Provider.getDefaultProvider(types.Network.Sepolia);
console.log(`Is ETH based chain: ${await provider.isEthBasedChain()}`);

`isL2BridgeLegacy`

Returns true if passed bridge address is legacy and false if its shared bridge.

Inputs

Parameter	Type	Description
`address`	'Address'	The bridge address.

async isL2BridgeLegacy(address: Address): Promise<boolean>

Example

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

const provider = Provider.getDefaultProvider(types.Network.Sepolia);
const isBridgeLegacy = await provider.isL2BridgeLegacy("<L2_BRIDGE_ADDRESS>");
console.log(isBridgeLegacy);

`l1ChainId`

Returns the chain id of the underlying L1.

Calls the zks_L1ChainId JSON-RPC method.

async l1ChainId(): Promise<number>

Example

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

const provider = Provider.getDefaultProvider(types.Network.Sepolia);
console.log(`L1 chain ID: ${await provider.l1ChainId()}`);

`l1TokenAddress`

Returns the L1 token address equivalent for a L2 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

Parameter	Type	Description
`token`	`Address`	The address of the token on L2.

async l1TokenAddress(token: Address): Promise<string>

Example

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

const provider = Provider.getDefaultProvider(types.Network.Sepolia);
console.log(`L1 token address: ${await provider.l1TokenAddress("0x3e7676937A7E96CFB7616f255b9AD9FF47363D4b")}`);

`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

Parameter	Type	Description
`token`	`Address`	The address of the token on L1.
`bridgeAddress?`	`Address`	The address of the custom bridge on L2(optional).

async l2TokenAddress(token: Address): Promise<string>

Example

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

const provider = Provider.getDefaultProvider(types.Network.Sepolia);
console.log(`L2 token address: ${await provider.l2TokenAddress("0x5C221E77624690fff6dd741493D735a17716c26B")}`);

`newBlockFilter`

Returns a new block filter by calling Ethereum method eth_newBlockFilter.

async newBlockFilter(): Promise<BigNumber>

Example

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

const provider = Provider.getDefaultProvider(types.Network.Sepolia);
console.log(`New block filter: ${await provider.newBlockFilter()}`);

`newFilter`

Returns a new filter by calling Ethereum method eth_newFilter and passing a filter object.

Inputs

Parameter	Type	Description
`filter`	`EventFilter` or `Promise<EventFilter>`	Filter query.

async newFilter(filter: EventFilter | Promise<EventFilter>): Promise<Number>

Example

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

const provider = Provider.getDefaultProvider(types.Network.Sepolia);
console.log(
  `New filter: ${await provider.newFilter({
    fromBlock: 0,
    toBlock: 5,
    address: utils.L2_ETH_TOKEN_ADDRESS,
  })}`
);

`newPendingTransactionFilter`

Returns a new pending transaction filter by calling Ethereum method eth_newPendingTransactionFilter and passing a filter object.

async newPendingTransactionsFilter(): Promise<BigNumber>

Example

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

const provider = Provider.getDefaultProvider(types.Network.Sepolia);
console.log(`New pending transaction filter: ${await provider.newPendingTransactionsFilter()}`);

`sendRawTransactionWithDetailedOutput`

Executes a transaction and returns its hash, storage logs, and events that would have been generated if the transaction had already been included in the block. The API has a similar behaviour to eth_sendRawTransaction but with some extra data returned from it.

With this API Consumer apps can apply "optimistic" events in their applications instantly without having to wait for ZKsync block confirmation time.

It’s expected that the optimistic logs of two uncommitted transactions that modify the same state will not have causal relationships between each other.

Calls the zks_sendRawTransactionWithDetailedOutput JSON-RPC method.

Inputs

Parameter	Type	Description
`signedTx`	`string`	The signed transaction that needs to be broadcasted.

async sendRawTransactionWithDetailedOutput(signedTx: string): Promise<TransactionWithDetailedOutput>

Example

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

const PRIVATE_KEY = "<PRIVATE_KEY>";
const provider = Provider.getDefaultProvider(types.Network.Sepolia);
const wallet = new Wallet(PRIVATE_KEY, provider);

const txWithOutputs = await provider.sendRawTransactionWithDetailedOutput(
  await wallet.signTransaction({
    to: Wallet.createRandom().address,
    value: ethers.utils.parseEther("0.01"),
  })
);

console.log(`Transaction with detailed output: ${utils.toJSON(txWithOutputs)}`);

For development and testing, it is recommended to use burner wallets. Avoid using real private keys to prevent security risks.

`sendTransaction`

Override of Ethers implementation.

Inputs

Parameter	Type	Description
`transaction`	`string` or `Promise<string>`	Signed transaction.

async sendTransaction(transaction: string | Promise<string>): Promise<TransactionResponse>

Example

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

const PRIVATE_KEY = "<PRIVATE_KEY>";
const provider = Provider.getDefaultProvider(types.Network.Sepolia);
const wallet = new Wallet(PRIVATE_KEY, provider);

const signedTx = await wallet.signTransaction({
  to: "0xa61464658AfeAf65CccaaFD3a512b69A83B77618",
  value: ethers.utils.parseEther("0.01"),
});

const tx = await provider.sendTransaction(signedTx);
console.log(tx.hash);

Introduction

Provider objects for interacting with ZKsync.

Web3Provider

Web3Provider object for interacting with ZKsync.