Wallet - ZKsync SDK Docs

Overview

zksync2-java uses following classes that can sign transactions on ZKsync:

Wallet
EthSigner class that is used to sign EIP712-typed ZKsync transactions.

`Wallet`

`approveERC20`

Bridging ERC20 tokens from Ethereum requires approving the tokens to the ZKsync Ethereum smart contract.

Inputs

Parameter	Type	Description
`token`	`String`	The Ethereum address of the token.
`amount`	`BigInteger`	The amount of the token to be approved.
`bridgeAddress`	`String`	The address of the bridge contract to be used. Defaults to the default ZKsync bridge, either `L1EthBridge` or `L1Erc20Bridge` (optional).

Example

String L1_DAI = "0x5C221E77624690fff6dd741493D735a17716c26B";
 
TransactionReceipt tx = wallet.approveERC20(L1_DAI, BigInteger.valueOf(5)).join();

`balanceL1`

Returns the amount of the token the Wallet has on Ethereum.

BigInteger ethBalance = wallet.getBalance().sendAsync().join();

Inputs

Parameter	Type	Description
`token`	`String`	The address of the token. ETH by default (optional).

Example

String L1_DAI = "0x56E69Fa1BB0d1402c89E3A4E3417882DeA6B14Be"
String l2DAI = wallet.l2TokenAddress(L1_DAI);
 
BigInteger tokenBalance = wallet.getBalance(l2DAI).sendAsync().join();

Inputs

Parameter	Type	Description
`address`	`String`	The address of the wallet.
`token`	`String`	The address of the token. ETH by default.
`blockNumber`	`BlockNumber`	In which block a balance should be checked on. `committed`, i.e. the latest processed one is the default option.

Example

String L1_DAI = "0x56E69Fa1BB0d1402c89E3A4E3417882DeA6B14Be"
String l2DAI = wallet.l2TokenAddress(L1_DAI);
 
BigInteger tokenBalance = wallet.getBalance(signer.getAddress(), l2DAI, ZkBlockParameterName.COMMITTED).sendAsync().join();

`constructor`

Inputs

Parameter	Type	Description
`providerL1`	Web3j	Instance of Web3j class.
`providerL2`	ZkSync	A ZKsync node provider. Needed for interaction with ZKsync.
`credentials`	Credentials	An Ethereum node provider. Needed for interaction with L1.

Transfers the specified token from the associated account on the L1 network to the target account on the L2 network. The token can be either ETH or any ERC20 token. For ERC20 tokens, enough approved tokens must be associated with the specified L1 bridge (default one or the one defined in transaction.bridgeAddress). In this case, transaction.approveERC20 can be enabled to perform token approval. If there are already enough approved tokens for the L1 bridge, token approval will be skipped. To check the amount of approved tokens for a specific bridge, use the allowanceL1 method.

Inputs

Parameter	Type	Description
`transaction`	`DepositTransaction`	DepositTransaction class.

Example

Deposit ETH

BigInteger amount = new BigInteger("7000000000");
DepositTransaction transaction = new DepositTransaction(ZkSyncAddresses.ETH_ADDRESS, amount);
 
EthSendTransaction hash = testWallet.deposit(transaction).send();
// Wait for l1 receipt
TransactionReceipt l1Receipt = processorL1.waitForTransactionReceipt(hash.getTransactionHash());
// Get l2 hash from l1 receipt
String l2Hash = zksync.getL2HashFromPriorityOp(l1Receipt, zksync.zksMainContract().sendAsync().join().getResult());
// Wait for l2 receipt
TransactionReceipt l2Receipt = wallet.getTransactionReceiptProcessor().waitForTransactionReceipt(l2Hash);

Deposit ERC20 token

String L1_DAI = "0x56E69Fa1BB0d1402c89E3A4E3417882DeA6B14Be"
String l2DAI = testWallet.l2TokenAddress(L1_DAI);
 
DepositTransaction transaction = new DepositTransaction(L1_DAI, BigInteger.valueOf(5));
 
EthSendTransaction hash = testWallet.deposit(transaction).send();
// Wait for l1 receipt
TransactionReceipt l1Receipt = processorL1.waitForTransactionReceipt(hash.getTransactionHash());
// Get l2 hash from l1 receipt
String l2Hash = zksync.getL2HashFromPriorityOp(l1Receipt, zksync.zksMainContract().sendAsync().join().getResult());
// Wait for l2 receipt
TransactionReceipt l2Receipt = wallet.getTransactionReceiptProcessor().waitForTransactionReceipt(l2Hash);

