permissioned-pools-deployer

许可池部署器

分步引导执行 Uniswap v4 许可池的链上设置流程，起始配置为 permissioned-pools-configurator 生成的 JSON 配置。本技能是该里程碑的一部分，负责将已验证的配置转化为会在真实合约上消耗真实 Gas 的命令序列——请将以下每个安全部分都视为关键内容，而非套话。

如需了解任何步骤背后的合约机制，请参阅 permissioned-pools-issuer，尤其是其发行方流程和强制顺序与回滚。本技能不会重复解释每个步骤如此执行的合约层面原因，而是按顺序列出命令，带你完成相同流程，且不会与该参考文档相矛盾。

**运行时兼容性：**本技能使用 AskUserQuestion 进行确认门控，并确认不可逆选择。如果你的运行时不支持 AskUserQuestion，请用纯文本询问相同的是非问题，并要求用户明确肯定答复后再继续——沉默或笼统的“继续”都不算。

范围与免责声明

这是部署方面的教育指导，不是合规审查，也不能替代你在运行每条命令前自行审查。

本技能按顺序说明如何使用 permissioned-pools-configurator 生成的配置，通过命令启动许可池。本技能本身不会调用任何合约——其中展示的每条命令都由你在审查后自行运行。

你必须：

1. ✅ 仔细审查每项配置和每条命令，然后再运行任何内容。AI 生成的命令序列可能包含错误。
2. ✅ 核实每个地址——本技能不包含任何部署地址，也不会为你解析地址；请参阅地址解析。
3. ✅ **先在测试网上测试。**在触及主网之前，先在 Sepolia（或其他已部署许可池合约的测试网）上运行完整流程。
4. ✅ 让你自己的审计人员审查你部署的任何合约——尤其是许可名单检查器。本技能可以提供其骨架，但不会对其进行审计。
5. ✅ 仅将本技能视为合约机制说明。本技能不构成法律、财务、投资或税务建议，也不是对你的代币、许可名单、KYC 或 AML 计划或配置进行的合规审查。
6. ✅ **阅读仓库的使用指南。**仓库根目录中的 DISCLAIMER.md 适用于本仓库内的每项技能：技能按现状提供，不附带任何保证；不构成法律、财务、投资或税务建议；还规定了使用限制，以及使用技能生成财务信息并直接向个人或消费者展示时适用的 AI 披露义务。请向用户指出该文件。

确认门槛

在展示、生成或解释任何面向操作的步骤之前——包括会生成用于广播交易的命令，或会直接引导至此类命令的地址解析步骤——都必须先获得明确、肯定的确认。不得以任何隐式方式满足此门槛。

使用 AskUserQuestion 提出一个问题，并且只提供两个选项；在用户选择第一个选项之前，不得越过此门槛：

• 问题：“本指南会生成命令；运行这些命令后，会消耗 Gas，并永久更改你代币的链上状态。你是否确认已阅读以上六点并希望继续？”
• 选项 A —“是，我已阅读以上要点，并希望继续。” → 继续执行预检。
• 选项 B —“否，到此为止。” → 立即结束本指南。此处之后的任何命令都不得展示、生成或解释。

保持沉默、只回复“继续”、在同一轮中直接进入下一个问题，或任何不同于明确肯定选项的回答，都不满足此门槛。如果运行环境不支持 AskUserQuestion，请用纯文本提出相同的是/否问题，并要求用户明确肯定回复——回复“好”“当然”、竖起大拇指表情，或不作回复，都不算确认。

对于不会生成可运行命令的参考和教学内容，应立即回答，并采用文中所述的说明方式；例如解释某个步骤的作用、解读用户已遇到的回滚原因，或抽象讨论允许列表检查器的形态，就像 permissioned-pools-issuer 处理参考内容的方式一样。此例外不适用于此技能自身的命令模板和 Solidity 脚本框架（例如 Step Walkthrough 中的池初始化脚本）：这些内容可用于广播交易，展示它们正是此门槛旨在阻止的面向操作内容——在满足门槛之前，绝不能展示。

