ZKsync Python SDK 钱包模块全面指南

ZKsync 是一个基于 ZK Rollup 技术的 Layer 2 扩展解决方案，旨在为以太坊带来更高的吞吐量和更低的交易成本。其 Python SDK 提供了丰富的功能，其中 Wallet 模块是开发者与 ZKsync 网络交互的核心工具之一。

本文将深入解析 Wallet 模块的各项功能，包括账户创建、余额查询、资产转移、跨链存取款等，并提供详细的代码示例，帮助开发者快速上手。

Wallet 模块概述

Wallet 模块为开发者提供了在 ZKsync 生态系统中集成、创建和管理钱包的账户功能。该模块的核心是 Wallet 对象，可以从 BaseAccount 创建而来。

创建 Wallet 对象

以下是创建 Wallet 对象的基本示例：

from eth_account import Account
from eth_account.signers.local import LocalAccount
from web3 import Web3
from zksync2.account.wallet import Wallet
from zksync2.module.module_builder import ZkSyncBuilder

if __name__ == "__main__":
    ZKSYNC_PROVIDER = "https://sepolia.era.zksync.dev"
    ETH_PROVIDER = "https://rpc.ankr.com/eth_sepolia"
    
    zk_web3 = ZkSyncBuilder.build(ZKSYNC_PROVIDER)
    eth_web3 = Web3(Web3.HTTPProvider(ETH_PROVIDER))
    
    account: LocalAccount = Account.from_key(private_key)
    wallet = Wallet(zk_web3, eth_web3, account)

开发建议：在开发和测试环境中，建议使用 burner wallets（临时钱包），避免使用真实的私钥以防止安全风险。

核心功能详解

1. 主合约访问

通过 mainContract 属性，可以获取 ZKsync 智能合约的 Contract 包装器：

contract = wallet.main_contract
print(contract.address)

2. 桥接合约获取

ZKsync 提供了多种方法获取 Layer 1 和 Layer 2 的桥接合约：

获取 L1 桥接合约：

l1_bridge_contracts = wallet.get_l1_bridge_contracts()

获取 L2 桥接合约：

l2_bridge_contracts = await wallet.get_l2_bridge_contracts()

需要注意的是，ZKsync 没有单独的 Ether 桥接合约，而是使用主合约来代替。

3. 余额查询

Wallet 模块提供了多种余额查询方法，满足不同场景的需求：

查询 L2 余额：

balance = wallet.get_balance()
print(balance)

查询 L1 余额：

balance = wallet.get_l1_balance()
print(balance)

查询所有余额：

balance = wallet.get_all_balances()
print(balance)

4. 资产转移

transfer 方法提供了便捷的资产转移功能，支持 ETH 和任何 ERC20 代币：

转移 ETH：

from zksync2.core.types import TransferTransaction, ADDRESS_DEFAULT

amount = 7_000_000_000
tx_hash = wallet.transfer(TransferTransaction(
    to=Web3.to_checksum_address("TO_ADDRESS"),
    token_address=ADDRESS_DEFAULT,
    amount=amount
))

使用 Paymaster 支付手续费：

from zksync2.core.types import PaymasterParams
from zksync2.manage_contracts.paymaster_utils import PaymasterFlowEncoder

paymaster_address = zk_web3.to_checksum_address("0x13D0D8550769f59aa241a41897D4859c87f7Dd46")
token_address = zk_web3.to_checksum_address("0x927488F48ffbc32112F1fF721759649A89721F8F")

paymaster_params = PaymasterParams(
    paymaster=paymaster_address,
    paymaster_input=eth_web3.to_bytes(
        hexstr=PaymasterFlowEncoder(eth_web3).encode_approval_based(
            token_address, 1, b""
        )
    )
)

tx_hash = wallet.transfer(
    TransferTransaction(
        to=Web3.to_checksum_address("TO_ADDRESS"),
        amount=amount,
        paymaster_params=paymaster_params
    )
)

跨链操作

存款（Deposit）

存款操作允许用户将资产从 Layer 1 转移到 Layer 2：

ETH 存款：

from zksync2.core.types import DepositTransaction
from zksync2.core.utils import LEGACY_ETH_ADDRESS

tx_hash = wallet.deposit(
    DepositTransaction(token=LEGACY_ETH_ADDRESS, amount=7_000_000)
)

ERC20 代币存款：

l1_address = HexStr("0x56E69Fa1BB0d1402c89E3A4E3417882DeA6B14Be")
l1_hash_erc20 = wallet.deposit(DepositTransaction(
    Web3.to_checksum_address(l1_address),
    5,
    account.address,
    approve_erc20=True
))

取款（Withdrawal）

取款操作允许用户将资产从 Layer 2 撤回至 Layer 1：

from zksync2.core.types import WithdrawTransaction, ADDRESS_DEFAULT

withdraw_tx_hash = wallet.withdraw(
    WithdrawTransaction(
        token=ADDRESS_DEFAULT, 
        amount=Web3.to_wei(1, "ether")
    )
)

最终化取款

取款操作需要最终化才能在 L1 上完成：

withdraw_tx_hash = wallet.finalize_withdrawal("L2_TX_HASH")

高级功能

手续费估算

ZKsync 提供了多种手续费估算方法，帮助开发者预估操作成本：

估算存款手续费：

full_deposit_fee_eth = wallet.get_full_required_deposit_fee(
    DepositTransaction(token=ADDRESS_DEFAULT, to=wallet.address)
)

估算请求执行手续费：

estimated_gas = wallet.estimate_gas_request_execute(RequestExecuteCallMsg(
    contract_address=Web3.to_checksum_address(zk_web3.zksync.main_contract_address),
    call_data=HexStr("0x"),
    l2_value=amount,
    l2_gas_limit=900_000
))

代币批准操作

在进行存款等操作前，可能需要先批准代币：

l1_address = HexStr("0x56E69Fa1BB0d1402c89E3A4E3417882DeA6B14Be")
result = wallet.approve_erc20(HexStr(l1_address), 10000000)

常见问题

如何选择合适的网络提供商？

对于测试环境，建议使用 Sepolia 测试网：

ZKSYNC_PROVIDER = "https://sepolia.era.zksync.dev"
ETH_PROVIDER = "https://rpc.ankr.com/eth_sepolia"

生产环境需要使用主网提供商，确保交易的安全性和可靠性。

如何处理交易失败的情况？

如果存款交易在 L2 上失败，可以使用 claim_failed_deposit 方法取回资金：

claim_failed_deposit_handle = wallet.claim_failed_deposit(HexStr("DEPOSIT_HASH"))

如何查询交易状态？

可以使用以下方法查询优先级操作的状态：

confirmation = wallet.get_priority_op_confirmation("TX_HASH")
print(confirmation)

什么是 Paymaster？如何使用？

Paymaster 是 ZKsync 的一个特色功能，允许用户使用 ERC20 代币支付交易手续费，而不是必须使用 ETH。这在用户体验和资金效率方面提供了很大便利。

使用 Paymaster 需要在交易中设置 paymaster_params 参数，指定 Paymaster 合约地址和相应的输入数据。

如何确保交易的安全性？

始终在测试网充分测试后再部署到主网
使用环境变量管理私钥，避免硬编码
定期更新 SDK 版本以获取安全补丁和新功能
对于大额交易，建议先进行小额测试交易

👉 查看实时开发工具和资源

通过本指南，您应该对 ZKsync Python SDK 的 Wallet 模块有了全面的了解。无论是基本的账户管理、资产转移，还是高级的跨链操作，该模块都提供了简洁而强大的 API，帮助开发者快速构建基于 ZKsync 的应用程序。