`estimateAndSend`

Estimate and send the transaction to the network.

Inputs

Parameter	Type	Description
`transaction`	Transaction	Transaction request.
`nonce`	BigInteger	Nonce to use in the transaction.
`maxPriorityFeePerGas`	BigInteger	Max priority fee per gas to use in the transaction, default is 0.(optional)

Example

Transaction tx = Transaction.createEthCallTransaction("<FROM_ADDRESS>", "<TO_ADDRESS", "0x", BigInteger.valueOf(7_000_000_000L));
BigInteger nonce = wallet.getNonce().sendAsync().join();
 
EthSendTransaction result = wallet.estimateAndSend(tx, nonce).sendAsync().join();

`estimateGasDeposit`

Estimates the amount of gas required for a deposit transaction on L1 network. Gas of approving ERC20 token is not included in estimation.

Inputs

Parameter	Type	Description
`transaction`	`DepositTransaction`	DepositTransaction class.

Example

BigInteger amount = new BigInteger("7000000000");
DepositTransaction transaction = new DepositTransaction(ZkSyncAddresses.ETH_ADDRESS, amount);
BigInteger result = testWallet.estimateGasDeposit(transaction);

`estimateGasRequestExecute`

Estimates the amount of gas required for a request execute transaction.

Inputs

Parameter	Type	Description
`transaction`	`RequestExecuteTransaction`	RequestExecuteTransaction struct.

Example

RequestExecuteTransaction transaction = new RequestExecuteTransaction(null, zksync.zksMainContract().send().getResult(), Numeric.hexStringToByteArray("0x"), BigInteger.valueOf(7000000), null, null, null, null, null);
BigInteger baseGasLimit = estimateGasRequestExecute(transaction.toRequestExecute(mainContractAddress)).sendAsync().join().getAmountUsed();

`finalizeWithdraw`

Proves the inclusion of the L2 -> L1 withdrawal message.

Inputs

Name	Type	Description
`withdrawalHash`	`String`	Hash of the L2 transaction where the withdrawal was initiated.
`index`	`Int`	In case there were multiple withdrawals in one transaction, you may pass an index of the withdrawal you want to finalize. Defaults to 0.

Example

WithdrawTransaction transaction = wallet.finalizeWithdraw("<WITHDRAW_HASH>", 0).sendAsync().join();

`getAddress`

Returns the wallet address.

Example

String address = wallet.getAddress();

`getAllBalances`

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

Example

ZksAccountBalances allBalances = wallet.getAddress().join();

`getAllowanceL1`

Returns the amount of approved tokens for a specific L1 bridge.

Inputs

Parameter	Type	Description
`token`	`String`	The Ethereum address of the token.
`bridgeAddress`	`String`	The address of the bridge contract to be used. Defaults to the default ZKsync bridge, either `L1EthBridge` or `L1Erc20Bridge` (optional).

Example

String L1_DAI = "0x5C221E77624690fff6dd741493D735a17716c26B";
 
BigInteger allowanceL1 = wallet.getAllowanceL1(L1_DAI).join();

`getBalance`

Returns the amount of the token the Wallet has.

BigInteger ethBalance = wallet.getBalance().sendAsync().join();

Inputs

Parameter	Type	Description
`token`	`String`	The address of the token. ETH by default (optional).

Example

String L1_DAI = "0x56E69Fa1BB0d1402c89E3A4E3417882DeA6B14Be"
String l2DAI = wallet.l2TokenAddress(L1_DAI);
 
BigInteger tokenBalance = wallet.getBalance(l2DAI).sendAsync().join();

Inputs

Parameter	Type	Description
`address`	`String`	The address of the wallet.
`token`	`String`	The address of the token. ETH by default.
`blockNumber`	`BlockNumber`	In which block a balance should be checked on. `committed`, i.e. the latest processed one is the default option.

Example

String L1_DAI = "0x56E69Fa1BB0d1402c89E3A4E3417882DeA6B14Be"
String l2DAI = wallet.l2TokenAddress(L1_DAI);
 
BigInteger tokenBalance = wallet.getBalance(signer.getAddress(), l2DAI, ZkBlockParameterName.COMMITTED).sendAsync().join();

`getBaseCost`

Returns base cost for L2 transaction.

