Restrict Who Can Hold It

Limit transfers of your stablecoin to accounts your KYC program has approved, using B20 transfer policies.

Keep your stablecoin within a known set of holders with an allowlist: transfers only settle between accounts your KYC program has approved. You manage the list in the Policy Registry and bind it to the token’s transfer scopes.

Demo

The demo uses a local browser-generated account to submit real transactions on Base Vibenet. If Vibenet or its B20 features are unavailable, it automatically switches to an illustrative offline version.

New to B20? See the B20 Token Standard for the concepts and a full launch walkthrough. These samples target base-std@be6d045, viem@2.55.11, and Base Foundry v1.1.1.

How Policies Work

The Policy Registry is a singleton precompile that stores each member list once. A token stores only a uint64 policy ID per scope. When a gated function runs, the token calls isAuthorized(policyId, account) on the registry. Many tokens can share one policy; an update to the policy is immediately visible to every token that references it.

Scopes gate specific functions. TRANSFER_SENDER_POLICY and TRANSFER_RECEIVER_POLICY check the sender and recipient on every transfer and transferFrom. MINT_RECEIVER_POLICY checks the recipient on every mint. All three default to ALWAYS_ALLOW (0) until you bind a policy.

An allowlist authorizes only accounts in the set. An empty allowlist authorizes nobody, so seed your intended holders before binding the policy.

Inverted policy IDs

Bit 63 of a uint64 policy ID is the invert (NOT) flag. When that bit is set, isAuthorized resolves the base policy and returns the opposite result. If the base does not exist, the result is false — a mistyped inverted ID never becomes allow-everyone. Call invertedPolicyId(policyId) on the registry to toggle the bit. The inverted ID shares the base’s member set; updating the base updates the inverse immediately.

You can pass an inverted simple policy ID as a child of an INTERSECT or UNION composite to express “A AND NOT X” without maintaining a mirror list.

Create and Bind a Holder Allowlist

TypeScript

import { parseEventLogs, type Address } from "viem";
import { account, publicClient } from "../../shared/clients.js";
import { POLICY_REGISTRY, b20Abi, policyRegistryAbi, scope } from "../abi.js";
import { sendContract } from "../write.js";

export async function createHolderAllowlist(token: Address, holders: Address[]) {
  const receipt = await sendContract({
    address: POLICY_REGISTRY,
    abi: policyRegistryAbi,
    functionName: "createPolicyWithAccounts",
    args: [account.address, 1, holders],
  });
  const [created] = parseEventLogs({ abi: policyRegistryAbi, logs: receipt.logs, eventName: "PolicyCreated" });
  const policyId = created.args.policyId;
  for (const policyScope of [scope("TRANSFER_SENDER_POLICY"), scope("TRANSFER_RECEIVER_POLICY")]) {
    await sendContract({ address: token, abi: b20Abi, functionName: "updatePolicy", args: [policyScope, policyId] });
  }
  const saved = await publicClient.readContract({ address: token, abi: b20Abi, functionName: "policyId", args: [scope("TRANSFER_RECEIVER_POLICY")] });
  if (saved !== policyId) throw new Error("Policy was not bound");
  return policyId;
}

The token returns the new policy ID for both transfer policy scopes.

An allowlist denies every account not in the policy. Seed intended holders before binding it, and retain the PolicyCreated ID. Membership batches are capped at 64 accounts per call; call updateAllowlist to add more after creation.

Update Membership

After creation, only the policy admin can add or remove accounts. Call updateAllowlist(policyId, true, accounts) to add and updateAllowlist(policyId, false, accounts) to remove. The change is visible to every token that references the policy on the next call. No second updatePolicy is needed on the token.

To combine a KYC allowlist with a sanctions blocklist, create an INTERSECT composite policy referencing both simple policies, then bind the composite ID to the token’s scopes. You can also pass an inverted policy ID as a composite child — for example, [kycId, invertedPolicyId(exclusionId)] — to express “KYC’d and not on the exclusion list” without duplicating members. See the B20 token standard for the full policy type reference.

See Also

Block an Account

Deny a specific address.

Policy Integration (B20 Standard)

Policy hooks in the B20 standard.