@masterpeach/market-sdk 0.2.0-beta.20260930.1

package/docs/frontend.md

@@ -0,0 +1,153 @@
+# 前端接入指南
+
+Market SDK 面向 Arc（5042）和 BSC（56），负责市场读取、LP 仓位、存取流动性和手续费。使用前端已有的 viem publicClient / walletClient；不绑定 React、钱包连接框架或 UI 组件，也不会自动轮询。用户买卖的路由与执行属于 Swap SDK，测试脚本里的 Router 不作为前端生产交易入口。
+
+## 文档导航
+
+| 前端需求 | 文档 |
+| --- | --- |
+| 池子列表、字段、分页和详情补充 | [池子列表](pools.md) |
+| 我的仓位、收益和部分/全部提取 | [仓位](positions.md) |
+| 授权、存入、滑点和原生币 | [流动性接口](liquidity.md) |
+| 净收益、份额与代领 | [收益与权限](earnings.md) |
+| 价格和活动流动性读取 | [池状态](pool-state.md) |
+| 管理员/运营参数 | [管理接口](management.md) |
+| 最新合约与测试池 | [最新合约对接](latest-contract.md) |
+
+## 安装与双链配置
+
+包版本以 `package.json` 为准；本次仅准备临时发布产物，尚未执行 npm 发布。同仓库消费使用 `@masterpeach/market-sdk: workspace:*` 和仓库 viem catalog；独立前端先安装本地打包产物：
+
+```sh
+# 在 SDK 仓库执行
+pnpm --filter @masterpeach/market-sdk build
+pnpm -C packages/market pack
+
+# 在前端项目执行；替换为实际打包文件路径
+pnpm add /path/to/masterpeach-market-sdk-0.2.0-beta.20260930.1.tgz 'viem@^2.45.0'
+```
+
+公开入口为根、`/abi`、`/core`，不要导入 src 内部路径。当前 peer 范围为 viem `>=2.45.0 <3`。已验证 Bundler TypeScript 5.7.3；NodeNext 消费使用 TypeScript 5.9+，详见包 README。
+
+| 配置 | Arc | BSC |
+| --- | --- | --- |
+| chainId | 5042 | 56 |
+| 原生 gas 币 | USDC，18 位 | BNB，18 位 |
+| 文档测试池 | tBTC/tUSDC，8/6 位 | tBNB/tUSDT、tQQQ/tUSDT，均 18/18 位 |
+| 测试币形式 | 均为 ERC-20 | 均为 ERC-20；tBNB 不是原生 BNB |
+
+为两条链分别维护 `MarketChainConfig`，由用户选中的链选择配置和 RPC，不共用合约地址。配置包含：
+
+- `chainId`、`confirmations`（至少 1）。
+- `deployment.chainId`、`deploymentId`、PoolManager、Registry、authority，按需提供 Reader 和 poolStateReader。
+- 每个合约的审核地址与 runtimeCodeHash；每 Hook 的 kind、implementation、独立 ClaimFeePolicy，RwaRamp 额外提供自己的 Calendar。
+- 每 Hook 的 `liquidity / nativeLiquidity / claimOperator / management` 能力状态；写操作要求相关能力经过独立验收。不能因为 verifyDeployment 成功就自动将状态改为 verified。
+
+SDK 不提供可直接开启主网写操作的可信内置配置。验收报告的 `observedChain` 供复现读取，不是生产信任预设；完整部署配置由接入方审核后提供。getPoolState、LP 预览和收益估算需要显式状态读取配置，见[池状态](pool-state.md)。
+
+SDK 核心仅使用注入的 publicClient。仓库 Arc 只读脚本默认 RPC 仍为 `https://rpc.arc-scan.org`；双链验收时显式覆盖合约文档 Blockdaemon 节点。前端应注入可用的对应链节点并展示 RPC 失败，不自动跨链或默默换节点。
+
+## 客户端生命周期
+
+```ts
+import { createMarketClient, type MarketChainConfig } from "@masterpeach/market-sdk";
+import type { PublicClient, WalletClient } from "viem";
+
+export async function initializeMarket(
+  chain: MarketChainConfig,
+  publicClient: PublicClient,
+  walletClient?: WalletClient,
+) {
+  const client = createMarketClient({ chain, publicClient, walletClient });
+  await client.verifyDeployment();
+  return client;
+}
+```
+
+构造实例本身不发请求；示例主动核验代码和绑定。未连接钱包可浏览市场和指定 owner 的仓位，准备/发送交易才需要钱包。核验失败时展示配置/网络错误，不能继续把旧链数据当新链数据。
+
+React 等框架中稳定保留实例，不要每次渲染都重新创建。切链、切钱包或更换部署后创建对应实例，丢弃旧 quote/prepared；已广播交易保留原实例等待回执，或者使用原链 publicClient 查询保存的 hash。不能把旧 prepared 或陌生 hash 交给新实例。
+
+查询缓存至少包含 chainId、deploymentId 和业务键（poolId，或 hook/rangeId/owner）。新账户不要复用旧 owner 的仓位缓存。批量查询限制并发，只在可见页面和必要状态变化时刷新；SDK 不会自动帮前端管理缓存。
+
+## 添加流动性：金额到预览
+
+输入使用字符串金额，通过 `parseUnits` 和真实 decimals 转成 bigint。PoolKey 的 currency0/1 顺序不一定等于界面的 base/quote，先映射币种再计算；ticks 必须与 key.tickSpacing 对齐。
+
+```ts
+import { getMarketLiquidityForAmounts, type MarketClient, type MarketPoolKey } from "@masterpeach/market-sdk";
+import type { Address } from "viem";
+
+export async function previewAddition(
+  client: MarketClient,
+  params: {
+    key: MarketPoolKey; owner: Address; tickLower: number; tickUpper: number;
+    sqrtPriceX96: bigint; amount0: bigint; amount1: bigint;
+    slippageBps: number; deadline: bigint;
+  },
+) {
+  const liquidity = getMarketLiquidityForAmounts(params);
+  if (liquidity === 0n) throw new Error("Amounts are too small for this range");
+  const quote = await client.previewDeposit({
+    key: params.key, tickLower: params.tickLower, tickUpper: params.tickUpper,
+    liquidity, slippageBps: params.slippageBps, deadline: params.deadline,
+  });
+  const spend = await client.getSpendStatus({
+    key: params.key, owner: params.owner,
+    amount0: quote.data.limit0, amount1: quote.data.limit1,
+    ...quote.block,
+  });
+  return { quote, spend };
+}
+```
+
+params.sqrtPriceX96 来自该池的 `getPoolState().data.sqrtPriceX96`；deadline 使用最新区块 timestamp 加用户接受的有效秒数。SDK 会根据实际预览区块重新计算本金。数学 helper 的 amount0/1 是计算预算，**叠加滑点后的 limit0/1 可能超过输入金额**；若输入代表硬预算，前端必须检查并降低 liquidity 后重算，不能默认把超额授权给 Hook。
+
+展示 `quote.data.amount0/1`（估计本金）、`limit0/1`（最大支出）、deadline 及余额。对 `spend.data.tokens`：
+
+1. `sufficientBalance=false` 时提示余额不足。
+2. `kind="erc20" && needsApproval` 时调用 `prepareApproval({ key, currency: 0或1, amount: token.requiredAmount })`；授权金额为完整所需额度，不是差额。每笔经用户确认发送并等成功回执。需要先清零的 token 分两笔处理。
+3. 授权结束后重新预览和检查余额/allowance，再 `prepareDeposit(freshQuote)`，展示新金额并由用户确认发送。
+4. 原生币不 approve，allowance 为 null；RampETH 原生池另需 `nativeLiquidity="verified"`，余额覆盖本金和 gas。三组文档测试池均走 ERC-20 路径。
+
+完整接口限制见[流动性接口](liquidity.md)；不要将预览序列化再恢复后传给 prepare，SDK 要求当前实例产生的原始对象。
+
+## 交易发送与界面状态
+
+以下函数会请求钱包发送交易，仅绑定用户确认事件调用，不放在初始化或自动 effect 中：
+
+```ts
+import type { MarketClient, MarketPreparedTransaction } from "@masterpeach/market-sdk";
+import type { Hex } from "viem";
+
+export async function submitConfirmedAction(
+  client: MarketClient,
+  prepared: MarketPreparedTransaction,
+  savePendingHash: (hash: Hex) => void,
+) {
+  const hash = await client.send(prepared);
+  savePendingHash(hash);
+  const result = await client.waitForTransaction(hash);
+  if (result.status !== "confirmed") throw new Error("Transaction reverted");
+  // repriced 替换时以 result.hash / receipt 为最终依据。
+  return result;
+}
+```
+
+| 状态 | 页面行为 |
+| --- | --- |
+| 未连接钱包 / 钱包链错误 | 保留只读浏览，交易前提示连接或切链 |
+| 查询/预览中 | 显示加载态，金额未就绪不允许确认 |
+| 待签名 / 已发送等待回执 | 禁止重复提交；取得 hash 后立即保存并展示进度 |
+| 已确认 | 刷新钱包余额、仓位、收益和授权；根据实际回执与事件显示结果 |
+| 用户拒签 / 模拟回滚 | 显示原因，重新准备后允许重试 |
+| 超时 / 连接中断 | 保留 hash，先查询或继续等待；不盲目重发本金交易 |
+| 数据为空 | 分清没有候选仓位、没有份额、历史 owed 与 RPC 失败 |
+
+参数错误为 `InvalidMarketConfigError`；链/代码/绑定不匹配为 `MarketDeploymentVerificationError`；读取错误 `MarketReadError` 保留 cause；交易错误 `MarketTransactionError` 携带 stage；替换或取消为 `MarketTransactionReplacedError`。合约错误应保留可诊断信息，不能把所有失败都显示为“余额不足”。
+
+领取成功可能没有支付事件，不能把“没有 FeesClaimed”一概当失败。单独 claim 的准备有效期只限制发送时机，并不是合约链上 deadline。所有金额保持 bigint，到展示时用对应 decimals 格式化；JSON 传输显式编码为十进制字符串并按字段恢复，避免 Number 精度损失。
+
+## 验证范围
+
+Arc tBTC/tUSDC 与 BSC tBNB/tUSDT、tQQQ/tUSDT 已通过线上只读和本地 fork 的存入、swap 产生手续费、领取、退出及余额对账。尚未进行前端钱包 UI 端到端验收或主网真实资金广播；观察配置未自动开放生产写能力。双链验收只使用 ERC-20 测试池，原生路径另有本地 EVM 验证。前端仍需测试连接/切链/拒签/重复点击/刷新恢复等交互。