Inputs

Name	Type	Description
`gasLimit`	`BigInteger`	The `gasLimit` for the L2 contract call.
`gasPerPubdataByte`	`BigInteger`	The L2 gas price for each published L1 calldata byte (optional).
`gasPrice`	`BigInteger`	The L1 gas price of the L1 transaction that will send the request for an execute call (optional).

Example

BigInteger baseCost = wallet.getBaseCost(BigInteger.valueOf(100_000));

`getDeploymentNonce`

Returns account's deployment nonce number.

Example

BigInteger deploymentNonce = wallet.getDeploymentNonce().join()

`getDepositTransaction`

Returns populated deposit transaction.

Inputs

Parameter	Type	Description
`transaction`	`DepositTransaction`	DepositTransaction class.

Example

BigInteger amount = new BigInteger("7000000000");
DepositTransaction transaction = new DepositTransaction(ZkSyncAddresses.ETH_ADDRESS, amount);

`getFullRequiredDepositFee`

Retrieves the full needed ETH fee for the deposit. Returns the L1 fee and the L2 fee FullDepositFee.

Inputs

Parameter	Type	Description
`transaction`	`DepositTransaction`	DepositTransaction class.

Example

BigInteger amount = new BigInteger("7000000000");
DepositTransaction transaction = new DepositTransaction(ZkSyncAddresses.ETH_ADDRESS, amount);
BigInteger result = testWallet.getFullRequiredDepositFee(transaction);

`getL1BridgeContracts`

Returns L1 bridge contracts.

There is no separate Ether bridge contract, Main contract is used instead.

Example

L1BridgeContracts l1BridgeContracts = wallet.getL1BridgeContracts();

`getMainContract`

Returns Contract wrapper of the ZKsync smart contract.

Example

IZkSync mainContract = testWallet.getMainContract()

`getNonce`

Returns account's nonce number.

Inputs

Parameter	Type	Description
`at`	`DefaultBlockParameter`	In which block a balance should be checked on. `committed`, i.e. the latest processed one is the default option (optional).

Example

BigInteger nonce = wallet.getNonce().sendAsync().join();

`getRequestExecute`

Returns populated RequestExecuteTransaction.

Inputs

Parameter	Type	Description
`transaction`	`RequestExecuteTransaction`	RequestExecuteTransaction struct.

Example

RequestExecuteTransaction transaction = new RequestExecuteTransaction(null, zksync.zksMainContract().send().getResult(), Numeric.hexStringToByteArray("0x"), BigInteger.valueOf(7000000), null, null, null, null, null);
RequestExecuteTransaction result = testWallet.getRequestExecute(transaction);

