Provider - ZKsync SDK Docs

A Web3Provider object provides application-layer access to underlying blockchain networks.

The zksync2 library supports provider methods from the web3.py library and supplies additional functionality.

`Provider`

This doc details ZKsync Era specific methods.
web3.py implementations link to the web3.py Providers documentation.

`init`

Returns a ZKsync Era Provider object.

Inputs

Parameter	Type	Description
`web3`	string or `ConnectionInfo`	Network RPC URL (optional)

Example

from zksync2.module.module_builder import ZkSyncBuilder

zksync = ZkSyncBuilder.build("https://sepolia.era.zksync.dev")

`zks_estimate_fee`

Returns an estimated Fee for requested transaction.

Inputs

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

Example

func_call = TxFunctionCall(
            chain_id=chain_id,
            nonce=nonce,
            from_=account.address,
            to=saccount.address,
            gas_limit=0,
            gas_price=gas_price,
        )
estimated_fee = web3.zksync.zks_estimate_fee(func_call.tx)

`eth_estimate_gas`

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

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

web3.py implementation.

Example

func_call = TxFunctionCall(
            chain_id=chain_id,
            nonce=nonce,
            from_=account.address,
            to=saccount.address,
            gas_limit=0,
            gas_price=gas_price,
        )
estimated_fee = web3.zksync.eth_estimate_gas(func_call.tx)

`zks_estimate_gas_l1_to_l2`

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

Calls the zks_estimateL1ToL2 JSON-RPC method.

Example

func_call = TxFunctionCall(
            chain_id=chain_id,
            nonce=nonce,
            from_=account.address,
            to=saccount.address,
            value=7_000_000_000
        )
estimated_fee = web3.zksync.zks_estimate_gas_l1_to_l2(func_call.tx)

`zks_estimate_gas_transfer`

Returns the gas estimation for a transfer transaction.

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

Inputs

Parameter	Type	Description
`transaction`	`Transaction`	Transaction.
`token`	Address string	Token address (optional).

Example

func_call = TxFunctionCall(
            chain_id=chain_id,
            nonce=nonce,
            from_=account.address,
            to=saccount.address,
            value=7_000_000_000
        )
estimated_fee = web3.zksync.zks_estimate_gas_transfer(func_call.tx)

`zks_estimate_l1_to_l2_execute`

Returns gas estimation for an L1 to L2 execute operation.

Inputs

Parameter	Type
`Transaction`	`Transaction`

Example

func_call = TxFunctionCall(
            chain_id=chain_id,
            nonce=nonce,
            from_=account.address,
            to=saccount.address,
            value=7_000_000_000
        )
estimated_fee = web3.zksync.zks_estimate_l1_to_l2_execute(func_call.tx)

`zks_get_all_account_balances`

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

Calls the zks_getAllAccountBalances JSON-RPC method.

all_balances = web3.zksync.zks_get_all_account_balances(address)

`zks_get_balance`

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

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

Inputs

Name	Description
address	User's address.
block_tag	Block tag for getting the balance on. Latest `committed` block is default.
token_address	The address of the token. ETH is default.

Example

zksync_web3 = ZkSyncBuilder.build("https://sepolia.era.zksync.dev")

#Find the USDC ADDRESS in https://zksync2-testnet.zkscan.io/address/0x0faF6df7054946141266420b43783387A78d82A9/transactions
USDC_L2_ADDRESS = "<USDC_L2_ADDRESS>"
# Get the USDC balance from your account using your address. Get your address from https://zksync2-testnet.zkscan.io/txs
usdc_balance = zksync_web3.zksync.zks_get_balance("<YOUR_ADDRESS>", "latest", USDC_L2_ADDRESS)

// Getting ETH balance
eth_balance = zksync_web3.zksync.zks_get_balance("<YOUR_ADDRESS>")

`zks_get_base_token_contract_address`

Returns the L1 base token address.

Calls the zks_getBaseTokenL1Address JSON-RPC method.

Example

from zksync2.module.module_builder import ZkSyncBuilder

if __name__ == "__main__":
    # Set a provider
    PROVIDER = "https://sepolia.era.zksync.dev"

    # Connect to ZKsync network
    provider = ZkSyncBuilder.build(PROVIDER)

    print(provider.zksync.zks_get_base_token_contract_address())

`zks_get_block_details`

Returns BlockDetails additional ZKsync-specific information about the L2 block.

Calls the zks_getBlockDetails JSON-RPC method.

Name	Description
block	Block number.

Example

zksync_web3 = ZkSyncBuilder.build("https://sepolia.era.zksync.dev")

block_details = zksync_web3.zksync.zks_get_block_details(block_number)

