> ## Documentation Index
> Fetch the complete documentation index at: https://docs.raydium.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 2026-08-17 — CLMM：受限发行人头寸 NFT 冻结

> CLMM 在 V2 开仓路径发现底层铸币权的冻结权限与受限发行人列表匹配时，有条件地冻结新头寸 NFT 账户。

<Info>
  **本页内容由 AI 自动翻译，所有内容以英文版本为准。**

  [查看英文版 →](/reference/changelog/2026-08-17-clmm-restricted-position-nft-freeze)
</Info>

本次发布为选定的 KYC 受限发行人池添加了条件性不可转账路径。它不会冻结每个新头寸、冻结池资产或阻止头寸所有者管理流动性。CLMM 池 PDA 成为每个新头寸 NFT 铸币权的冻结权限，但 NFT 代币账户默认保持解冻状态。程序仅在头寸使用 `OpenPositionV2` 或 `OpenPositionWithToken22Nft` 且至少一个底层金库铸币权的冻结权限来自硬编码的受限发行人列表时，才会冻结它。

## 集成者速览

* **新头寸 NFT 铸币权具有冻结权限，但默认不冻结。** `OpenPosition`、`OpenPositionV2` 和 `OpenPositionWithToken22Nft` 将头寸的 `pool_state` 设置为铸币权冻结权限。铸币权在单个 NFT 铸造后仍被移除。
* **冻结需要 V2 路径加发行人匹配。** `OpenPositionV2` 和 `OpenPositionWithToken22Nft` 检查 `vault_0_mint.freeze_authority` 和 `vault_1_mint.freeze_authority`。仅当至少一个与程序列表匹配时，新 NFT 账户才会被冻结。不匹配时，它保持解冻和可转账状态。
* **冻结意味着绑定到所有者。** SPL Token 会以其原生 `AccountFrozen` 错误拒绝 NFT 转账和代币账户所有者变更。当 NFT 所有者签名时，增加/减少流动性和费用/奖励收集继续有效。
* **关闭仍然可用。** `ClosePosition` 检测冻结的 NFT 账户，使用池 PDA 解冻它，然后原子性地销毁 NFT 并关闭头寸。
* **冻结关闭需要一个额外账户。** 客户端必须将 `personal_position.pool_id` 作为第一个剩余账户追加。缺少它会返回 CLMM `AccountLack`；传递错误的池会返回 `NotApproved`。
* **现有头寸不受影响。** 此更新不会追溯更改 NFT 铸币权或冻结现有代币账户。
* **无 CLMM 状态布局或声明的 IDL 账户列表变更。** `PoolState`、`PersonalPositionState` 和指令参数保持字节兼容。关闭路径要求通过 `remaining_accounts` 传递。

## 触发逻辑

程序在开仓时评估两个金库铸币权：

```rust theme={null}
must_freeze = restricted_ids.contains(vault_0_mint.freeze_authority)
           || restricted_ids.contains(vault_1_mint.freeze_authority)
```

