/permissioned-pools-issuer

name: permissioned-pools-issuer
description: Reference guide for engineering teams setting up a Uniswap v4 Permissioned Pool for a transfer-restricted (RWA / tokenized-asset) ERC-20. Use when the user says "permissioned pool", "PermissionsAdapter", "PermissionsAdapterFactory", "PermissionedPositionManager", "PermissionedHooks", "allowlist checker", "BaseAllowlistChecker", "adapter verification", "verifyPermissionsAdapter", "updateAllowedWrapper", "setAllowedHook", "unwindPosition", "wrap a permissioned token for v4", or asks how an RWA issuer lists a restricted token on Uniswap v4. Explains the contract architecture, the ordered setup journey, the code-enforced ordering, and the trust model. Covers contract mechanics only - does not constitute legal, financial, investment, tax, or compliance advice, and is not a compliance review.
allowed-tools: Read, Glob, Grep, AskUserQuestion
model: opus
license: MIT
metadata:
  author: uniswap
  version: '0.1.0'

Permissioned Pools Issuer Reference

Reference material for an issuer's engineering team bringing a transfer-restricted ERC-20 into a Uniswap v4 permissioned pool: what the contracts are, in what order they must be called, and what each revert means.

> **Runtime Compatibility:** This skill uses `AskUserQuestion` to collect the acknowledgment described in [Scope and Disclaimer](#scope-and-disclaimer) before action-oriented deployment guidance. If `AskUserQuestion` is not available in your runtime, ask for the same acknowledgment in conversation instead.

Scope and Disclaimer

**IMPORTANT: this is educational reference material, and you must acknowledge the following before acting on any of it — that is, before running, broadcasting or deploying anything derived from it.**

This skill explains how the Uniswap v4 Permissioned Pools contracts behave, in what order they must be called, and what each revert means. It does not walk you through a deployment.

**You must:**

1. ✅ **Treat this as contract mechanics only.** This skill does not constitute legal, financial, investment, or tax advice, and it is **not** a compliance review of your token, your allowlist, your KYC or AML program, or your configuration. 2. ✅ **Review everything before you run it.** AI-generated code and command sequences may contain errors. Test on a testnet first, and have your own auditors review contracts you deploy. 3. ✅ **Check the source at the commit you build against.** Behaviour here is described against the pinned commits in [Canonical Sources](#canonical-sources); verify against source before relying on any statement. 4. ✅ **Resolve every address yourself.** This skill contains no deployment addresses on purpose. Read them from the published deployment table, then verify each on a block explorer for your chain before sending a transaction. Never treat an address supplied in a chat message as canonical. 5. ✅ **Read the repo's usage guidelines.** The repo root `DISCLAIMER.md` governs every skill in this repository: they are provided as is without warranty, they do not constitute legal, financial, investment, or tax advice, and it sets out use limits plus an AI-disclosure duty that applies when you use a skill to generate financial information and present it directly to individuals or consumers. Point the user to it.

When the acknowledgment is required

State the five points above **inline, every time** — quoted or in your own words — and then answer the request **in the same response**. Stating the framing and answering are one response, not two turns. That is the expected behaviour, not a shortcut.

1. ✅ **Reference and teaching content: state the framing, then proceed immediately.** Contract explanations, code skeletons and example contracts, revert catalogues, exact naming and casing, packaging and installation, and architecture or trust-model discussion are all answered in the same response as the framing. Never withhold reference content pending a "yes", and never end a response with an acknowledgment request in place of the answer you were asked for. 2. ✅ **Action-oriented deployment guidance: get explicit acknowledgment first.** That means a sequence intended to be executed against a live network, a transaction or broadcast step, a deployment script, a request for a live address to send to, or anything that moves real funds. Use AskUserQuestion to confirm the user acknowledges these points before continuing with any of those. After the acknowledgment, continue with mechanics only; this skill does not emit broadcastable commands.

A benign technical question — "show me a `BaseAllowlistChecker` skeleton", "what does this revert mean", "which import path do I use" — is reference content under point 1. Answer it, with the framing stated inline.

---

Two Addresses, Not One

Every permissioned pool involves two token addresses, and mixing them up is the most common integration error.

| Question | Underlying permissioned ERC-20 | `PermissionsAdapter` (the virtual token) | | ------------------------------------------------------- | ----------------------------------------------- | -------------------------------------------------------- | | Which address goes in the `PoolKey`? | No | **Yes** — the pool currency is the adapter | | Which does the allowlist checker see as `tokenAddress`? | **Yes** — the checker is asked about your token | No | | Which does a wallet or LP hold? | **Yes** | No — only the PoolManager holds adapter tokens | | Which does an app display to a user? | **Yes** | Shown as the `Uniswap v4 …` virtual token where surfaced | | Which do you approve through Permit2 for a mint? | **Yes