package/docs/latest-contract.md

@@ -0,0 +1,38 @@
+# 最新合约接入：cf16bd9
+
+基线 `cf16bd9376c12ea50de04658b279176d8d56e4f5`。相对 `839c68e`，原有八份 ABI 和生产实现未变化，主要新增 BSC 部署及三组主网上的无价值测试 ERC-20 池。现有读取、LP 与管理 action 保持兼容。
+
+```ts
+import { marketTestPools, createMarketClient } from "@masterpeach/market-sdk";
+
+// publicClient 和 chain 为调用方提供的 RPC 与审核后的 MarketChainConfig。
+const client = createMarketClient({ publicClient, chain });
+const testPool = marketTestPools.find(
+  (pool) => pool.chainId === chain.chainId && pool.name === "tBTC/tUSDC",
+);
+if (!testPool) throw new Error("Requested test market is not recorded on this chain");
+const verified = await client.verifyDeployment();
+const block = { blockNumber: verified.blockNumber, blockHash: verified.blockHash };
+const pool = await client.getPool(testPool.poolId, block);
+const fees = await client.getCurrentFees(testPool.poolId, block);
+```
+
+| 链 | 测试市场 | base / quote 精度 | 实现 |
+| --- | --- | --- | --- |
+| Arc 5042 | tBTC / tUSDC | 8 / 6 | Ramp |
+| BSC 56 | tBNB / tUSDT | 18 / 18 | Ramp |
+| BSC 56 | tQQQ / tUSDT | 18 / 18 | RwaRamp |
+
+目录来源为该提交的 `docs/test-pools/{arc,bsc}.json`，`source` 保留提交、文件、历史核验区块。目录不是实时状态或部署能力证明，也不自动合并进 Registry 结果。共用 Registry 可以包含真实与测试资产；列表未收录的池属于未知分类，不能据此推断有真实价值。
+
+`tBNB` 是 ERC-20：授权给对应 Ramp，deposit value=0。真实 BSC BNB 池才使用 currency0=零地址及 RampETH。Arc 池内 tUSDC 是 6 位 ERC-20，gas 使用的原生 USDC 是另一种表示。RWA CLOSED 仅影响费率，不代表禁止交易。
+
+每个 Hook 必须配置自己的 `claimFeePolicy` 和审核后的 runtimeCodeHash；RwaRamp 另需自己的 `calendar`。不能把三个 BSC Hook 的 Policy 地址共用，也不能从某次 RPC 读取代码后自动把它认定为可信预期。目录没有这类信任配置，所有写入仍由已有 capability 和模拟流程控制。
+
+只读示例可精确指定池（Arc 默认 RPC 仍为 Launchpad 所用节点）：
+
+```sh
+node examples/consumer/scripts/read-market.mjs reviewed-chain.json https://rpc.arc-scan.org 0x1a325fe4671d6584778464cbe5ea68b111c2a72718f128a9427717298e85e2cd
+```
+
+`reviewed-chain.json` 必须来自部署审核，不能直接使用合约测试池 JSON 替代。示例输出 `assetClassification`；RPC 失败会报告失败，不自动切换网络或发送交易。目录不提供真实资产兑换关系；公开 mint 是测试代币合约功能，不是生产资产的发行入口。

