Python API

Provider

Web3Provider for ZKsync Python SDK

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

init

Returns a ZKsync Era Provider object.

Inputs

ParameterTypeDescription
web3string or ConnectionInfoNetwork 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

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

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

ParameterTypeDescription
transactionTransactionTransaction.
tokenAddress stringToken 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

ParameterType
TransactionTransaction

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

NameDescription
addressUser's address.
block_tagBlock tag for getting the balance on. Latest committed block is default.
token_addressThe 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.

NameDescription
blockBlock 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

NameTypeDescription
tx_hashHexStrHash of the L2 transaction where the withdrawal was initiated.
indexintIn 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

NameDescription
addressContract 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

NameDescription
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

NameDescription
tx_receiptTransaction receipt.
main_contractZkSync 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

NameDescription
tx_hashTransaction hash.
indexLog 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

NameDescription
tx_hashTransaction 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

NameDescription
tx_hashTransaction 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

NameDescription
transactionTransferTransaction
fromFrom 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

NameDescription
transactionWithdrawTransaction
fromFrom 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

NameDescription
tokenThe 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

NameDescription
tokenThe 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

NameDescription
tokenThe 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)

Made with ❤️ by the ZKsync Community