wagmi Tempozone.encryptedDeposit实战指南向 Zone 加密存入 TIP-20 代币【免费下载链接】wagmiReactive primitives for Ethereum apps项目地址: https://gitcode.com/GitHub_Trending/wa/wagmi导读本文围绕 wagmi 的 Tempo 扩展模块中zone.encryptedDeposit这一核心 action 展开讲解如何以「加密的接收方recipient与备注memo」向指定 Zone 的 Portal 合约存入 TIP-20 代币。你将掌握zone.encryptedDeposit异步返回交易哈希与zone.encryptedDepositSync同步等待上链后返回回执两种调用方式、完整参数语义、底层加密原理与交易构造细节并了解其在 React 中的 Hook 用法可直接用于 Tempo 网络的隐私存款类业务。一、功能概览什么是zone.encryptedDepositzone.encryptedDeposit是 wagmi Tempo 命名空间下针对「父链parent Tempo chain向 Zone 存入资产」提供的 action。与普通的zone.deposit不同它在发送存款交易之前会在客户端本地将目标接收方地址与 memo 备注加密再通过 Zone Portal 合约的depositEncrypted函数提交密文从而让存款内容对链上观察者不可见只有持有对应解密能力的 sequencer 才能还原出真实的接收方与备注。文档原意见 zone.encryptedDeposit.md明确指出需要viem 2.48.0才能使用 Zone actions 与 hooks*Sync变体zone.encryptedDepositSync会等待交易被打包进区块后再返回返回的是交易回执非 sync 的zone.encryptedDeposit会立即返回交易哈希适合对性能敏感、希望自行管理「等待上链」流程的场景。从源码 zone.ts 的 JSDoc 可以看到同一描述Deposits tokens into a zone on the parent Tempo chain with an encrypted recipient and memo.返回值为交易哈希而encryptedDepositSynczone.ts则是「waits for the transaction to be included on a block before returning a response」返回{ receipt }。二、快速上手同步存入encryptedDepositSync文档给出的最简用法如下使用*Sync变体直接拿到回执并打印交易哈希import { Actions } from wagmi/tempo import { parseUnits } from viem import { config } from ./config const result await Actions.zone.encryptedDepositSync(config, { amount: parseUnits(10, 6), token: 0x20c0000000000000000000000000000000000001, zoneId: 7, }) console.log(Transaction hash:, result.receipt.transactionHash)其中config是标准的 wagmi 配置需要包含 Tempo 网络与tempoWallet连接器参考 site/snippets/react/config-tempo.tsimport { createConfig, http } from wagmi import { tempo } from wagmi/chains import { tempoWallet } from wagmi/tempo export const config createConfig({ connectors: [tempoWallet()], chains: [tempo], multiInjectedProviderDiscovery: false, transports: { [tempo.id]: http(), }, })要点说明amount使用parseUnits(10, 6)构造即 10 个 6 位小数的代币单位符合 TIP-20 代币常见精度token传入一个示例 TIP-20 代币地址若使用代币 ID则传bigint见下文参数表zoneId: 7为目标 Zone 的 IDPortal 地址会由框架根据该 ID 解析。三、异步用法自行等待上链当你希望「发出交易后立即继续执行」可以采用非 sync 版本zone.encryptedDeposit它只返回交易哈希之后再用waitForTransactionReceipt手动等待交易被包含进区块import { Actions } from wagmi/tempo import { parseUnits } from viem import { waitForTransactionReceipt } from wagmi/actions const hash await Actions.zone.encryptedDeposit(config, { amount: parseUnits(10, 6), token: 0x20c0000000000000000000000000000000000001, zoneId: 7, }) const receipt await waitForTransactionReceipt(config, { hash }) console.log(receipt.status)两种用法的取舍非常清晰Sync 变体开箱即用、语义直观但会阻塞到交易上链非 sync 变体让你可以把「发送」与「确认」解耦适合批量提交、并行等待或对接自定义监听逻辑的性能敏感场景。四、返回值zone.encryptedDepositSync的返回类型来自 zone.ts 的return { receipt }如下type ReturnType { /** Transaction receipt */ receipt: TransactionReceipt }即返回交易回执对象可通过receipt.transactionHash拿到交易哈希、通过receipt.status判断交易是否成功zone.encryptedDeposit则直接返回PromiseHash交易哈希。测试用例 zone.test.ts 中对encryptedDepositSync断言result.receipt.status success对encryptedDeposit断言hash已定义印证了上述两种返回形态。五、参数详解amount类型bigint含义要存入的代币数量。建议使用parseUnits按代币精度换算避免浮点精度问题。token类型Address | bigint含义要存入的 TIP-20 代币的地址或 ID。源码中通过TokenId.toAddress(token)统一将代币 ID 归一化为地址zone.ts所以两种形式皆可。zoneId类型number含义目标 Zone 的 ID。框架通过resolvePortal(config, resolvedChainId, zoneId)解析出该 Zone 对应的 Portal 合约地址zone.ts。memo可选类型Hex含义可选备注会与接收方地址一起被加密。若未传入源码默认memo zeroHashzone.ts。recipient可选类型Address含义目标 Zone 内的接收方地址默认在加密前回退为当前已连接账户的地址recipient accountAddress见 zone.ts。加密后该地址在链上不可见起到隐私保护作用。通用交易参数可选以下参数由shared/tempo-write-parameters.mdtempo-write-parameters.md统一提供适用于所有 Tempo 写入类 action参数类型说明accountAccount \| Address发送交易使用的账户默认使用已连接的 wagmi 账户feeTokenAddress \| bigint交易手续费代币可为 TIP-20 代币地址或 IDfeePayerAccount \| true手续费支付方可为 viem Account或设为true表示使用 Fee Payer Servicegasbigint交易的 gas 上限maxFeePerGasbigint交易的最大每单位 gas 费用maxPriorityFeePerGasbigint交易的最大优先费noncenumber交易 noncenonceKeyexpiring \| bigint交易 nonce keyvalidBeforenumber交易必须在此 Unix 时间戳之前被打包validAfternumber交易可被打包的时间点Unix 时间戳之后throwOnReceiptRevertboolean默认true仅对*Syncaction 生效若回执显示 revert 则抛出错误另外参数类型还包含chainId与connector见encryptedDeposit.Parameters的定义zone.tschainId用于显式指定父链 IDconnector用于指定使用的连接器测试中即通过chainId: parentChain.id显式指定zone.test.ts。六、底层原理加密与交易是如何构造的这一节结合 zone.ts 源码梳理encryptedDeposit/encryptedDepositSync内部的完整调用链帮助理解「加密存款」究竟做了什么。6.1 Portal 地址与加密密钥的解析resolvePortal(config, chainId, zoneId)zone.ts按以下优先级解析 Portal若链配置中chain.contracts.zonePortal是字符串则直接作为 Portal 地址若zonePortal是按zoneId索引的对象则取出对应 Zone 的 Portal 配置可能附带encryptionKeyCount与sequencerEncryptionKey用于跳过链上读取否则回退到框架内置的portalAddresses映射表全部失败则抛出No portal address configured for zone ...错误。得到 Portal 地址后若链配置未提供加密密钥框架会通过viem_readContract调用 Portal 的sequencerEncryptionKey与encryptionKeyCount两个 view 函数获取 sequencer 的 secp256k1 公钥{ x, yParity }与当前加密密钥计数zone.ts。若keyIndex 0n会抛出No sequencer encryption key configured.表示该 Zone 尚未配置加密密钥无法执行加密存款。6.2 ECIES 风格的本地加密encryptDepositPayload(publicKey, recipient, memo)zone.ts在客户端完成 ECIES 风格的加密流程用 sequencer 公钥与临时生成的 secp256k1 密钥对通过Secp256k1.getSharedSecret计算共享密钥以 HKDF-SHA-256盐为 12 字节零向量、info 为ecies-aes-key派生 256 位 AES 密钥生成 12 字节随机 nonce将recipientaddress与memobytes32用 ABI 编码为明文encodeAbiParameters用 AES-GCMtagLength: 128加密输出ciphertext、tag以及临时公钥的ephemeralPubkeyX、ephemeralPubkeyYParity、nonce。这些字段最终作为depositEncrypted的密文载荷提交上链只有持有对应私钥的 sequencer 才能解密还原接收方与备注。6.3 两段式交易approve depositEncrypted无论 sync 还是非 sync 版本最终都会构造一条包含两个 call 的交易zone.ts第一个 call 调用 TIP-20 代币的approve(portalAddress, amount)授权 Portal 划转代币第二个 call 调用 Zone Portal 的depositEncrypted(tokenAddress, amount, keyIndex - 1n, encrypted, bouncebackRecipient)完成加密存款。其中keyIndex - 1n指向本次加密使用的密钥索引bouncebackRecipient默认等于发送方账户地址用于失败时的退回地址。整个流程可通过viem_sendTransaction非 sync或viem_sendTransactionSyncsync配合throwOnReceiptRevert发送。从测试用例看还支持「预生成好的加密载荷」直接传入getPreparedEncryptedDeposit()返回含encrypted字段的参数源码中if (encrypted in rest_)分支会直接把预加密载荷透传给 viem 的 Tempo actionzone.ts测试断言其返回回执状态为successzone.test.ts。这为「离线/预加密再广播」的高级流程保留了扩展点。七、React 中使用 Hook 版本除了命令式 actionReact 侧还提供了对应的 mutation hooks见 packages/react/src/tempo/hooks/zone.tsimport { Hooks } from wagmi/tempo function App() { const { mutate, isPending } Hooks.zone.useEncryptedDeposit() return ( button onClick{() mutate({ amount: 1_000_000n, token: 0x20c0000000000000000000000000000000000001, zoneId: 7, }) } disabled{isPending} Encrypted Deposit /button ) }useEncryptedDeposit内部包装Actions.zone.encryptedDepositmutation key 为[encryptedDeposit]返回{ hash }useEncryptedDepositSynczone.ts包装Actions.zone.encryptedDepositSyncmutation key 为[encryptedDepositSync]返回{ receipt }。两个 Hook 均支持通过mutation配置项透传 TanStack Query 的UseMutationParameters可自定义onSuccess、onError、onSettled等回调参数类型与 action 一致。若使用同步 HookisPending会持续到交易确认上链为止。八、注意事项与边界版本约束zone.encryptedDeposit及其 hooks 需要viem 2.48.0请确保项目依赖满足该版本先连接后调用action 内部通过getConnectorClient获取已连接客户端并断言存在账户account_缺失时抛出account is required.因此调用前需先完成钱包连接测试中也先connect(config, { connector })见 zone.test.tschainId必须可解析若未显式传入chainId会回退到client.chain?.id两者皆无时抛出chainId is required.加密密钥缺失时无法使用若 Zone Portal 未配置 sequencer 加密密钥encryptionKeyCount 0n加密存款将报错此时应考虑普通zone.deposit回执回滚使用*Sync变体时默认throwOnReceiptRevert true交易回滚会直接抛错如需自行处理可显式传throwOnReceiptRevert: false。相关文档与源码zone.encryptedDeposit 文档通用 Tempo 写入参数核心实现zone.tsReact Hook 实现hooks/zone.ts测试用例zone.test.tsTempo 配置示例【免费下载链接】wagmiReactive primitives for Ethereum apps项目地址: https://gitcode.com/GitHub_Trending/wa/wagmi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考