`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
`l1Address`	`String`	The address of the token on L1.

Example

String L1_DAI = "0x56E69Fa1BB0d1402c89E3A4E3417882DeA6B14Be"
 
String l2Address = wallet.l2TokenAddress(L1_DAI).sendAsync().join();

`requestExecute`

Request execution of L2 transaction from L1.

Inputs

Parameter	Type	Description
`transaction`	`RequestExecuteTransaction`	RequestExecuteTransaction struct.

Example

RequestExecuteTransaction transaction = new RequestExecuteTransaction(null, zksync.zksMainContract().send().getResult(), Numeric.hexStringToByteArray("0x"), BigInteger.valueOf(7000000), null, null, null, null, null);
EthSendTransaction result = testWallet.requestExecute(transaction);
// Wait for l1 receipt
TransactionReceipt l1Receipt = processorL1.waitForTransactionReceipt(hash.getTransactionHash());
// Get l2 hash from l1 receipt
String l2Hash = zksync.getL2HashFromPriorityOp(l1Receipt, zksync.zksMainContract().sendAsync().join().getResult());
// Wait for l2 receipt
TransactionReceipt l2Receipt = wallet.getTransactionReceiptProcessor().waitForTransactionReceipt(l2Hash);

`transfer`

For convenience, the Wallet class has transfer method, which can transfer ETH or any ERC20 token within the same interface.

Inputs

Parameter	Type	Description
`transaction`	`TransferTransaction`	TransferTransaction class.

Examples

Transfer ETH.

TransferTransaction transaction = new TransferTransaction("<RECIPIENT_ADDRESS>", BigInteger(7_000_000_000L), signer.getAddress());
 
TransactionReceipt receipt = wallet.transfer(transaction).sendAsync().join();
 
wallet.getTransactionReceiptProcessor().waitForTransactionReceipt(receipt.getTransactionHash());

Transfer ETH using paymaster to facilitate fee payment with an ERC20 token.

PaymasterParams paymasterParams = new PaymasterParams(PAYMASTER, Numeric.hexStringToByteArray(FunctionEncoder.encode(Paymaster.encodeApprovalBased(TOKEN, BigInteger.ONE, new byte[] {}))));
TransferTransaction transaction = new TransferTransaction("<RECIPIENT_ADDRESS>", BigInteger(7_000_000_000L), signer.getAddress(), paymasterParams);
 
TransactionReceipt receipt = wallet.transfer(transaction).sendAsync().join();
 
wallet.getTransactionReceiptProcessor().waitForTransactionReceipt(receipt.getTransactionHash());

`withdraw`

Initiates the withdrawal process which withdraws ETH or any ERC20 token from the associated account on L2 network to the target account on L1 network.

Inputs

Parameter	Type	Description
`transaction`	`DepositTransaction`	DepositTransaction class.

Examples

Withdraw ETH.

BigInteger amount = new BigInteger("7000000000");
WithdrawTransaction transaction = new WithdrawTransaction(ZkSyncAddresses.ETH_ADDRESS, amount, testWallet.getAddress());
 
TransactionReceipt result = testWallet.withdraw(transaction).sendAsync().join();
 
TransactionReceipt receipt = testWallet.getTransactionReceiptProcessor().waitForTransactionReceipt(result.getTransactionHash());

Withdraw ETH using paymaster to facilitate fee payment with an ERC20 token.

BigInteger amount = new BigInteger("7000000000");
String token = "0x927488F48ffbc32112F1fF721759649A89721F8F"; // Crown token which can be minted for free
String paymaster = "0x13D0D8550769f59aa241a41897D4859c87f7Dd46"; // Paymaster for Crown token
 
PaymasterParams paymasterParams = new PaymasterParams(paymaster, Numeric.hexStringToByteArray(FunctionEncoder.encode(Paymaster.encodeApprovalBased(token, BigInteger.ONE, new byte[]
 {}))));
WithdrawTransaction transaction = new WithdrawTransaction(ZkSyncAddresses.ETH_ADDRESS, amount, paymasterParams);
 
TransactionReceipt result = testWallet.withdraw(transaction).sendAsync().join();
 
TransactionReceipt receipt = testWallet.getTransactionReceiptProcessor().waitForTransactionReceipt(result.getTransactionHash());

Withdraw ERC20.

BigInteger amount = BigInteger.valueOf(5);
String tokenL1 = "0x56E69Fa1BB0d1402c89E3A4E3417882DeA6B14Be"
String l2DAI = testWallet.l2TokenAddress(L1_DAI);
 
WithdrawTransaction transaction = new WithdrawTransaction(l2DAI, amount, testWallet.getAddress());
TransactionReceipt result = testWallet.withdraw(transaction).sendAsync().join();
TransactionReceipt receipt = testWallet.getTransactionReceiptProcessor().waitForTransactionReceipt(result.getTransactionHash());

Withdraw ERC20 using paymaster to facilitate fee payment with an ERC20 token.

BigInteger amount = BigInteger.valueOf(5);
String tokenL1 = "0x56E69Fa1BB0d1402c89E3A4E3417882DeA6B14Be"
String l2DAI = testWallet.l2TokenAddress(L1_DAI);
 
String token = "0x927488F48ffbc32112F1fF721759649A89721F8F"; // Crown token which can be minted for free
String paymaster = "0x13D0D8550769f59aa241a41897D4859c87f7Dd46"; // Paymaster for Crown token
 
PaymasterParams paymasterParams = new PaymasterParams(paymaster, Numeric.hexStringToByteArray(FunctionEncoder.encode(Paymaster.encodeApprovalBased(token, BigInteger.ONE, new byte[]
 {}))));
 
WithdrawTransaction transaction = new WithdrawTransaction(l2DAI, amount, testWallet.getAddress(), paymasterParams);
TransactionReceipt result = testWallet.withdraw(transaction).sendAsync().join();
TransactionReceipt receipt = testWallet.getTransactionReceiptProcessor().waitForTransactionReceipt(result.getTransactionHash());

Introduction

Manage accounts and sign transactions in the ZKsync2-java.

EthSigner

Overview of account functionalities in the zksync2-java