Client - ZKsync SDK Docs

`ZKsyncClient`

This doc details ZKsync Era specific methods.
Web3Swift implementations link to their GitHub.

`allAccountBalances`

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

Calls the zks_getAllAccountBalances JSON-RPC method.

Inputs

Parameter	Type	Description
`address`	`String`	Account address.

Example

let accountBalances = try! await self.ZKsync.allAccountBalances("0x36615Cf349d7F6344891B1e7CA7C72883F5dc049")

`blockDetails`

Returns additional ZKsync-specific information about the L2 block.

Calls the zks_getBlockDetails JSON-RPC method.

Inputs

Parameter	Type	Description
`blockNumber`	`BigUInt`	Block number.

Example

let blockDetails = try! await ZKsync.blockDetails(blockNumber: BigUInt(90_000))

`bridgeContracts`

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

Example

let bridgeAddresses = try await ZKsync.bridgeContracts()

`constructor`

Returns a ZKsyncClient object.

Inputs

Parameter	Type	Description
`providerURL`	`URL`	Network RPC URL (optional).

Example

var ZKsync: ZKsyncClient= BaseClient(URL(string: "https://sepolia.era.zksync.dev"))

`estimateFee`

Returns an estimated Fee for requested transaction.

Inputs

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

var ZKsync: ZKsyncClient= BaseClient(URL(string: "https://sepolia.era.zksync.dev"))
var transaction = CodableTransaction(to: EthereumAddress("<TO_ADDRESS>")!, value: BigUInt(7_000_000_000), from: EthereumAddress("<FROM_ADDRESS>"))
 
let fee = try! await ZKsync.estimateFee(transaction)

`estimateGas`

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

Inputs

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

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";
 
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: 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 BigUInt object.

Calls the zks_estimateL1ToL2 JSON-RPC method.

Inputs

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

Example

var EIP712Meta = EIP712Meta()
EIP712Meta.gasPerPubdata = gasPerPubData
 
var transaction = CodableTransaction(
  type: .eip1559,
  to: EthereumAddress(from: "<TO>")!,
  value: BigUInt(7_000_000_000),
  data: calldata,
  eip712Meta: EIP712Meta,
  from: EThereumAddress(from: "<FROM>")!
)
 
let gasL1 = try! await ZKsync.estimateGasL1(transaction)

`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
`to`	`String`	To address.
`amount`	`BigUInt`	Amount of token.
`from`	`String`	From address.
`token`	`String`	Token address (optional).
`options`	`TransactionOption`	TransactionOption (optional).
`paymasterParams`	`PaymasterParams`	Paymaster parameters (optional).

Example

let gas = try! await ZKsync.web3.eth.estimateGas("<TO_ADDReSS>", amount: BigUInt(7_000_000_000))

`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
`amount`	`BigUInt`	Amount of token.
`from`	`String`	From address.
`to`	`String`	To address (optional).
`token`	`String`	Token address (optional).
`options`	`TransactionOption`	TransactionOption (optional).
`paymasterParams`	`PaymasterParams`	Paymaster parameters (optional).

Example

let gas = try! await ZKsync.web3.eth.estimateGasWithdraw(amount: BigUInt(7_000_000_000),
                                                        "<FROM_ADDReSS>")

`estimateL1ToL2Execute`

Returns gas estimation for an L1 to L2 execute operation.

Inputs

Parameter	Type	Description
`to`	`String`	Address of contract.
`from`	`String`	Caller address.
`calldata`	`Data`	The transaction call data.
`amount`	`BigUInt`	The deposit amount (optional).
`gasPerPubdataByte?`	`BigNumberish`	Constant representing current amount of gas per byte (optional).

Example

let mainContractAddress = try! await wallet.walletL1.mainContract()
let gasL1ToL2 = try! await ZKsync.estimateL1ToL2Execute(
  to: mainContractAddress,
  from: "0x36615Cf349d7F6344891B1e7CA7C72883F5dc049",
  calldata: Data(hex: "0x"),
  amount: BigUInt(7_000_000_000))

`getBalance`

Returns the user's balance as a bigint 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`	`String`	Account address.
`blockNumber`	`BlockNumber`	Block tag for getting the balance on. Latest `committed` block is default (optional).
`tokenAddress?`	`String`	Token address. ETH is default (optional).

Example

let tokenAddress = "0x927488F48ffbc32112F1fF721759649A89721F8F"
let ethBalance = try! await ZKsync.getBalance(address: "0x36615Cf349d7F6344891B1e7CA7C72883F5dc049")
let tokenBalance = try! await ZKsync.getBalance(address: "0x36615Cf349d7F6344891B1e7CA7C72883F5dc049", blockNumber: .latest, token: tokenAddress)

`getL2HashFromPriorityOp`

Returns a L2 transaction hash from L1 transaction response.

Inputs

Parameter	Type	Description
`receipt`	`TransactionReceipt`	L1 transaction receipt.

Example