`zks_get_bridgehub_contract_address`

Returns the Bridgehub smart contract address.

Calls the zks_getBridgehubContract JSON-RPC method.

Example

from zksync2.module.module_builder import ZkSyncBuilder

if __name__ == "__main__":
    # Set a provider
    PROVIDER = "https://sepolia.era.zksync.dev"

    # Connect to ZKsync network
    provider = ZkSyncBuilder.build(PROVIDER)

    print(provider.zksync.zks_get_bridgehub_contract_address())

`get_priority_op_confirmation`

Returns the transaction confirmation data that is part of L2->L1 message.

Inputs

Name	Type	Description
`tx_hash`	`HexStr`	Hash of the L2 transaction where the withdrawal was initiated.
`index`	`int`	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 (optional).

Example

from zksync2.module.module_builder import ZkSyncBuilder

if __name__ == "__main__":
    # Set a provider
    PROVIDER = "https://sepolia.era.zksync.dev"

    # Connect to ZKsync network
    provider = ZkSyncBuilder.build(PROVIDER)

    print(provider.zksync.get_priority_op_confirmation("0x2a1c6c74b184965c0cb015aae9ea134fd96215d2e4f4979cfec12563295f610e", 0))

`getContractAccountInfo`

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

Inputs

Name	Description
address	Contract address

Example

zksync_web3 = ZkSyncBuilder.build("https://sepolia.era.zksync.dev")

result = zksync_web3.zksync.get_contract_account_info(contract_address)

`zks_get_bridge_contracts`

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

zksync_web3 = ZkSyncBuilder.build("https://sepolia.era.zksync.dev")

addresses = zksync_web3.zksync.zks_get_bridge_contracts()

`zks_get_l1_batch_block_range`

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

Calls the zks_getL1BatchBlockRange JSON-RPC method.

Inputs

Name	Description
l1_batch_number

zksync_web3 = ZkSyncBuilder.build("https://sepolia.era.zksync.dev")

l1_batch_number = zksync_web3.zksync.zks_l1_batch_number()
block_range = zksync_web3.zksync.zks_get_l1_batch_block_range(l1_batch_number)

`zks_get_l1_batch_details`

Returns data pertaining to a given batch.

Calls the zks_getL1BatchDetails JSON-RPC method.

zksync_web3 = ZkSyncBuilder.build("https://sepolia.era.zksync.dev")

l1_batch_number = zksync_web3.zksync.zks_l1_batch_number()
batch_details = zksync_web3.zksync.zks_get_l1_batch_details(l1_batch_number)

`zks_l1_batch_number`

Returns the latest L1 batch number.

Calls the zks_L1BatchNumber JSON-RPC method.

zksync_web3 = ZkSyncBuilder.build("https://sepolia.era.zksync.dev")

l1_batch_number = zksync_web3.zksync.zks_l1_batch_number()

`get_l2_transaction_from_priority_op`

Returns a transaction object from a given Ethers TransactionResponse object.

Inputs

Name	Description
tx_receipt	Transaction receipt.
main_contract	ZkSync main contract

def get_l2_transaction_from_priority_op(self, tx_receipt, main_contract: Contract):
    l2_hash = self.get_l2_hash_from_priority_op(tx_receipt, main_contract)
    self.wait_for_transaction_receipt(l2_hash)
    return self.get_transaction(l2_hash)

`zks_get_log_proof`

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

Name	Description
tx_hash	Transaction hash.
index	Log index. Default is None

zksync_web3 = ZkSyncBuilder.build("https://sepolia.era.zksync.dev")

proof: ZksMessageProof = zksync_web3.zksync.zks_get_log_proof(hex_hash)

`zks_main_contract`

Returns the main ZKsync Era smart contract address.

Calls the zks_getMainContract JSON-RPC method.

Example

zksync_web3 = ZkSyncBuilder.build("https://sepolia.era.zksync.dev")

main_contract_address = zksync.zksync.zks_main_contract()

`zks_get_l2_to_l1_msg_proof`

Returns the proof for a message sent via the L1Messenger system contract.

Calls the zks_getL2ToL1MsgProof JSON-RPC method.

def zks_get_l2_to_l1_msg_proof(self,
                               block: int,
                               sender: HexStr,
                               message: str,
                               l2log_pos: Optional[int]) -> ZksMessageProof:
    return self._zks_get_l2_to_l1_msg_proof(block, sender, message, l2log_pos)

`zks_get_testnet_paymaster_address`

Returns the testnet paymaster address if available, or null.

Example

zksync_web3 = ZkSyncBuilder.build("https://sepolia.era.zksync.dev")

paymaster_address = zksync.zksync.zks_get_testnet_paymaster_address()

