Providers
Providers
Providers are objects that wrap interactions with the zkSync node. If you are new to the concept of providers in ethers
, you should check out their docs here.
zkSync fully supports Ethereum Web3 API, so you can use the provider objects from ethers.js
. However, zkSync API provides some additional JSON-RPC methods, which allow:
- Easily track L1<->L2 transactions.
- Different stages of finality for transactions. By default, our RPC returns information about the last state processed by the server, but some use-cases may require tracking "finalized" transactions only.
And much more! Generally, you can use providers from ethers
for a quick start, but switch to providers from the zksync-web3
library later on.
The zksync-web3
library exports two types of providers:
Provider
which inherits fromethers
'sJsonRpcProvider
and provides access to all of the zkSync JSON-RPC endpoints.Web3Provider
which extends theProvider
class by making it more compatible with Web3 wallets. This is the type of wallet that should be used for browser integrations.
Provider
This is the most commonly used type of provider. It provides the same functionality as ethers.providers.JsonRpcProvider
, but extends it with the zkSync-specific methods.
Creating provider
The constructor accepts the url
to the operator node and the network
name (optional).
constructor(url?: ConnectionInfo | string, network?: ethers.providers.Networkish)
Inputs and outputs
Name | Description |
---|---|
url? | URL of the zkSync operator node. |
network? | The description of the network. |
returns | Provider object. |
Example
import { Provider } from "zksync-web3";
const provider = new Provider("https://zksync2-testnet.zksync.dev");
getBalance
Returns the balance of a user for a certain block tag and a native token. In order to check the balance in ETH
you can either omit the last argument or supply ETH_ADDRESS
provided in the utils
object.
Example:
async getBalance(address: Address, blockTag?: BlockTag, tokenAddress?: Address): Promise<BigNumber>
Inputs and outputs
Name | Description |
---|---|
address | The address of the user to check the balance. |
blockTag? | The block the balance should be checked on. by default the latest processed(committed ) block is used. |
tokenAddress? | The address of the token. by default ETH is used. |
returns | BigNumber object. |
Example
import { Provider } from "zksync-web3";
const provider = new Provider("https://zksync2-testnet.zksync.dev");
const USDC_L2_ADDRESS = "0x0faF6df7054946141266420b43783387A78d82A9";
// Getting USDC balance of account 0x0614BB23D91625E60c24AAD6a2E6e2c03461ebC5 at the latest processed block
console.log(await provider.getBalance("0x0614BB23D91625E60c24AAD6a2E6e2c03461ebC5", "latest", USDC_L2_ADDRESS));
// Getting ETH balance
console.log(await provider.getBalance("0x0614BB23D91625E60c24AAD6a2E6e2c03461ebC5"));
Getting the zkSync smart contract address
async getMainContractAddress(): Promise<string>
Inputs and outputs
Name | Description |
---|---|
returns | The address of the zkSync smart contract. |
Example
import { Provider } from "zksync-web3";
const provider = new Provider("https://zksync2-testnet.zksync.dev");
console.log(await provider.getMainContractAddress());
Getting testnet paymaster address
On zkSync testnets, the testnet paymaster is available.
async getTestnetPaymasterAddress(): Promise<string|null>
Inputs and outputs
Name | Description |
---|---|
returns | The address of the testnet paymaster or null if there isn't any. |
Example
import { Provider } from "zksync-web3";
const provider = new Provider("https://zksync2-testnet.zksync.dev");
console.log(await provider.getTestnetPaymasterAddress());
Getting zkSync default bridge contract addresses
async getDefaultBridgeAddresses(): Promise<{
erc20L1: string;
erc20L2: string;
}>
Inputs and outputs
Name | Description |
---|---|
returns | The addresses of default zkSync bridge contracts on both L1 and L2 |
getConfirmedTokens
Given start
and limit
returns information (address, symbol, name, decimals) about the confirmed tokens with IDs in the interval [start..start+limit-1]
. "Confirmed" is a misnomer here, since a confirmed token is one that has been bridged through the default zkSync bridge. This method will mostly be used by the zkSync team internally.
The tokens are returned in alphabetical order by their symbol, so basically, the token id is its position in an alphabetically sorted array of tokens.
async getConfirmedTokens(start: number = 0, limit: number = 255): Promise<Token[]>
Inputs and outputs
Name | Description |
---|---|
start | The token id from which to start returning the information about the tokens. Zero by default. |
limit | The number of tokens to be returned from the API. 255 by default. |
returns | The array of Token objects sorted by their symbol. |
Example
import { Provider } from "zksync-web3";
const provider = new Provider("https://zksync2-testnet.zksync.dev");
console.log(await provider.getConfirmedTokens());
getTokenPrice
Deprecated
This method is deprecated and will be removed in the near future.
Returns the USD price for a token. Please note that that this is the price that is used by the zkSync team and can be a bit different from the current market price. On testnets, token prices can be very different from the actual market price.
async getTokenPrice(token: Address): Promise<string | null>
Name | Description |
---|---|
token | The address of the token. |
returns | string value of the token price. |
Example
import { Provider } from "zksync-web3";
const provider = new Provider("https://zksync2-testnet.zksync.dev");
console.log(await provider.getTokenPrice(USDC_L2_ADDRESS));
Getting token's address on L2 from its L1 address and vice-versa
Token's address on L2 will not be the same as on L1. ETH's address is set to zero address on both networks.
Provided methods work only for tokens bridged using default zkSync bridges.
// takes L1 address, returns L2 address
async l2TokenAddress(l1Token: Address): Promise<string>
// takes L2 address, returns L1 address
async l1TokenAddress(l2Token: Address): Promise<string>
Name | Description |
---|---|
token | The address of the token on the one layer. |
returns | The address of that token on the opposite layer. |
getTransactionStatus
Given a transaction hash, returns the status of the transaction.
async getTransactionStatus(txHash: string): Promise<TransactionStatus>
Name | Description |
---|---|
txHash | zkSync transaction hash. |
returns | The status of the transaction. You can find the description for TransactionStatus enum variants in the types. |
Example
import { Provider } from "zksync-web3";
const provider = new Provider("https://zksync2-testnet.zksync.dev");
const TX_HASH = "0x95395d90a288b29801c77afbe359774d4fc76c08879b64708c239da8a65dbcf3";
console.log(await provider.getTransactionStatus(TX_HASH));
getTransaction
Given a transaction hash, returns the L2 transaction response object.
async getTransaction(hash: string | Promise<string>): Promise<TransactionResponse>
Name | Description |
---|---|
hash | zkSync transaction hash. |
returns | TransactionResponse object, which allows for easy tracking the state of the transaction. |
Example
import { Provider } from "zksync-web3";
const provider = new Provider("https://zksync2-testnet.zksync.dev");
const TX_HASH = "0x300baeb6804c2068ff796d95336c53ac671eef216e7ae9c17190660cdb1e2c17";
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();
Web3Provider
A class that should be used for web3 browser wallet integrations, adapted for easy compatibility with Metamask, WalletConnect, and other popular browser wallets.
Web3Provider
Creating The main difference from the constructor of Provider
class is that it accepts ExternalProvider
instead of the node URL.
constructor(provider: ExternalProvider, network?: ethers.providers.Networkish)
Inputs and outputs
Name | Description |
---|---|
provider | The ethers.providers.ExternalProvider class instance. For instance, in the case of Metamask it is window.ethereum . |
network? | The description of the network. |
returns | Provider object. |
Example
import { Web3Provider } from "zksync-web3";
const provider = new Web3Provider(window.ethereum);
Getting zkSync signer
Returns a Signer
object that can be used to sign zkSync transactions. More details on the Signer
class can be found in the next section.
Inputs and outputs
Name | Description |
---|---|
returns | Signer class object. |
Example
import { Web3Provider } from "zksync-web3";
const provider = new Web3Provider(window.ethereum);
const signer = provider.getSigner();