PCL Address Lists
Shared, independently mutable address registries that PCL allow-list and deny-list policies reference by listId — one list can back many policies, and members change without rewriting a PolicySet.
An address list is a standalone registry entry in PCL: a numeric listId, a current admin, a status (Active or Disabled), and a membership set of EVM addresses. Allow-list and deny-list policies do not carry addresses inline — they hold a listId and an AddressListTarget (From, To, or Both) and read the list at evaluation time. This lets the same list back many policies, lets the list admin add or remove members without touching any PolicySet, and lets the list admin take a list out of service in one call. Disabled does not switch the referencing policies off: each of them then reverts with AddressListDisabled(listId), so they fail closed. The registry replaces the v0.10 inline DENYLIST_POLICY, whose id is now reserved.
Architecture
graph LR
A["dApp caller"] --> B["PCL-wrapped proxy"]
B --> C["PCL precompile<br/>0x1000...0005"]
C --> D["Address list registry<br/>(listId → members)"]
E["List admin EOA"] -->|"createAddressList<br/>updateAddressList<br/>setAddressListStatus"| C
F["PolicySet<br/>{templateId, {listId, target}}"] -.->|references| D
C --> G{"member check"}
G -->|"allow: member<br/>deny: not member"| H["admit"]
G -->|"allow: not member<br/>deny: member"| I["revert ReasonCode"]
classDef evm fill:#0096AA,stroke:#0096AA,color:#fff;
classDef precompile fill:#FF8C50,stroke:#FF8C50,color:#fff;
class A,B,E,F,H,I evm;
class C,D,G precompile; A shared address list lives in the PCL precompile's registry; PolicySets reference it by listId and read membership at evaluation time. Only the current list admin can mutate members or change the list's status.
The Solidity surface
IPcl.sol. A list carries only metadata — the member set lives in a separate paginated query. The AddressListTarget enum is used by the referencing policies, not the list itself.enum AddressListTarget { Unspecified, From, To, Both }
enum AddressListStatus { Unspecified, Active, Disabled }
struct AddressList {
uint64 id;
address admin;
AddressListStatus status;
}
// Management (admin-only)
function createAddressList() external returns (uint64 listId);
function updateAddressList(uint64 listId, address[] calldata add, address[] calldata remove) external;
function changeAddressListAdmin(uint64 listId, address newAdmin) external;
function setAddressListStatus(uint64 listId, AddressListStatus status) external;
// Queries
function addressList(uint64 listId) external view returns (AddressList memory);
function addressLists(PageRequest calldata pageRequest)
external view returns (AddressList[] memory lists, PageResponse memory pageResponse);
function addressListMembers(uint64 listId, PageRequest calldata pageRequest)
external view returns (address[] memory members, PageResponse memory pageResponse);
function isAddressListed(uint64 listId, address account) external view returns (bool); Creating and populating a list
createAddressList() allocates the next listId and records the caller as its admin. The list starts Active and empty. From Solidity the PCL precompile has no EVM bytecode, so a high-level call to a function that returns nothing (like updateAddressList) reverts with empty data — issue those low-level. createAddressList returns a value, so the normal syntax works. From an EOA using viem or ethers there is no code-size check and both calls are plain writeContracts.import {IPcl, AddressListStatus} from "@maroo-chain/contracts/precompiles/pcl/IPcl.sol";
IPcl constant pcl = IPcl(0x1000000000000000000000000000000000000005);
function createAndSeed(address[] memory sanctioned) external returns (uint64 listId) {
// Returns a value, so the high-level call compiles.
listId = pcl.createAddressList();
// updateAddressList returns nothing: call low-level to avoid solc's
// code-size check against the precompile.
address[] memory empty = new address[](0);
(bool ok, bytes memory ret) = address(pcl).call(
abi.encodeCall(IPcl.updateAddressList, (listId, sanctioned, empty))
);
if (!ok) { assembly { revert(add(ret, 32), mload(ret)) } }
} How policies reference a list
AllowListPolicy and DenyListPolicy both carry { listId, target }. The target selects which endpoints of the call to inspect: From for the sender, To for the recipient, Both for either. An AllowListPolicy is contract-scope only — a transaction is admitted only if the selected endpoints are all members. On the testnet its template, ALLOW_LIST_POLICY, is not registered yet, so binding one reverts with PolicyNotRegistered("ALLOW_LIST_POLICY"). A DenyListPolicy is usable at global or contract scope and rejects a transaction if any selected endpoint is a member. Membership is read at evaluation time, so updating the list immediately affects every policy that references it.import {
IPcl, PolicySet, AllowListPolicy, DenyListPolicy, AddressListTarget
} from "@maroo-chain/contracts/precompiles/pcl/IPcl.sol";
// Build a deny-list PolicySet that rejects a call when either side is listed.
function buildDenyPolicy(uint64 listId) internal pure returns (PolicySet memory) {
DenyListPolicy memory dl = DenyListPolicy({
listId: listId,
target: AddressListTarget.Both
});
return PolicySet({
templateId: "DENY_LIST_POLICY",
policy: abi.encode(dl),
selector: ""
});
} Admin rotation and status
updateAddressList, changeAddressListAdmin, and setAddressListStatus all require the caller to match list.admin, otherwise they revert with the typed error Unauthorized(), which decodes against the IPcl ABI. changeAddressListAdmin passes ownership atomically; the previous admin loses access the instant the call succeeds. Setting the status to Disabled keeps the list readable but makes every referencing policy revert with the typed error AddressListDisabled(uint64 listId) at evaluation time — it fails CLOSED: a policy over a Disabled list rejects every call it evaluates, and a global DENY_LIST_POLICY over one rejects every transaction on the chain. That holds wherever the list sits in the policy tree: before evaluating a policy, the chain re-checks every list it references, so a Disabled list inside an OR rejects the call with AddressListDisabled even when an earlier child would pass. A missing or corrupt list is caught the same way (AddressListNotFound / InvalidAddressListConfig); an ordinary rejection such as NotInAddressList still falls through to the next OR child. To stop enforcing a list, remove or replace the policies that reference it instead of disabling it. Re-enable with setAddressListStatus(listId, AddressListStatus.Active).import { createWalletClient, http } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { iPclAbi, iPclAddress } from "@maroo-chain/contracts/abi/precompiles/pcl/IPcl";
const admin = privateKeyToAccount(process.env.ADMIN_KEY as `0x${string}`);
const wallet = createWalletClient({
account: admin,
transport: http(process.env.MAROO_RPC_URL),
});
// Disable a shared sanctions list — every referencing policy now reverts
// with AddressListDisabled(listId) until it is re-activated.
await wallet.writeContract({
address: iPclAddress,
abi: iPclAbi,
functionName: "setAddressListStatus",
args: [listId, 2 /* Disabled */],
}); Reading list state
addressList(listId) returns metadata (id, admin, status); addressLists(pageRequest) paginates every registered list's metadata ordered by numeric id; addressListMembers(listId, pageRequest) paginates the members of one list; isAddressListed(listId, account) returns a plain boolean regardless of list status. A member query against a disabled list still returns the current membership — only policy evaluation observes the disabled state.import { createPublicClient, http } from "viem";
import { iPclAbi, iPclAddress } from "@maroo-chain/contracts/abi/precompiles/pcl/IPcl";
const publicClient = createPublicClient({ transport: http(process.env.MAROO_RPC_URL) });
const meta = await publicClient.readContract({
address: iPclAddress,
abi: iPclAbi,
functionName: "addressList",
args: [listId],
});
// meta.status: 1 = Active, 2 = Disabled
const [members, page] = await publicClient.readContract({
address: iPclAddress,
abi: iPclAbi,
functionName: "addressListMembers",
args: [listId, { key: "0x", offset: 0n, limit: 100n, countTotal: true, reverse: false }],
}); Scope rules and migration from v0.10
AllowListPolicy is contract-scope only — it is rejected at global scope with InvalidAddressListConfig(listId) because an empty list would trap every transaction on the chain. DenyListPolicy is accepted at either scope. The retired v0.10 inline DENYLIST_POLICY (whose UnitPolicy wrapper carried its own address[]) is removed and its template id is reserved; the testnet rejects it with UnknownPolicyType. The v0.11 upgrade handler migrates every stored inline denylist by creating a new address list seeded with its members and replacing the policy with a DENY_LIST_POLICY that references the new listId. A list migrated from a global policy is administered by the policy admin (getParams().policyAdmin); one migrated from a contract policy is administered by that contract config's admin. Where that admin had been renounced (the zero address), the list is immutable: nobody can update it, hand it over or disable it. Policy sets stored in the retired repeated-policy layout were deleted, not migrated.