用途
本技能用于将 1AM 钱包集成到 Midnight Network 上的前端 dApp 中，实现免 dust 费用的合约部署与交易流程。1AM 钱包负责处理所有 ZK 证明与 dust 费用赞助，用户无需支付 gas。技能同时支持 1AM 与 Lace 钱包。
该技能是通用模板：需要将代码中的 YourContract / yourCircuit / your-contract 等占位符替换为实际的合约名称与电路 ID。
主要能力
- 检测并连接 1AM 浏览器扩展（window.midnight['1am']）或 Lace 钱包（window.midnight.mnLace）。
- 创建连接会话（createConnectedSession），并行获取配置、网络 ID 与地址。
- 提供补丁版公共数据提供者（createPatchedPublicDataProvider），修复 preview 与 preprod 索引器在 latest-state 查询中 offset: null 的 GraphQL 问题。
- 提供内存版私密状态提供者（createPrivateStateProvider）。
- 提供十六进制转换辅助函数（toHex / fromHex）与 coin public key 辅助函数。
- 提供 React Context、useWallet Hook 与 WalletConnect UI 组件示例。
使用方式
依赖安装
已知可协同工作的精确版本：
npm install \
@midnight-ntwrk/compact-runtime@^0.15.0 \
@midnight-ntwrk/ledger@^4.0.0 \
@midnight-ntwrk/ledger-v8@^8.0.3 \
@midnight-ntwrk/midnight-js-contracts@^4.0.4 \
@midnight-ntwrk/midnight-js-fetch-zk-config-provider@^4.0.4 \
@midnight-ntwrk/midnight-js-indexer-public-data-provider@^4.0.4 \
@midnight-ntwrk/midnight-js-network-id@^4.0.4 \
@midnight-ntwrk/midnight-js-types@^4.0.4 \
@midnight-ntwrk/wallet-sdk-address-format@^3.1.0
Vite 需要以下插件以支持 WASM 与顶层 await（Compact SDK 两者都使用）：
npm install -D vite-plugin-wasm vite-plugin-top-level-await
Next.js 需要 webpack 配置。
建议文件布局
- src/lib/midnight.ts → 钱包会话、提供者接线、索引器补丁
- src/lib/encryption.ts → 可选的基于钱包签名的载荷加密
- src/hooks/useContract.ts → 应用逻辑与状态编排
- src/contexts/WalletContext.tsx → 钱包连接状态
共享参考：references/midnight-session.md、references/gotchas.md、references/versions.json
钱包检测与连接
扩展是异步注入的，必须轮询检测，不能假设立即可用。检测函数会以 100ms 间隔最多尝试 50 次。连接时调用 wallet.connect('preprod')，网络可选 'preview' | 'preprod' | 'mainnet'。
React 侧提供 WalletProvider 与 useWallet Hook，包含 address、isConnected、walletType、isConnecting、walletStatus、session、connect、disconnect 等状态与方法。WalletConnect UI 组件需渲染四种状态：checking、not-found、disconnected（连接 CTA）、connected（地址 + 断开）。
会话创建
createConnectedSession 并行获取配置、非屏蔽地址与屏蔽地址，调用 setNetworkId，创建 FetchZkConfigProvider（ZK 资产从 /contract/your-contract 提供），获取 provingProvider，并构建自定义 proofProvider。注意：不要使用 @midnight-ntwrk/midnight-js-types 的 createProofProvider()，应直接调用 unprovenTx.prove()。
walletProvider 提供 getCoinPublicKey、getEncryptionPublicKey 与 balanceTx；midnightProvider 提供 submitTx。
索引器补丁
preview 与 preprod 索引器在 latest-state 查询中存在 offset: null 的 GraphQL 问题。默认 SDK 的 queryContractState() 不带 config 块会触发该问题。必须用 createPatchedPublicDataProvider 包装 indexerPublicDataProvider，否则这些网络上的状态读取会失败。
私密状态提供者
内存版私密状态提供者适用于大多数 dApp。私密状态不会跨页面刷新持久化，这是最小参考实现的有意设计。生产环境持久化需替换为 localStorage 或加密服务器存储。
适用场景
- 在 Midnight Network 上构建前端 dApp 并需要集成 1AM 或 Lace 钱包。
- 需要免 dust 费用、由钱包赞助 gas 的交易流程。
- 需要处理 preview / preprod 索引器状态读取问题的项目。
限制
- 私密状态默认不持久化，页面刷新后丢失。
- 索引器补丁针对 preview 与 preprod 网络的已知 GraphQL 问题。
- 代码中的合约名称与电路 ID 占位符需替换为实际值。
- 关于收费、价格、平台支持范围等更多信息暂未提供。