缺少冻结权限不匹配。一侧匹配即可。初始列表包含 CLMM 的 Superstate 资产检测使用的相同发行人权限。当前 mainnet-beta 和 devnet 匹配密钥位于 [`reference/program-addresses`](/zh/reference/program-addresses#clmm-restricted-issuer-freeze-authorities)。

检查仅在提供金库铸币权账户时在共享开仓处理程序中运行。这意味着：

| 开仓路径                         | 头寸 NFT 程序  | 受限发行人冻结行为                             |
| ---------------------------- | ---------- | ------------------------------------- |
| `OpenPosition` V1            | SPL Token  | 不冻结。V1 无法服务已发布列表针对的 Token-2022 发行人资产。 |
| `OpenPositionV2`             | SPL Token  | 检查两个金库铸币权，匹配时冻结。                      |
| `OpenPositionWithToken22Nft` | Token-2022 | 检查两个金库铸币权，匹配时冻结。                      |

## 头寸 NFT 权限变更

在此更新之前，新创建的经典 SPL 头寸 NFT 铸币权不保留冻结权限。更新后，每个新头寸 NFT 铸币权都将其池命名为冻结权限，包括普通池中的头寸。仅此权限设置不会冻结 NFT 代币账户；普通和不匹配的头寸保持解冻。

使用池 PDA 而非全局管理员或发行人密钥将权限范围限制在一个池。外部方无法以 PDA 身份签名，CLMM 不公开任何通用指令来冻结或解冻任意头寸账户。新代码仅在两个地方使用该权限：

1. 当底层发行人检查匹配时，铸造后立即冻结。
2. 在 `ClosePosition` 期间销毁前立即解冻。

## `ClosePosition` 迁移

六个声明的账户不变。对于冻结的 NFT，将池作为第一个剩余账户添加：

```text theme={null}
declared: nft_owner, position_nft_mint, position_nft_account,
          personal_position, system_program, token_program
remaining[0]: personal_position.pool_id   // read-only, non-signer
```

处理程序在加载 `PoolState` 前验证密钥，派生池签名者种子，并执行：

```text theme={null}
解冻 NFT 账户 → 销毁 NFT → 关闭 NFT 代币账户 / 头寸状态
```

所有步骤在一个 Solana 指令中运行，因此一起提交或回滚。每次关闭时传递池是安全的：当 NFT 账户未冻结时，处理程序忽略剩余账户。

<Warning>
  **条件性客户端破坏。** 较旧的客户端可以在升级后成功开仓，因为 V2 开仓账户布局未变。如果该头寸被冻结，同一客户端稍后可能无法关闭它，因为其 `ClosePosition` 构建器省略了池剩余账户。在允许用户在受影响的池中开仓前更新关闭构建器。
</Warning>

## 兼容性矩阵

| 场景             | 转账 NFT | 管理流动性 | 旧版关闭构建器             | 更新的关闭构建器   |
| -------------- | ------ | ----- | ------------------- | ---------- |
| 现有头寸           | 不变     | 是     | 是                   | 是          |
| 新头寸，普通池        | 是      | 是     | 是                   | 是          |
| 新 V2 头寸，受限发行人池 | 否      | 是     | 失败，返回 `AccountLack` | 是；原子性解冻和销毁 |

未引入新的 CLMM 自定义错误变体或数值移位。SPL Token 的原生 `AccountFrozen` 错误拒绝转账或所有者变更尝试。

## 更新的页面

* `products/clmm/overview` — 发布摘要和受限可转账性注意事项。
* `products/clmm/ticks-and-positions` — 权限模型、触发器、所有者能力和关闭迁移警告。
* `products/clmm/accounts` — 头寸 NFT 铸币权和生命周期行为。
* `products/clmm/instructions` — 开仓后置条件和冻结 `ClosePosition` 剩余账户路径。
* `products/clmm/code-demos` — 直接 Anchor 关闭示例和固定 SDK 警告。
* `user-flows/add-remove-liquidity` — 用户面向的受限头寸行为。
* `user-flows/burn-and-earn` — 冻结头寸无法转账到锁定托管。
* `security/oracle-and-token-risks` / `security/attack-vectors` — 发行人和转账风险边界。
* `reference/token-2022-support` — 池白名单和头寸托管之间的区别。
* `reference/error-codes` — 扩展的 `AccountLack` 和 `NotApproved` 原因。
* `reference/program-addresses` — 受限发行人权限匹配密钥。
* `reference/fee-comparison` / `reference/glossary` — 可转账性例外。

**验证于 2026-08-13，对比**：

* 预发布 CLMM 分支 `feat/position-nft-freeze`，提交 `ecb157760776f83f97507fa78c6e32cfb30d92a9`。
* 提交 `2e95310`（受限发行人 NFT 冻结）和 `ecb1577`（池范围冻结权限），与 `master` 的 `51fdba2` 比较。
* `instructions/{open_position,open_position_v2,open_position_with_token22_nft,close_position}.rs` 和 `util/token.rs` 下的程序源。
* `position-nft-freeze.test.ts`，涵盖普通可转账性、冻结转账/所有者变更拒绝和 V2 加 Token-2022 解冻前关闭流。

<Warning>
  此验证涵盖预发布源分支，不是 mainnet-beta 部署或已发布的 SDK 版本。在启用流程前确认已部署的程序、生产受限权限列表和 SDK 关闭构建器。
</Warning>