let l1Tx = "0xcca5411f3e514052f4a4ae1c2020badec6e0998adb52c09959c5f5ff15fba3a8";
let receipt = try! await ZKsync.web3.eth.transactionReceipt(Data(hex: "l1Tx")
let l2Hash = try! await wallet.walletL1.ZKsync.getL2HashFromPriorityOp(receipt: receipt!)

`getL2ToL1LogProof`

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`	`String`	Hash of the L2 transaction the L2 to L1 log was produced within.
`index`	`Int`	The index of the L2 to L1 log in the transaction (optional).

Example

// Any L2 -> L1 transaction can be used.
// In this case, withdrawal transaction is used.
let tx = "0x2a1c6c74b184965c0cb015aae9ea134fd96215d2e4f4979cfec12563295f610e";
let logProof = try! await wallet.walletL1.ZKsync.getL2ToL1LogProof(txHash: tx, index: 0)

`getTestnetPaymaster`

Returns the testnet paymaster address if available, or null.

Example

let paymasterAddress = try! await wallet.walletL1.ZKsync.getTestnetPaymaster()

`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.

Example

let TX_HASH = "<YOUR_TX_HASH_ADDRESS>";
let transactionDetails = try! await wallet.walletL1.ZKsync.transactionDetails(TX_HASH)

`getTransferTx`

Returns the populated transfer transaction.

Inputs

Parameter	Type	Description
`to`	`String`	To address.
`amount`	`BigUInt`	Amount of token.
`from`	`String`	From address.
`token`	`String`	Token address (optional).
`options`	`TransactionOption`	TransactionOption (optional).
`paymasterParams`	`PaymasterParams`	Paymaster parameters (optional).

Example

let tx = try! await ZKsync.web3.eth.getTransferTx("<TO_ADDReSS>", amount: BigUInt(7_000_000_000))

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

let token = "0x927488F48ffbc32112F1fF721759649A89721F8F" // Crown token which can be minted for free
let paymaster = "0x13D0D8550769f59aa241a41897D4859c87f7Dd46" // Paymaster for Crown token
 
let paymasterInput = Paymaster.encodeApprovalBased(
    EthereumAddress(token)!,
    minimalAllowance: BigUInt(1),
    paymasterInput: Data()
)
let paymasterParams = PaymasterParams(
  paymaster: EthereumAddress(paymaster)!,
  paymasterInput: paymasterInput)
 
let result = try! await ZKsync.web3.eth.getTransferTx(
  "<TO_ADDReSS>",
  amount: BigUInt(7_000_000_000),
  paymasterParams: paymasterParams)
 
let receipt = await ZKsyncTransactionReceiptProcessor(ZKsync: ZKsync).waitForTransactionReceipt(hash: result.hash)

`getWithdrawTx`

Returns the populated withdrawal transaction.

Inputs

Parameter	Type	Description
`amount`	`BigUInt`	Amount of token.
`from`	`String`	From address.
`to`	`String`	To address.
`token`	`String`	Token address (optional).
`options`	`TransactionOption`	TransactionOption (optional).
`paymasterParams`	`PaymasterParams`	Paymaster parameters (optional).

Examples

Retrieve populated ETH withdrawal transactions.

let result = try! await ZKsync.getWithdrawTx(BigUInt(7_000_000_000), from: "0x36615Cf349d7F6344891B1e7CA7C72883F5dc049", to: "0x36615Cf349d7F6344891B1e7CA7C72883F5dc049", token: nil, options:
nil, paymasterParams: nil)

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

let token = "0x927488F48ffbc32112F1fF721759649A89721F8F" // Crown token which can be minted for free
let paymaster = "0x13D0D8550769f59aa241a41897D4859c87f7Dd46" // Paymaster for Crown token
 
let paymasterInput = Paymaster.encodeApprovalBased(
    EthereumAddress(token)!,
    minimalAllowance: BigUInt(1),
    paymasterInput: Data()
)
let paymasterParams = PaymasterParams(
  paymaster: EthereumAddress(paymaster)!,
  paymasterInput: paymasterInput)
 
let result = try! await ZKsync.getWithdrawTx(BigUInt(7_000_000_000), from: "0x36615Cf349d7F6344891B1e7CA7C72883F5dc049", to: "0x36615Cf349d7F6344891B1e7CA7C72883F5dc049", token: nil, options:
nil, paymasterParams: paymasterParams)

`l1BatchBlockRange`

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`	`BigUInt`	L1 batch number.

Example

let l1BatchNumber = try await ZKsync.l1BatchNumber()
let l1BatchBlockRange = try await ZKsync.l1BatchBlockRange(l1BatchNumber: l1BatchNumber)

`l1BatchDetails`

Returns data pertaining to a given batch.

Calls the zks_getL1BatchDetails JSON-RPC method.

Inputs

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

Example

let l1BatchNumber = try await ZKsync.l1BatchNumber()
let l1BatchDetails = try await ZKsync.l1BatchDetails(l1BatchNumber: l1BatchNumber)

`l1BatchNumber`

Returns the latest L1 batch number.

Calls the zks_getL1BatchNumber JSON-RPC method.

Example

let l1BatchNumber = try await ZKsync.l1BatchNumber()

`l1ChainId`

Returns the chain id of the underlying L1.

Calls the zks_L1ChainId JSON-RPC method.

Example

let result = try! await ZKsync.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`	`String`	The address of the token on L2.

Example

let result = try! await ZKsync.l1TokenAddress(address: "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`	`String`	The address of the token on L1.

Example

let result = try! await ZKsync.l2TokenAddress(address: "0x5C221E77624690fff6dd741493D735a17716c26B")

`mainContract`

Returns the main ZKsync Era smart contract address.

Calls the zks_getMainContract JSON-RPC method.

Example

let mainContractAddress = try! await wallet.walletL1.ZKsync.mainContract()

Introduction

Overview of the Client component in the ZKsync Era

Introduction

Overview of the accounts package in ZKsync Era