Replace ERC20Custodian with ERC20Freezable (#719)

Co-authored-by: Eric Lau <ericglau@outlook.com>

Author: typicalHuman

.changeset/smart-fans-build.md

@@ -0,0 +1,7 @@
+---
+'@openzeppelin/wizard': patch
+'@openzeppelin/wizard-common': minor
+'@openzeppelin/contracts-mcp': patch
+---
+
+**Breaking changes**: Solidity Stablecoin and RWA: Change `custodian` option to `freezable`. Replace ERC20Custodian with ERC20Freezable. 

packages/common/src/ai/descriptions/solidity.ts

@@ -54,7 +54,7 @@ export const solidityERC1155Descriptions = {
 };
 
 export const solidityStablecoinDescriptions = {
-  custodian:
+  freezable:
     'Whether authorized accounts can freeze and unfreeze accounts for regulatory or security purposes. This feature is experimental, not audited and is subject to change.',
   restrictions:
     'Whether to restrict certain users from transferring tokens, either via allowing or blocking them. This feature is experimental, not audited and is subject to change.',

packages/core/solidity/src/generate/stablecoin.ts

@@ -44,7 +44,7 @@ const erc20Full = {
 
 const stablecoinExtensions = {
   restrictions: [false, 'allowlist', 'blocklist'] as const,
-  custodian: booleans,
+  freezable: booleans,
   upgradeable: [false] as const,
 };
 

packages/core/solidity/src/stablecoin.test.ts

@@ -78,6 +78,11 @@ testStablecoin('stablecoin mintable with roles', {
   access: 'roles',
 });
 
+testStablecoin('stablecoin mintable with role managed', {
+  mintable: true,
+  access: 'managed',
+});
+
 testStablecoin('stablecoin callback', {
   callback: true,
 });
@@ -86,8 +91,8 @@ testStablecoin('stablecoin permit', {
   permit: true,
 });
 
-testStablecoin('stablecoin custodian', {
-  custodian: true,
+testStablecoin('stablecoin freezable', {
+  freezable: true,
 });
 
 testStablecoin('stablecoin allowlist', {
@@ -129,7 +134,7 @@ testStablecoin('stablecoin full', {
   crossChainBridging: 'custom',
   premintChainId: '10',
   restrictions: 'allowlist',
-  custodian: true,
+  freezable: true,
 });
 
 testAPIEquivalence('stablecoin API default');
@@ -154,7 +159,7 @@ testAPIEquivalence('stablecoin API full', {
   crossChainBridging: 'custom',
   premintChainId: '10',
   restrictions: 'allowlist',
-  custodian: true,
+  freezable: true,
 });
 
 test('stablecoin API assert defaults', async t => {

packages/core/solidity/src/stablecoin.test.ts.md

@@ -289,6 +289,31 @@ Generated by [AVA](https://avajs.dev).
     }␊
     `
 
+## stablecoin mintable with role managed
+
+> Snapshot 1
+
+    `// SPDX-License-Identifier: MIT␊
+    // Compatible with OpenZeppelin Contracts ^5.5.0␊
+    pragma solidity ^0.8.27;␊
+    ␊
+    import {AccessManaged} from "@openzeppelin/contracts/access/manager/AccessManaged.sol";␊
+    import {ERC20} from "@openzeppelin/contracts/token/ERC20/ERC20.sol";␊
+    import {ERC20Permit} from "@openzeppelin/contracts/token/ERC20/extensions/ERC20Permit.sol";␊
+    ␊
+    contract MyStablecoin is ERC20, AccessManaged, ERC20Permit {␊
+        constructor(address initialAuthority)␊
+            ERC20("MyStablecoin", "MST")␊
+            AccessManaged(initialAuthority)␊
+            ERC20Permit("MyStablecoin")␊
+        {}␊
+    ␊
+        function mint(address to, uint256 amount) public restricted {␊
+            _mint(to, amount);␊
+        }␊
+    }␊
+    `
+
 ## stablecoin callback
 
 > Snapshot 1
@@ -322,7 +347,7 @@ Generated by [AVA](https://avajs.dev).
     }␊
     `
 
-## stablecoin custodian
+## stablecoin freezable
 
 > Snapshot 1
 
@@ -331,26 +356,26 @@ Generated by [AVA](https://avajs.dev).
     pragma solidity ^0.8.27;␊
     ␊
     import {ERC20} from "@openzeppelin/contracts/token/ERC20/ERC20.sol";␊
-    import {ERC20Custodian} from "@openzeppelin/community-contracts/token/ERC20/extensions/ERC20Custodian.sol";␊
+    import {ERC20Freezable} from "@openzeppelin/community-contracts/token/ERC20/extensions/ERC20Freezable.sol";␊
     import {ERC20Permit} from "@openzeppelin/contracts/token/ERC20/extensions/ERC20Permit.sol";␊
     import {Ownable} from "@openzeppelin/contracts/access/Ownable.sol";␊
     ␊
-    contract MyStablecoin is ERC20, ERC20Permit, ERC20Custodian, Ownable {␊
+    contract MyStablecoin is ERC20, ERC20Permit, ERC20Freezable, Ownable {␊
         constructor(address initialOwner)␊
             ERC20("MyStablecoin", "MST")␊
             ERC20Permit("MyStablecoin")␊
             Ownable(initialOwner)␊
         {}␊
     ␊
-        function _isCustodian(address user) internal view override returns (bool) {␊
-            return user == owner();␊
+        function freeze(address user, uint256 amount) public onlyOwner {␊
+            _setFrozen(user, amount);␊
         }␊
     ␊
         // The following functions are overrides required by Solidity.␊
     ␊
         function _update(address from, address to, uint256 value)␊
             internal␊
-            override(ERC20, ERC20Custodian)␊
+            override(ERC20, ERC20Freezable)␊
         {␊
             super._update(from, to, value);␊
         }␊
@@ -586,23 +611,23 @@ Generated by [AVA](https://avajs.dev).
     import {ERC20} from "@openzeppelin/contracts/token/ERC20/ERC20.sol";␊
     import {ERC20Bridgeable} from "@openzeppelin/contracts/token/ERC20/extensions/draft-ERC20Bridgeable.sol";␊
     import {ERC20Burnable} from "@openzeppelin/contracts/token/ERC20/extensions/ERC20Burnable.sol";␊
-    import {ERC20Custodian} from "@openzeppelin/community-contracts/token/ERC20/extensions/ERC20Custodian.sol";␊
     import {ERC20FlashMint} from "@openzeppelin/contracts/token/ERC20/extensions/ERC20FlashMint.sol";␊
+    import {ERC20Freezable} from "@openzeppelin/community-contracts/token/ERC20/extensions/ERC20Freezable.sol";␊
     import {ERC20Pausable} from "@openzeppelin/contracts/token/ERC20/extensions/ERC20Pausable.sol";␊
     import {ERC20Permit} from "@openzeppelin/contracts/token/ERC20/extensions/ERC20Permit.sol";␊
     import {ERC20Restricted} from "@openzeppelin/community-contracts/token/ERC20/extensions/ERC20Restricted.sol";␊
     import {ERC20Votes} from "@openzeppelin/contracts/token/ERC20/extensions/ERC20Votes.sol";␊
     import {Nonces} from "@openzeppelin/contracts/utils/Nonces.sol";␊
     ␊
-    contract MyStablecoin is ERC20, ERC20Bridgeable, AccessControl, ERC20Burnable, ERC20Pausable, ERC1363, ERC20Permit, ERC20Votes, ERC20FlashMint, ERC20Custodian, ERC20Restricted {␊
+    contract MyStablecoin is ERC20, ERC20Bridgeable, AccessControl, ERC20Burnable, ERC20Pausable, ERC1363, ERC20Permit, ERC20Votes, ERC20FlashMint, ERC20Freezable, ERC20Restricted {␊
         bytes32 public constant TOKEN_BRIDGE_ROLE = keccak256("TOKEN_BRIDGE_ROLE");␊
         error Unauthorized();␊
         bytes32 public constant PAUSER_ROLE = keccak256("PAUSER_ROLE");␊
         bytes32 public constant MINTER_ROLE = keccak256("MINTER_ROLE");␊
-        bytes32 public constant CUSTODIAN_ROLE = keccak256("CUSTODIAN_ROLE");␊
+        bytes32 public constant FREEZER_ROLE = keccak256("FREEZER_ROLE");␊
         bytes32 public constant LIMITER_ROLE = keccak256("LIMITER_ROLE");␊
     ␊
-        constructor(address defaultAdmin, address tokenBridge, address recipient, address pauser, address minter, address custodian, address limiter)␊
+        constructor(address defaultAdmin, address tokenBridge, address recipient, address pauser, address minter, address freezer, address limiter)␊
             ERC20("MyStablecoin", "MST")␊
             ERC20Permit("MyStablecoin")␊
         {␊
@@ -613,7 +638,7 @@ Generated by [AVA](https://avajs.dev).
             }␊
             _grantRole(PAUSER_ROLE, pauser);␊
             _grantRole(MINTER_ROLE, minter);␊
-            _grantRole(CUSTODIAN_ROLE, custodian);␊
+            _grantRole(FREEZER_ROLE, freezer);␊
             _grantRole(LIMITER_ROLE, limiter);␊
         }␊
     ␊
@@ -633,8 +658,8 @@ Generated by [AVA](https://avajs.dev).
             _mint(to, amount);␊
         }␊
     ␊
-        function _isCustodian(address user) internal view override returns (bool) {␊
-            return hasRole(CUSTODIAN_ROLE, user);␊
+        function freeze(address user, uint256 amount) public onlyRole(FREEZER_ROLE) {␊
+            _setFrozen(user, amount);␊
         }␊
     ␊
         function isUserAllowed(address user) public view override returns (bool) {␊
@@ -653,7 +678,7 @@ Generated by [AVA](https://avajs.dev).
     ␊
         function _update(address from, address to, uint256 value)␊
             internal␊
-            override(ERC20, ERC20Pausable, ERC20Votes, ERC20Custodian, ERC20Restricted)␊
+            override(ERC20, ERC20Pausable, ERC20Votes, ERC20Freezable, ERC20Restricted)␊
         {␊
             super._update(from, to, value);␊
         }␊

packages/core/solidity/src/stablecoin.test.ts.snap

@@ -1,6 +1,6 @@
 import type { Contract, ContractBuilder } from './contract';
 import type { Access } from './set-access-control';
-import { setAccessControl, requireAccessControl } from './set-access-control';
+import { requireAccessControl } from './set-access-control';
 import { defineFunctions } from './utils/define-functions';
 import { printContract } from './print';
 import type { ERC20Options } from './erc20';
@@ -13,15 +13,15 @@ import {
 
 export interface StablecoinOptions extends ERC20Options {
   restrictions?: false | 'allowlist' | 'blocklist';
-  custodian?: boolean;
+  freezable?: boolean;
 }
 
 export const defaults: Required<StablecoinOptions> = {
   ...erc20defaults,
   name: 'MyStablecoin',
   symbol: 'MST',
   restrictions: false,
-  custodian: false,
+  freezable: false,
 } as const;
 
 function withDefaults(opts: StablecoinOptions): Required<StablecoinOptions> {
@@ -30,7 +30,7 @@ function withDefaults(opts: StablecoinOptions): Required<StablecoinOptions> {
     name: opts.name ?? defaults.name,
     symbol: opts.symbol ?? defaults.symbol,
     restrictions: opts.restrictions ?? defaults.restrictions,
-    custodian: opts.custodian ?? defaults.custodian,
+    freezable: opts.freezable ?? defaults.freezable,
   };
 }
 
@@ -39,7 +39,7 @@ export function printStablecoin(opts: StablecoinOptions = defaults): string {
 }
 
 export function isAccessControlRequired(opts: Partial<StablecoinOptions>): boolean {
-  return opts.mintable || opts.restrictions !== false || opts.custodian || opts.pausable || opts.upgradeable === 'uups';
+  return opts.mintable || opts.restrictions !== false || opts.freezable || opts.pausable || opts.upgradeable === 'uups';
 }
 
 export function buildStablecoin(opts: StablecoinOptions): Contract {
@@ -50,8 +50,8 @@ export function buildStablecoin(opts: StablecoinOptions): Contract {
 
   const c = buildERC20(allOpts);
 
-  if (allOpts.custodian) {
-    addCustodian(c, allOpts.access);
+  if (allOpts.freezable) {
+    addFreezable(c, allOpts.access);
   }
 
   if (allOpts.restrictions) {
@@ -87,63 +87,33 @@ function addRestrictions(c: ContractBuilder, access: Access, mode: 'allowlist' |
   c.addFunctionCode(`_resetUser(user);`, removeFn);
 }
 
-function addCustodian(c: ContractBuilder, access: Access) {
-  const ERC20Custodian = {
-    name: 'ERC20Custodian',
-    path: '@openzeppelin/community-contracts/token/ERC20/extensions/ERC20Custodian.sol',
+function addFreezable(c: ContractBuilder, access: Access) {
+  const ERC20Freezable = {
+    name: 'ERC20Freezable',
+    path: '@openzeppelin/community-contracts/token/ERC20/extensions/ERC20Freezable.sol',
   };
 
-  c.addParent(ERC20Custodian);
-  c.addOverride(ERC20Custodian, functions._update);
-  c.addOverride(ERC20Custodian, functions._isCustodian);
+  c.addParent(ERC20Freezable);
+  c.addOverride(ERC20Freezable, functions._update);
 
   if (access === false) {
     access = 'ownable';
   }
 
-  setAccessControl(c, access);
-
-  switch (access) {
-    case 'ownable': {
-      c.setFunctionBody([`return user == owner();`], functions._isCustodian);
-      break;
-    }
-    case 'roles': {
-      const roleOwner = 'custodian';
-      const roleId = 'CUSTODIAN_ROLE';
-      const addedConstant = c.addConstantOrImmutableOrErrorDefinition(
-        `bytes32 public constant ${roleId} = keccak256("${roleId}");`,
-      );
-      if (roleOwner && addedConstant) {
-        c.addConstructorArgument({ type: 'address', name: roleOwner });
-        c.addConstructorCode(`_grantRole(${roleId}, ${roleOwner});`);
-      }
-      c.setFunctionBody([`return hasRole(CUSTODIAN_ROLE, user);`], functions._isCustodian);
-      break;
-    }
-    case 'managed': {
-      c.addImportOnly({
-        name: 'AuthorityUtils',
-        path: `@openzeppelin/contracts/access/manager/AuthorityUtils.sol`,
-      });
-      const logic = [
-        `(bool immediate,) = AuthorityUtils.canCallWithDelay(authority(), user, address(this), bytes4(_msgData()[0:4]));`,
-        `return immediate;`,
-      ];
-      c.setFunctionBody(logic, functions._isCustodian);
-      break;
-    }
-  }
+  const freezeFn = functions.freeze;
+  requireAccessControl(c, freezeFn, access, 'FREEZER', 'freezer');
+  c.setFunctionBody([`_setFrozen(user, amount);`], freezeFn);
 }
 
 const functions = {
   ...erc20functions,
   ...defineFunctions({
-    _isCustodian: {
-      kind: 'internal' as const,
-      args: [{ name: 'user', type: 'address' }],
-      returns: ['bool'],
-      mutability: 'view' as const,
+    freeze: {
+      kind: 'public' as const,
+      args: [
+        { name: 'user', type: 'address' },
+        { name: 'amount', type: 'uint256' },
+      ],
     },
 
     allowUser: {

packages/core/solidity/src/stablecoin.ts

@@ -108,7 +108,7 @@ export const stablecoinSchema = {
     .or(z.literal('blocklist'))
     .optional()
     .describe(solidityStablecoinDescriptions.restrictions),
-  custodian: z.boolean().optional().describe(solidityStablecoinDescriptions.custodian),
+  freezable: z.boolean().optional().describe(solidityStablecoinDescriptions.freezable),
 } as const satisfies z.ZodRawShape;
 
 export const rwaSchema = stablecoinSchema;

packages/mcp/src/solidity/schemas.ts

@@ -54,7 +54,7 @@ test('all', async t => {
     crossChainBridging: 'custom',
     premintChainId: '10',
     restrictions: 'allowlist',
-    custodian: true,
+    freezable: true,
     namespacePrefix: 'myProject',
     info: {
       license: 'MIT',

packages/mcp/src/solidity/tools/rwa.test.ts

@@ -26,7 +26,7 @@ export function registerSolidityRWA(server: McpServer) {
       access,
       info,
       restrictions,
-      custodian,
+      freezable,
     }) => {
       const opts: StablecoinOptions = {
         name,
@@ -44,7 +44,7 @@ export function registerSolidityRWA(server: McpServer) {
         access,
         info,
         restrictions,
-        custodian,
+        freezable,
       };
       return {
         content: [