`zks_get_transaction_details`

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

Calls the getTransactionDetails JSON-RPC method.

Inputs

Name	Description
tx_hash	Transaction hash.

Example

zksync_web3 = ZkSyncBuilder.build("https://sepolia.era.zksync.dev")

transaction_details = zksync.zksync.zks_get_transaction_details()

`eth_get_transaction_receipt`

Returns the transaction receipt from a given hash number.

Inputs

Name	Description
tx_hash	Transaction hash.

Examples

zksync_web3 = ZkSyncBuilder.build("https://sepolia.era.zksync.dev")

transaction_receipt = zksync_web3.zksync.eth_get_transaction_receipt(tx_hash)

`get_transfer_transaction`

Returns the populated transfer transaction.

Inputs

Name	Description
transaction	`TransferTransaction`
`from`	From address.

Examples

Retrieve populated ETH transfer transactions.

from eth_typing import HexStr

from zksync2.core.types import TransferTransaction
from zksync2.core.utils import LEGACY_ETH_ADDRESS
from zksync2.module.module_builder import ZkSyncBuilder

if __name__ == "__main__":
  ZKSYNC_PROVIDER = "https://sepolia.era.zksync.dev"

  zk_web3 = ZkSyncBuilder.build(ZKSYNC_PROVIDER)

  withdraw_tx = zk_web3.zksync.get_withdraw_transaction(
      TransferTransaction
      (
          to=HexStr("0xa61464658AfeAf65CccaaFD3a512b69A83B77618"),
          token_address=LEGACY_ETH_ADDRESS,
          amount=7_000_000_000
      ),
      from_=HexStr("0x36615Cf349d7F6344891B1e7CA7C72883F5dc049"))

`get_withdraw_transaction`

Returns the populated withdrawal transaction.

Inputs

Name	Description
transaction	`WithdrawTransaction`
`from`	From address.

Examples

Retrieve populated ETH withdrawal transactions.

from eth_typing import HexStr

from zksync2.core.types import WithdrawTransaction
from zksync2.core.utils import LEGACY_ETH_ADDRESS
from zksync2.module.module_builder import ZkSyncBuilder

if __name__ == "__main__":
  ZKSYNC_PROVIDER = "https://sepolia.era.zksync.dev"

  zk_web3 = ZkSyncBuilder.build(ZKSYNC_PROVIDER)

  withdraw_tx = zk_web3.zksync.get_withdraw_transaction(WithdrawTransaction(
      token=LEGACY_ETH_ADDRESS,
      amount=7_000_000_000,
      to=HexStr("0x36615Cf349d7F6344891B1e7CA7C72883F5dc049")
  ),
      from_=HexStr("0x36615Cf349d7F6344891B1e7CA7C72883F5dc049"))

`is_base_token`

Returns whether the token is the base token.

Inputs

Name	Description
token	The address of the token.

Examples

from zksync2.module.module_builder import ZkSyncBuilder

if __name__ == "__main__":
    # Set a provider
    PROVIDER = "https://sepolia.era.zksync.dev"

    # Connect to ZKsync network
    provider = ZkSyncBuilder.build(PROVIDER)

    print(provider.zksync.is_base_token("0x5C221E77624690fff6dd741493D735a17716c26B"))

`is_eth_based_chain`

Returns whether the token is the base token.

Examples

from zksync2.module.module_builder import ZkSyncBuilder

if __name__ == "__main__":
    # Set a provider
    PROVIDER = "https://sepolia.era.zksync.dev"

    # Connect to ZKsync network
    provider = ZkSyncBuilder.build(PROVIDER)

    print(provider.zksync.is_eth_based_chain())

`zks_l1_chain_id`

Returns the chain id of the underlying L1.

Calls the zks_L1ChainId JSON-RPC method.

Examples

zksync_web3 = ZkSyncBuilder.build("https://sepolia.era.zksync.dev")

l1_chain_id = zksync_web3.web3.zksync.zks_l1_chain_id()

`l1_token_address`

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

Name	Description
token	The address of the token on L2.

Examples

zksync_web3 = ZkSyncBuilder.build("https://sepolia.era.zksync.dev")

l1_chain_id = zksync_web3.web3.zksync.l1_token_address(ADDRESS_DEFAULT)

`l2_token_address`

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

Name	Description
token	The address of the token on L1.

Examples

zksync_web3 = ZkSyncBuilder.build("https://sepolia.era.zksync.dev")

l1_chain_id = zksync_web3.web3.zksync.l2_token_address(ADDRESS_DEFAULT)

Introduction

Overview of Web3Providers and their functions

Introduction

Manage accounts and sign transactions in the ZKsync Python SDK.