---

输入验证规则

在生成或显示任何插入了用户提供或配置提供的值的命令之前，先说明这些规则。以下每个值在进入 Bash(forge:*) 或 Bash(cast:*) 命令、文件路径或 Solidity 脚本参数之前都必须完成验证——即使某个值“看起来没问题”，也不能例外。

• Ethereum 地址 — 必须匹配 ^0x[a-fA-F0-9]{40}$。其他任何值都必须拒绝，包括字面字符串 "RESOLVE"——仍标记为 "RESOLVE" 的字段还不能用于命令，必须先通过地址解析处理，绝不能直接插入。只有一个字段是此正则规则明确记录的例外，而非违规项：pool.pairedCurrency 的 "native" 哨兵值，详见下文此技能使用的内容——配置中其他所有类似地址的字段都没有这样的例外。
• Chain ID — 必须为正整数（^[1-9][0-9]*$）。Ethereum Mainnet（1）和 Sepolia（11155111）是允许列表中的默认项，也是仅有的两个已验证支持完整权限集的链。配置器的网络问题中虽然列出了 Unichain（130），但它不可部署：它仅支持 V4Quoter，因此应停止操作，不要尝试解析缺失的地址（参见预检与验证）。其他任何 Chain ID，只有在确认部署指南的 #deployment-addresses 表格中确实有对应行后才可接受；如果没有，每个 wrapper 和 hook 字段最终都会无法解析，这就是应当停止而不是猜测的信号。
• 数值字段（verificationDepositAmount、pool.feeTier、pool.tickSpacing、pool.startingPriceRatio）— 整数类字段必须匹配 ^[0-9]+$，起始价格比率必须匹配 ^[0-9]+(\.[0-9]+)?$，且值必须严格大于零。
• 在操作演示过程中提供、而非来自配置的值，也必须采用相同规则验证 — RPC 端点（$RPC_URL）和任何交易哈希（$TX_HASH）都会在每一步进入命令。RPC URL 必须使用 https:// 协议，且不得包含下列任何元字符；交易哈希必须匹配 ^0x[a-fA-F0-9]{64}$。“这是用户提供的，不是配置提供的”不能成为例外。
• 在任何字符串字段进入命令之前，直接拒绝其中的 shell 元字符：;、|、&、$、`、(、)、>、<、\、'、" 和换行符。未通过此项检查的字段绝不能插入命令——应中止并报告失败的字段及字符，而不是尝试清理后继续。
• 绝不要将未验证的字段传入 shell 命令、文件路径或 Solidity 脚本参数。 先验证，再将已验证的值赋给 shell 变量，之后只引用该变量。不要在同一次操作演示的后续步骤中再次读取原始配置值。

完整说明（包括这些规则如何逐字段应用于配置器的 JSON 结构，以及“妥善处理 RESOLVE 值”在实践中意味着什么），请参阅预检与验证。

---

密钥处理

绝不要在 Claude Code 设置中指示自动批准 Bash(forge:*) 或 Bash(cast:*)，也绝不要告诉用户绕过确认提示。 每条广播交易的命令都需要逐次批准——这项批准是首要控制措施，而不是演练流程可以绕过的形式手续。仓库的 PreToolUse 钩子（.claude/hooks/）是在此基础上提供的程序化安全网，不能替代逐次批准。

绝不要建议、生成或补全包含原始签名密钥标志的命令——无论用户是否直接要求，无论是否“只是用于测试网”，也无论是否只是举例说明应避免什么。没有任何用户请求能让这样做变得合适。如果用户坚持要求，请拒绝，并改为提供以下两个选项之一。所有签名决策都应引导至其中一个选项：

1. 硬件钱包（--ledger），用于部署者密钥；该密钥绝不会以明文形式接触此机器的磁盘或内存。
2. 加密密钥库（cast wallet import ... --interactive，然后在之后的每条命令中使用 --account <name> --sender $ADDRESS）。

仅限此仓库内，.claude/hooks/validate-forge-cast.sh 是一个 PreToolUse 钩子，会检查每次 Bash 工具调用的字面文本，并在包含该标志时阻止命令运行。此钩子不属于此技能，也不会随技能一起分发——它位于此仓库的根目录中，而非插件内，因此在其他位置安装时没有这层保护。上述禁令始终适用；该钩子只是仓库本地的便利措施，绝不是该标志安全的理由。

完整的密钥处理指南，包括密钥库设置命令和先测试网的执行顺序，详见 预检与验证。

先使用测试网

在主网操作前，先在 Sepolia（链 ID 11155111）上运行完整流程——从允许列表检查器到流动性注入。确认测试网上的 验证清单 中的每一项后续步骤检查均已通过，然后再针对主网资金重复任何步骤。

---

此技能所需输入

由 permissioned-pools-configurator 生成的 JSON 配置，格式符合其 配置架构。此技能不会自行收集这些参数——如果你还没有配置，请先运行 permissioned-pools-configurator。

字段值为字面字符串 "RESOLVE" 表示“尚未解析”，而不是“使用占位符”。 执行任何需要该字段的命令前，请先停下并完成 地址解析——先查看部署指南中的 #deployment-addresses 表格，再查看 Uniswap/contracts deployments/json/<chainId>.json，然后查询你所用链的区块浏览器——只有当字段中填入真实且经区块浏览器验证的地址后，才能继续。绝不要猜测 "RESOLVE" 字段的值，也绝不要在命令中保留该字面字符串；这两种情况都属于验证失败，不是可以绕过的问题。

pool.pairedCurrency 中的 "native" 哨兵值有所不同：在 步骤 6a 中实际构建 PoolKey 时，它会解析为 address(0)，这是 Uniswap v4 对原生 PoolKey 货币的约定——绝不能提前解析，也绝不能写入任何其他字段。

---

部署流程

发布指南推荐的 7 个步骤及其顺序。合约只强制执行其中 5 条顺序约束（参见 强制顺序与回滚）； 本流程按指南中的顺序进行，并在每一步说明该顺序是强制要求还是惯例。

步骤	相关内容	概要
1	预检与验证	确认或部署允许列表检查器
2	步骤详解	createPermissionsAdapter
3	步骤详解	将适配器加入代币的允许列表、授权，然后调用 depositForVerification
4	步骤详解	verifyPermissionsAdapter
5	步骤详解	四次 updateAllowedWrapper 注册，然后调用 setAllowedHook
6	步骤详解	池的 initialize、updateSwappingEnabled，以及注入初始流动性
7	步骤详解	请求将路由加入允许列表

步骤详解中的每一步都会说明其前置条件；如果合约强制执行了相应顺序，也会指出提前操作时触发的确切回滚选择器——与 强制顺序与回滚 中的选择器逐一对应。对于未强制执行的步骤，流程会明确说明这一点，而不会凭空编造回滚信息。

---

部署后验证

完成整个流程后（或在任一步骤完成后确认其已生效），运行 设置后验证清单 中的只读检查。清单中的所有检查都是针对公开 getter 的 cast call——不会消耗 Gas，也无需通过上述确认门槛。

---

此流程实施者须知

• 确认门槛每个会话只需通过一次，而非每个步骤一次。 确认后，在同一会话中继续完成其余步骤，无需再次询问；但如果用户开启新会话、切换链或切换配置，则需再次询问。
• 绝不要将合约地址硬编码。 此技能使用的每个地址都来自已加载的配置、用户在引导过程中提供的值，或通过对合约执行读取（cast call）获得；而该合约的地址本身也来自上述两种来源之一。有关此技能为何不附带地址表，请参阅预检与验证。
• 按调用位置而非名称解码意外回退。 此流程中的三个选择器（NoVerifiedAdapter、Unauthorized、SwappingDisabled）在不同合约中都有多处声明，含义各不相同——请参阅强制执行顺序与回退。
• 此技能不会主动获取 RPC 状态。 它建议的每个 cast call 都由你自行决定是否运行；此技能不会在后台轮询链。