package/docs/liquidity.md

@@ -0,0 +1,87 @@
+# LP 接入与 P5 原生币支持
+
+前端完整流程见[接入指南](frontend.md)；“我的仓位”和按比例提取见[仓位说明](positions.md)。
+
+P3 提供双 ERC-20 本金预览、余额 / allowance、精确授权、存入、撤出、本人领取和撤出并领取。必须使用已审核的部署配置；Hook 的 `capabilities.liquidity` 必须为 `verified` 才能准备和发送交易。构造客户端不访问网络，读与预览不要求钱包。P4 增加收益和代领，P5 增加 RampETH 原生币及变体资金验收。
+
+## 钱包与交易流程
+
+```ts
+const market = createMarketClient({ publicClient, walletClient, chain });
+const quote = await market.previewDeposit({
+  key, tickLower: -120, tickUpper: 120,
+  liquidity: 10n ** 18n,
+  slippageBps: 50,
+  deadline: (await publicClient.getBlock()).timestamp + 180n,
+});
+const spend = await market.getSpendStatus({
+  key, owner,
+  amount0: quote.data.limit0, amount1: quote.data.limit1,
+});
+// UI 展示每个 token 的余额、现有 allowance 和最大支出。
+// 对需要授权的 token，amount 填其完整 requiredAmount，不能只填缺口。
+const approval = await market.prepareApproval({
+  key, currency: 0, amount: quote.data.limit0,
+});
+// 展示 approval.request；用户确认后显式执行：
+const approvalHash = await market.send(approval);
+const approvalResult = await market.waitForTransaction(approvalHash);
+if (approvalResult.status !== "confirmed") throw new Error("Approval reverted");
+// currency1 若也缺授权，同样单独准备、确认、发送并等待回执。
+// 授权后重新获取 quote 和 spend，确认新限额仍被余额和 allowance 覆盖。
+const freshQuote = await market.previewDeposit({
+  ...quote.data,
+  deadline: (await publicClient.getBlock()).timestamp + 180n,
+});
+const deposit = await market.prepareDeposit(freshQuote);
+// 再展示交易，显式发送并核对 receipt/events。
+const hash = await market.send(deposit);
+const result = await market.waitForTransaction(hash);
+```
+
+可编译的消费端示例：`examples/consumer/src/market.ts`。`marketLiquidityWorkflow` 返回同一个 client 以及显式广播 helper；不在构造或读取时签名。
+
+- `previewDeposit(params)` / `previewWithdraw(params)`：参数包括完整 PoolKey、上下 tick、liquidity、slippageBps、deadline、可选 validForSeconds。返回不可变 `{block,data}`，含本金 amount0/1、limit0/1、rangeId、sqrtPriceX96、expiresAt。以 PoolManager 为数据源，不要求 Registry 仍列出该池。
+- `getSpendStatus({key,owner,amount0,amount1,...block?})`：同时读取两币余额和对该 Hook 的 allowance，不隐式批准。
+- `prepareApproval({key,currency,amount,validForSeconds?})`：currency 只允许 0 或 1；精确替换额度，限 uint128，与存入最大金额边界一致。amount=0 显式撤销 / 清零。需要先清零的 token 必须先单独发送并确认零授权，再准备新额度；不自动扩大授权、不自动发送第二笔。
+- `prepareDeposit(quote)`：只接受当前客户端生成的 deposit quote，检查余额和 allowance 覆盖 maxima；份额归当前钱包，无存入 recipient 参数。
+- `prepareWithdraw(quote,to)`：只接受当前客户端的 withdraw quote，limit 为最低本金；暂停不阻止此操作。手续费会在合约内结算到 owed，但不会自动支付。
+- `prepareWithdrawAndClaim(quote,to,maxFeeBps)`：撤出并本人领取；暂停时拒绝，分账费上限在合约内验证。
+- `prepareClaim({key,tickLower,tickUpper,to,maxFeeBps,validForSeconds?})`：本人领取，不依赖 Registry 或池状态 Reader；零份额但仍有 owed 也交由合约处理。不得把 settledOwed=0 当作没有可领手续费。合约可能成功且没有 FeesClaimed 事件。
+- `send(prepared)`：只发送本客户端保存的不可变 canonical 请求。来源伪造、跨客户端、重复提交、链或账户变化均拒绝。发送前重新核对身份、有效期并模拟。
+- `waitForTransaction(hash,{timeout?})`：仅接受该实例发送的 hash；使用 chain.confirmations，返回 confirmed / reverted 和实际 receipt。事件只接纳对应 Hook、owner、range 和 recipient。存入 / 撤出成功必须有匹配事件；领取成功可能没有支付。repriced 替换返回实际 hash，cancelled / replaced 抛出 `MarketTransactionReplacedError`；超时保留 hash 可再次等待。
+
+持有这个 client 实例直到交易完成。实例重建后可用 viem 根据已保存 hash 获取原始回执，但新的实例不会将陌生 hash 当作自身准备的动作。广播状态不明确时先查询已有 hash / 钱包交易历史，不要盲目重复存入。
+
+## 精度和保护边界
+
+所有金额均为 token 原始单位、liquidity 为 ERC-6909 LP 份额，不是 token 数量。`getMarketSqrtPriceAtTick` / `getMarketTickAtSqrtPrice` 使用 v4 tick 边界；`getMarketPriceRatio` 返回精确分数，表示已应用 decimals 的 currency1/currency0 价格。`getMarketAmountsForLiquidity` 和 `getMarketLiquidityForAmounts` 保留整数精度，无浮点运算。
+
+存入本金向上取整，最大支出再按 `ceil(amount * (10000 + bps) / 10000)` 计算。撤出本金向下取整，最低回收按 `floor(amount * (10000 - bps) / 10000)` 计算。bps 允许 0..9999；小额或单边仓位的一侧 min 可能为零，调用方应展示实际保护值。这里是 token 金额容忍度，不是价格或 tick 容忍度；价格跨边界时交易可能回滚。Fee-on-transfer / rebasing 等特殊 token 未验收。
+
+数学基于以下 MIT 库，并通过本地 EVM 中编译后的库做差分：
+
+- v4-core `46c6834698c48bc4a463a86d8420f4eb1d7f3b75`：TickMath、SqrtPriceMath。
+- v4-periphery `9969eec44cfdf07e24b41de47f40276a58401976`：LiquidityAmounts。
+- 许可原文见包内 `THIRD_PARTY_NOTICES.md`。
+
+预览和 prepared 的有效期使用链上 timestamp，默认 60 秒，可设置 1..300 秒；LP preview 的 expiresAt 是 deadline 与快照寿命的较小值。准备 / 发送均拒绝过期、区块 hash 改变或时间倒退。存取的 deadline、max/min、组合领取的 maxFeeBps 进入 calldata，交易在 mempool 中等待也受合约限制；单独 `claimFees` 和 `approve` 没有链上 deadline，SDK 的有效期只能限制广播时机。模拟不是执行保证，签名期间 / 广播后状态仍可能改变。
+
+maxFeeBps 是用户容忍的有效分账上限（0..2000），不是固定手续费或最终净收益预言；合约历史策略决定本次有效费率。已结算净额只通过 `getPosition().data.settledOwed0/1` 展示；完整实时收益估算请使用 P4 的 `estimateClaimableFees`，见 [收益说明](./earnings.md)。
+
+准备和发送检查选中 Hook、PoolManager、authority、ClaimFeePolicy 的运行时代码与绑定；RwaRamp 还检查 Calendar 的代码、Hook 绑定及 controller。可选 Reader 或 Registry 故障不阻止直接本金退出。RPC 与合约错误保留 cause：读操作为 MarketReadError，交易阶段为 MarketTransactionError(stage=simulate/send/receipt)。没有静默降级或自动换链。
+
+## 验证范围
+
+参见 `tooling/market-integration/README.md` 的真实 EVM 复现方式。Ramp、RampETH 双 ERC-20、RampETH 原生币与 RwaRamp 双 ERC-20 的本地闭环均已验证，详见 [P5 验收矩阵](./variants.md)。后续 Arc/BSC 三组文档测试池已通过线上只读和本地 fork 存取/收益对账，见[前端指南验证范围](frontend.md#验证范围)。尚未执行主网资金交易，也没有自动开放主网 capability。
+
+
+## RampETH 原生币
+
+只有 `kind: "ramp-eth"` 可使用 `currency0 = zeroAddress`，且写操作同时要求 `liquidity` 与 `nativeLiquidity` 为 `verified`。Ramp / RwaRamp 拒绝 native；包装币仍按普通 ERC-20 处理。读和预览不会自动提升能力状态。
+
+- 存入 `request.value = preview.data.nativeValue = limit0`，合约实际花费后把剩余原生币退给存入方；`estimatedNativeRefund = limit0 - amount0` 仅是预览价格下的估计。其他操作和所有双 ERC-20 池的 value 均为零。
+- 原生币 `getSpendStatus` 返回 `kind: "native"`、`allowance: null`、`needsApproval: false`。`sufficientBalance` 只比较本金；`prepareApproval` 对原生币明确拒绝，currency1 仍需普通授权。
+- 原生币池的交易准备会模拟、估算 gas，按向上取整的 125% gas 设置限额，绑定 EIP-1559 `maxFeePerGas` / `maxPriorityFeePerGas`，并检查 `balance >= value + gas * maxFeePerGas`。发送前再次检查余额。不会把预计退款用于支付前置预算，也不会用零 gas 预算静默降级；此路径需要 RPC 支持 EIP-1559 费率及 gas 估算。估算不保证状态变化后的交易成功，重新准备可更新预算。
+- 未发布 0.1.0 的公共类型已扩展：`MarketTransactionRequest.value` 为 bigint，新增可选 gas 预算字段；spend allowance 为 `bigint | null`。消费端应按 `kind` 展示授权，按上述预算显示原生币前置余额。
+- 合约接收方拒绝退款时整个 deposit 回滚；退款为零时不调用接收函数。撤出和领取使用 PoolManager 直接支付收款人；拒收时份额、owed 和转账整体回滚。原生币余额对账需扣除发送方实际 gas，而收款人独立于发送方时可直接对比事件金额。

package/docs/management.md

@@ -0,0 +1,73 @@
+# P6 Keeper 与管理接入
+
+`getManagementAuthorization(action, account, { when? })` 在固定区块返回权限和编码，`prepareManagement(action, { execution?, validForSeconds? })` 准备交易。默认 execution 为 `{ mode: "direct" }`。它们只接受类型明确的 `MarketManagementAction`，不接受任意目标 / calldata；广播仍显式调用同一 client 的 `send` 和 `waitForTransaction`。
+
+选中 Hook 必须配置 `capabilities.management = "verified"`。此验收记录独立于 liquidity / nativeLiquidity，管理账户无需开放 LP 能力。SDK 核验相关合约代码、authority、Hook / ClaimFeePolicy / Calendar 绑定；Registry / Reader 操作额外核验目标及其绑定。Reader 停用、Registry 下架 / 重新上架不读取 Hook，保留处置故障 Hook 的路径。setHook 只接受已在部署配置登记的 Hook，并要求显式 expectedCodeHash 与审核配置一致，实际代码也必须匹配；不会把现场读取的哈希自动当作可信值。
+
+## 操作和作用域
+
+所有 action 都带 `key` 以选择已审核 Hook。以下 `kind` 为精确 API 名称：
+
+| kind | 参数与语义 |
+| --- | --- |
+| pokeFee | fee0For1 / fee1For0 为整数 pips，允许一侧零表示该方向不覆盖，不能同时为零；ttl 为 1..259200 秒。核验链上 floor / cap；执行时仍受自主费率的 50% 下限约束 |
+| clearPoke | 清除两方向临时覆盖 |
+| setPoolAsymmetry | premiumPips、premiumZeroForOne；持久方向加价，不能超过当前 cap-floor |
+| setCryptoPoolConfig | floorPips >=100、flatPips >=floor、cap >=flat 且不超过 Hook ABSOLUTE_MAX_FEE；仅 Ramp / RampETH |
+| setRwaPoolConfig | config: MarketRwaFloorConfig、cap；仅 RwaRamp，显式选择带 FloorConfig tuple 的重载，验证尖峰、下降窗口与收盘曲线约束 |
+| setSessionHours | openSec / closeSec 为本地日内秒；遵守合约的默认时间 ±30 分钟边界 |
+| setDayOverrides | year / month / days: [{day,status:"closed"或"open"}]；替换整个月，空数组清除。最多10个不重复日期；SDK Gregorian 日期域为1970..9999 |
+| setDstMode | mode: auto / est / edt；合约要求固定模式与当前 AUTO 偏移一致，实际执行时再次约束 |
+| setEarlyClose | year / month / day / closeSec；0清除，否则不得晚于当前收盘，距当前开盘至少3小时 |
+| setPaused / setPoolPaused | duration: 0..604800 秒；0解除。前者作用于整个 Hook，后者作用于 key 对应池 |
+| setClaimFee | bps:0..2000、recipient、必须显式提供 settleFirst: Address[]；比例按池配置，recipient 却是整个 Hook 的全局收款人 |
+| setClaimFeeBps | 只改本池 bps，不轮换收款人；要求已有收款人 |
+| sweepClaimFee | currency；任何账户均可触发，不需要 AccessManager 角色，但合约暂停时拒绝。始终支付给链上全局收款人 |
+| register / deregister / reregister | 针对部署配置的 Registry；登记与资金能力独立，register 已存在时回滚 |
+| setHook / disableHook | 针对配置的 Reader；setHook 必填 expectedCodeHash，Reader kind 根据已审核 Hook 变体决定 |
+
+日历操作全部发送给 RwaRamp，由 Hook 转发到 Calendar；费用比例操作全部发送给 Hook，不直接写 ClaimFeePolicy。日期纯工具 `marketDaysInMonth` / `packMarketDayOverrides` 从根入口导出。金额单位与普通 LP 相同，费率 pips 与分账 bps 不可混用。
+
+## 权限与延迟交易
+
+```ts
+const action = {
+  kind: "pokeFee" as const,
+  key,
+  fee0For1: 2000,
+  fee1For0: 0,
+  ttl: 300,
+};
+const permission = await client.getManagementAuthorization(action, account);
+// permission.data: permission / delay / operationId / scheduledAt / direct / schedule / execute
+// denied: 不应发送；immediate: 可准备 direct；delayed: 必须先排期。
+const queued = await client.prepareManagement(action, {
+  execution: { mode: "schedule" },
+});
+const scheduled = await client.waitForTransaction(await client.send(queued));
+if (scheduled.status !== "confirmed") throw new Error("Schedule reverted");
+// 保存完整 action、chain/deployment、账户、operationId、hash。
+// 等链上 getManagementAuthorization(...).data.scheduledAt 到期后重新准备：
+const execution = await client.prepareManagement(action, {
+  execution: { mode: "execute" },
+});
+const result = await client.waitForTransaction(await client.send(execution));
+```
+
+示例展示 delayed 分支。immediate 直接 `prepareManagement(action)`；拒绝将 delayed 假装成 direct。schedule / execute 发送到 AccessManager，真正的业务 target / data 保存在 context.management 中。schedule 的 when 默认为0，让合约按落块时间加 delay 排期；显式 when 必须至少达到当前区块 timestamp+delay。execute 要求该账户和完整 calldata 对应的有效排期已到期；getSchedule=0 可能表示未排期、已执行、取消或过期。
+
+排期成功只表示 AccessManager 接受排期，不代表业务已执行，也不保证到期时业务状态有效。准备与发送都会重新验证权限、参数相关的当前边界、部署身份、账户、链和请求寿命，并模拟本次真正发送的请求；schedule 时模拟的是 schedule，本次操作不会越过权限去伪装模拟未来业务。延迟完成后必须重新 prepare execute，不能让普通 prepared 对象存活数小时。执行失败会回滚排期消费，可在修正状态后重新准备执行。TTL 从业务执行时间开始，不从排期时间开始。
+
+`getManagementAuthorization` 的 direct / schedule / execute 提供所需编码，SDK 的 `send` 仍只接受本实例准备的对象。日后重建实例可根据保存的 action 和当前账户重新查询并 prepare execute。取消或 AccessManager 角色治理未封装为 Market 管理动作，可通过导出的 AccessManager ABI 显式处理；本阶段不交付 Keeper 服务或自动调度器。
+
+## 费用收款人轮换
+
+`settleFirst` 没有默认值，也不自动填入 key 的两币。它列出的已累计协议债务先支付给旧收款人，然后才轮换全局收款人；遗漏币种的债务归新收款人。列表可能需要包括同一个 Hook 其他池的币种。`pendingClaimFeeCurrencyCount` 仅是计数，不是完整币种枚举；列表为空是调用方明确选择全部遗留债务转给新收款人。
+
+这一步支付的是已经累计的协议 claim fee，不会遍历所有 LP 区间把尚未同步的收益强制结算。旧收款人拒收、币种支付失败或其他校验失败会回滚整笔交易，包含已支付的前序币种、债务扣减、收款人和比例更新。新收款人不能为零 / Hook / PoolManager；合约仅允许 bps=0 且尚未设置收款人时保留零地址。
+
+## 回执和验收
+
+回执新增 `managementEvents`，仅解码业务目标或配置的 AccessManager 发出的日志；AccessManager 日志匹配 operationId。schedule / execute 成功必须有相应 OperationScheduled / OperationExecuted；零债务 sweep 可以成功且没有支付事件。完整原始 receipt 仍保留，管理事件 args 为只读 Record<string, unknown>，消费端按 eventName 校验字段后展示。
+
+真实本地测试覆盖三个 Hook 的管理配置、方向费率、暂停、Registry / Reader、RWA 日历和重载选择；无角色拒绝、延迟排期 / 到期执行 / 重复执行拒绝 / 撤销权限 / 排期过期；执行失败保留排期；显式遗漏币种的债务归属与原生币拒收导致的轮换回滚。无主网写入或自动 capability 提升。P7 仍负责最终发布验收。

package/docs/pool-state.md

@@ -0,0 +1,30 @@
+# Pool state read boundary
+
+P2 supports two explicit readers. Neither is selected by guessing the chain or calling a nonexistent `PoolManager.slot0()` getter. All queries use the same block as Registry reads; code hashes are checked against caller-reviewed deployment records at that block.
+
+```ts
+// StateView is preferred when a reviewed deployment exists.
+poolStateReader: {
+  kind: "state-view",
+  contract: { address: reviewedStateView, runtimeCodeHash: reviewedRuntimeHash },
+}
+
+// Otherwise opt into the specific audited PoolManager layout.
+poolStateReader: { kind: "extsload", layout: "uniswap-v4-v1" }
+```
+
+An omitted reader causes `getPoolState` to reject with `MarketFeatureUnavailableError`. A configured StateView failure never silently falls back to direct storage. The expected PoolManager hash is always checked; StateView additionally checks its own runtime hash and `poolManager()` binding. These checks establish identity against supplied records, not an independent audit of code or layout.
+
+## Pinned interface and layout sources
+
+- [Uniswap StateView at 9969eec44cfdf07e24b41de47f40276a58401976](https://github.com/Uniswap/v4-periphery/blob/9969eec44cfdf07e24b41de47f40276a58401976/src/lens/StateView.sol): `getSlot0`, `getLiquidity` and its PoolManager binding.
+- [StateLibrary at 46c6834698c48bc4a463a86d8420f4eb1d7f3b75](https://github.com/Uniswap/v4-core/blob/46c6834698c48bc4a463a86d8420f4eb1d7f3b75/src/libraries/StateLibrary.sol): pool mapping slot 6 and liquidity offset 3.
+- [Slot0 at the same core revision](https://github.com/Uniswap/v4-core/blob/46c6834698c48bc4a463a86d8420f4eb1d7f3b75/src/types/Slot0.sol): packed price, signed tick, protocol fee and stored LP fee.
+
+These external source revisions document the optional adapter, not the missing `lib/` revision of the upstream contract checkout. The caller must establish that its pinned PoolManager uses this layout before opting in. No Arc default or blanket claim of compatibility is shipped.
+
+The adapter computes `keccak256(abi.encode(poolId, uint256(6)))`, reads this slot and offset 3 through `extsload(bytes32[])`, and decodes the signed tick separately from fee fields. Minimal handwritten interfaces live in `src/abi/v4.ts`; the eight generated Ramp ABI snapshots are unchanged.
+
+`activeLiquidity` is in liquidity units. `storedLpFeePips` is the pool's stored fee, not the Hook's current direction-dependent execution fee; use `getCurrentFees` for the latter. `protocolFeePacked` retains v4's packed directional protocol rates. `sqrtPriceX96=0` yields `initialized=false`; it does not invent a price, TVL, APR or tradeability.
+
+Tests cover packed negative ticks, field isolation, storage offsets, malformed responses, zero state, bounded reads, code/binding mismatch and equivalent StateView/extsload results. P2's initial public Arc RPC call timed out. Retrying with Launchpad's `https://rpc.arc-scan.org` returned HTTP 530 / error 1033 on 2026-09-30; those P2 checks were local evidence only. Later R4–R5 checks used an explicit Arc Blockdaemon RPC and a BSC RPC to read the three documented test pools and complete local-fork fund-flow reconciliation. This does not attest PoolManager source identity or mainnet transaction execution; see [frontend verification scope](frontend.md#验证范围).

package/docs/pools.md

@@ -0,0 +1,118 @@
+# 池子列表与市场详情
+
+`client.listPools()` 查询当前部署的 PoolRegistry，Arc 与 BSC 使用相同接口、不同链配置。调用方先执行 `verifyDeployment()`；读取无需钱包。前端创建客户端见[接入指南](frontend.md)。
+
+## 参数与分页
+
+| 参数 | 类型 | 默认值 / 含义 |
+| --- | --- | --- |
+| `offset` | `bigint` | `0n`，Registry 的扫描起点 |
+| `limit` | `number` | `20`，每次扫描 1–100 条登记记录 |
+| `activeOnly` | `boolean` | `false`；为 true 时过滤停用记录 |
+| `blockNumber` | `bigint` | 未提供时选择最新已出块区块 |
+| `blockHash` | `Hex` | 可选；必须同时提供 blockNumber，用于续读身份核对 |
+
+```ts
+import type { MarketClient, MarketPoolPage, MarketSnapshot } from "@masterpeach/market-sdk";
+
+export function firstPoolPage(client: MarketClient) {
+  return client.listPools({ offset: 0n, limit: 20, activeOnly: true });
+}
+
+export function nextPoolPage(
+  client: MarketClient,
+  previous: MarketSnapshot<MarketPoolPage>,
+) {
+  if (previous.data.nextOffset === null) return null;
+  return client.listPools({
+    ...previous.block,
+    offset: previous.data.nextOffset,
+    limit: 20,
+    activeOnly: true,
+  });
+}
+```
+
+`limit` 是扫描量，不是过滤后返回数量。某页可能 `pools=[]` 且仍有 `nextOffset`；只有 `nextOffset === null` 才表示扫描结束。`totalCount` 是该区块 Registry 的总登记数，不是 active 池数量。
+
+续页保留第一页的区块，避免分页间数据漂移；主动刷新时清空旧分页并从最新区块重新查询。如果节点不能提供该历史区块或检测到重组，展示错误并允许重新加载，不能拼接新旧区块的结果。接口读取每批最多 8 个池，不依赖 Multicall3。
+
+## 返回数据
+
+返回 `MarketSnapshot<MarketPoolPage>`，即 `{ block, data }`。
+
+| 字段 | 类型 | 含义 |
+| --- | --- | --- |
+| `block.chainId` | `number` | 5042 或 56 等实际查询链 |
+| `block.deploymentId` | `string` | 配置的部署标识 |
+| `block.blockNumber` | `bigint` | 本次快照区块 |
+| `block.blockHash` | `Hex` | 区块身份，读取结束时复核 |
+| `block.timestamp` | `bigint` | 区块 Unix 时间，单位秒 |
+| `data.pools` | `readonly MarketPool[]` | 本页符合条件的池 |
+| `data.totalCount` | `bigint` | 未按 activeOnly 过滤的总登记数 |
+| `data.nextOffset` | `bigint \| null` | 下一次扫描起点 |
+
+每个 `MarketPool` 包含：
+
+| 字段 | 类型 | 含义 |
+| --- | --- | --- |
+| `poolId` | `Hex` | 完整 PoolKey 的哈希 |
+| `active` | `boolean` | Registry 登记启用状态 |
+| `hookKind` | `"ramp" \| "ramp-eth" \| "rwa-ramp" \| null` | 当前配置识别到的 Hook 类型；null 为未配置支持的 Hook |
+| `key.currency0` / `currency1` | `Address` | 已按地址顺序排列的两币地址，不一定是业务 base/quote 顺序 |
+| `key.fee` | `number` | v4 动态费率标记 `8388608`，不是当前 swap 费率 |
+| `key.tickSpacing` | `number` | tick 间距 |
+| `key.hooks` | `Address` | 该池的 Hook 地址 |
+
+池没有独立 Pair 合约地址。跨链用 `(chainId, poolId)` 标识市场，缓存还应包含 deploymentId。不能仅按代币对聚合不同 Hook、fee 或 spacing 的池。
+
+`active=true` 不等于未暂停、已有流动性或具备写权限；`active=false` 也不表示本金不能退出。发现未知 Hook 时可展示其基础记录，但不调用 SDK 的该 Hook 业务方法。RWA `closed` 仅是费率时段，不能直接当成“禁止交易”。
+
+## 详情与展示字段
+
+列表本身不附带 token symbol、decimals、logo、价格、TVL、APR、成交量、用户仓位或收益。这些字段应按实际页面需要补充，不应对每行自动重复执行全量查询。
+
+| 页面字段 | 获取方式 / 边界 |
+| --- | --- |
+| 双向当前费率、全局/池暂停状态 | `getCurrentFees(poolId, options)`；读取 `fee0For1Pips` / `fee1For0Pips` |
+| 费率构成 | `getFeeBreakdown(poolId, zeroForOne, options)`；需要配置 Reader |
+| RWA 时段 | `getSession(poolId, options)`；非 RWA 的 session 为 null |
+| sqrtPriceX96、tick、活动流动性 | `getPoolState(poolId, options)`；需要显式 StateView / extsload 配置 |
+| 两币相对价格 | 使用 `getMarketPriceRatio` 和真实 decimals；不是美元价格 |
+| 名称、symbol、精度、图标 | 前端 token 元数据服务或 ERC-20 查询；原生币单独处理 |
+| TVL、APR、历史成交量、USD 估值 | 索引服务及价格数据，SDK 没有直接接口；activeLiquidity 不是 TVL |
+| 用户仓位 | 索引提供区间标识，再调用 `getPosition`，见[仓位说明](positions.md) |
+
+```ts
+import type { MarketClient, MarketPool } from "@masterpeach/market-sdk";
+
+export async function loadPoolDetails(client: MarketClient, selected: MarketPool) {
+  if (selected.hookKind === null) throw new Error("Unsupported Hook");
+  const pool = await client.getPool(selected.poolId);
+  const [fees, state, session] = await Promise.all([
+    client.getCurrentFees(selected.poolId, pool.block),
+    client.getPoolState(selected.poolId, pool.block),
+    client.getSession(selected.poolId, pool.block),
+  ]);
+  return { pool, fees, state, session };
+}
+```
+
+上例要求配置 poolStateReader；缺少时该查询会报错，不能把缺失状态显示成零价格。费率 pips 为百万分之一：`100 pips = 0.01%`，展示百分数为 `pips / 10000`。收益分账使用 bps，不能与 pips 混用。
+
+## 测试资产识别
+
+```ts
+import { marketTestPools } from "@masterpeach/market-sdk";
+import type { Hex } from "viem";
+
+export function findKnownTestPool(chainId: number, poolId: Hex) {
+  return marketTestPools.find(
+    (pool) => pool.chainId === chainId && pool.poolId.toLowerCase() === poolId.toLowerCase(),
+  );
+}
+```
+
+目录覆盖 Arc tBTC/tUSDC、BSC tBNB/tUSDT 和 tQQQ/tUSDT，包含 PoolKey、币种精度、组件地址与来源区块。三组均为无价值、可公开 mint 的测试 ERC-20。tBNB 不是原生 BNB；Arc 的 tUSDC/6 位也不是 gas 所用原生 USDC/18 位。
+
+共享 Registry 可以混合真实资产与测试资产。未命中有限的测试目录只能标记为“未分类”，不能据此判定为真实资产。目录不是实时池状态，也不是可信部署配置。

package/docs/positions.md

@@ -0,0 +1,94 @@
+# 我的仓位、收益与提取流动性
+
+SDK 支持查询已知区间的用户份额、收益以及存取操作，**不提供按钱包自动枚举全部历史仓位的接口**。LP 是 Hook 管理的 ERC-6909 区间份额，不是 ERC-721 tokenId。
+
+## 仓位列表的数据来源
+
+前端或索引服务维护候选 `(chainId, deploymentId, hook, rangeId, owner)`，再调用 SDK 读取当前链上状态。候选记录至少考虑存入、退出、份额转入/转出；仅保存当前浏览器的 deposit 回执会遗漏其他设备操作及别人转入的份额。
+
+索引合约日志时须处理分页、回滚/重组和重复事件。链上快照才是余额与收益依据，不能把历史事件累计值直接当当前可提金额。一个 Hook 可服务多个池，多个用户可持有同一 rangeId；候选记录不要只按 rangeId 或代币对去重。
+
+## 查询参数和返回字段
+
+`getPosition({ hook, rangeId, owner, blockNumber?, blockHash? })` 返回 `{ block, data }`。
+
+| data 字段 | 含义 |
+| --- | --- |
+| `owner` | 被查询钱包 |
+| `shares` | bigint 用户 LP 份额，不是 currency0/1 数量，也不能套代币 decimals 展示 |
+| `range` | 区间状态，见下文 |
+| `settledOwed0/1` | 已结算的净手续费欠款，token 最小单位；不是完整实时可领取金额 |
+| `checkpoint0X128/1X128` | 用户净收益检查点，用于精确记账 |
+| `remainder0X128/1X128` | Q128 余数，不能当成整数 token 金额相加 |
+
+`range.status="unset"` 时仅有 hook / rangeId，不能读取 key、ticks 或估算该区间收益。`status="set"` 时还包含 poolId、key、tickLower、tickUpper、state、globalPaused、poolPaused、effectiveClaimFeeBps。`state` 包含 totalShares、accFee0X128/1X128、collectionSeq 和 resetSeq。
+
+不要只用 `shares > 0` 过滤仓位：全部退出后仍可能有历史净收益待领取；已建立但 totalShares=0 的区间也不同于 unset。重建区间后 resetSeq 可能变化，不能沿用旧缓存的收益增长基线。
+
+```ts
+import type { MarketClient } from "@masterpeach/market-sdk";
+import type { Address } from "viem";
+
+export async function loadPosition(
+  client: MarketClient,
+  hook: Address,
+  rangeId: bigint,
+  owner: Address,
+) {
+  const position = await client.getPosition({ hook, rangeId, owner });
+  if (position.data.range.status === "unset") return { position, earnings: null };
+  const earnings = await client.estimateClaimableFees({
+    hook, rangeId, owner, ...position.block,
+  });
+  return { position, earnings };
+}
+```
+
+收益结果 `earnings.data.token0/1.claimable` 为完整估算，包含 settled / synchronized / pending 三部分并处理余数；`hasClaimableAmount` 表示是否有整数可领取额。链上状态可能在查询后变化，准备交易仍需模拟。详细记账语义见[收益与权限](earnings.md)。
+
+“我的仓位”列表应为每个条目保留加载/错误状态，单个池异常不要清空其他仓位；RPC 失败不能显示成余额为零。页面批量查询应限制并发。
+
+## 部分提取、全部提取和领取
+
+使用用户份额计算提取比例。以下只准备交易，不发送；`withdrawBps=10000` 为全部提取，`5000` 为一半。整数舍入后为零时不应提交。
+
+```ts
+import type { MarketClient } from "@masterpeach/market-sdk";
+import type { Address } from "viem";
+
+export async function preparePositionExit(
+  client: MarketClient,
+  params: {
+    hook: Address; rangeId: bigint; owner: Address; to: Address;
+    withdrawBps: number; slippageBps: number; deadline: bigint;
+    // undefined 表示只提本金；传入值表示同时领取并限制分账费。
+    maxFeeBps?: number;
+  },
+) {
+  if (!Number.isInteger(params.withdrawBps) || params.withdrawBps < 1 || params.withdrawBps > 10000)
+    throw new Error("Invalid withdrawal percentage");
+  const position = await client.getPosition({
+    hook: params.hook, rangeId: params.rangeId, owner: params.owner,
+  });
+  const range = position.data.range;
+  if (range.status !== "set") throw new Error("Unknown range");
+  const liquidity = position.data.shares * BigInt(params.withdrawBps) / 10000n;
+  if (liquidity === 0n) throw new Error("No withdrawable shares at this percentage");
+  const quote = await client.previewWithdraw({
+    key: range.key, tickLower: range.tickLower, tickUpper: range.tickUpper,
+    liquidity, slippageBps: params.slippageBps, deadline: params.deadline,
+  });
+  return params.maxFeeBps === undefined
+    ? client.prepareWithdraw(quote, params.to)
+    : client.prepareWithdrawAndClaim(quote, params.to, params.maxFeeBps);
+}
+```
+
+此示例的 owner 必须是当前连接钱包；它不是替其他钱包提取的授权接口。deadline 使用链上时间生成的 Unix 秒，slippageBps 是本金容忍度。UI 应展示 quote 的最低到账 limit0/1；maxFeeBps 是 LP 收益分账上限，范围 0–2000，不是提取本金的费率。
+
+- `prepareWithdraw` 只提本金；手续费结算到 owed，后续单独领取。暂停期间仍支持本金退出。
+- `prepareWithdrawAndClaim` 同时退出和领取，暂停时不可用，不能作为暂停期间唯一退出入口。
+- `prepareClaim({ key, tickLower, tickUpper, to, maxFeeBps })` 单独领取；不要求先提取本金。领取成功可能没有支付事件，例如金额不足一个最小单位。
+- `prepareClaimFeesFor` 是单独的代领能力，需要区间 claim operator 授权；普通份额 operator 不自动取得代领权限。
+
+交易确认后刷新用户份额、收益、币余额及 allowance。持有旧 hash 的 pending/超时交易先查回执，不要再次发起相同资金操作。[发送与回执处理](frontend.md#交易发送与界面状态)使用同一个 client 实例。

package/docs/variants.md

@@ -0,0 +1,24 @@
+# P5 变体实现与部署验收
+
+## 实现矩阵
+
+| 本地真实合约 | 双 ERC-20 LP | 原生币 LP | 净费用对账 | 本金限制与暂停退出 |
+| --- | --- | --- | --- | --- |
+| Ramp | 通过 P3 / P4 | 合约不支持，SDK 拒绝 | 通过 | 通过 |
+| RampETH | 通过 P5，value=0 | 通过 P5，currency0=0 | 通过 | 通过 |
+| RwaRamp | 通过 P5 | 合约不支持，SDK 拒绝 | 通过 | 通过 |
+
+P5 验证存入、swap 产生收益、领取、部分组合撤出、暂停后完整本金退出；拒绝错误 max/min、过期 deadline、超额份额、分账费上限和错误 msg.value。RampETH 另核对预付款退款、发送方 gas、零退款合约账户，以及退款 / 领取 / 撤出拒收的真实 reverted 回执和状态回滚。测试工具的合约账户只用于检验退款边界，不表示 SDK 实现了智能账户发送适配。
+
+RwaRamp 复用同一 LP 协议；closed 表示费率时段，不禁止 LP 操作。真实 Calendar / Reader 对照覆盖开盘前一秒 / 开盘、收盘前一秒 / 收盘、春秋 AUTO DST、强制开放 DST 周日的本地日期边界、early close，以及双方向 poke 到期前一秒 / 到期 / 到期后一秒。测试使用固定区块配置对假设时间做预览，不代表查询那一时刻的历史配置。Calendar 的 AUTO 按 DST 周日 UTC 日期切换，这是当前合约语义；节假日表仅覆盖合约内置的 2026–2030 年。
+
+## 部署矩阵
+
+| 环境 | 代码 / 绑定身份 | 资金验收 | capability |
+| --- | --- | --- | --- |
+| 独立本地 Anvil / 31337 | 本次固定源码编译并部署 | 上述矩阵通过 | 仅测试 fixture 声明 verified |
+| Arc / 用户提供的目标部署 | 尚需审核地址、runtime hash、布局及依赖 | 未执行目标链资金验收 | 不自动提升，没有新增可信主网预置 |
+
+实现支持不等于目标部署已验收。原生币写路径必须显式配置 `liquidity=verified` 和 `nativeLiquidity=verified`；Arc 没有已验收 RampETH 时保留 native disabled/unverified，不影响单独验收 ERC-20 能力。用户指定的 Launchpad RPC 保持 `https://rpc.arc-scan.org`，当前未取得恢复证据；没有切换链或执行主网写操作。
+
+复现见 [本地 EVM 工作流](../../../tooling/market-integration/README.md)。生产源码和 ABI 快照未改动，无新增依赖。管理写 API 属于后续 P6；本阶段测试直接调用管理合约仅用于搭建验收状态。