ALLOW_LIST_POLICY

component compliance

Contract-scope policy that admits a call only when the selected endpoints (From, To, or Both) are members of a shared address list.

ALLOW_LIST_POLICY is a contract-scoped PCL policy template that references a shared address list by listId and admits a call only when every selected endpoint (From, To, or both) is a member of that list. It cannot be used at global scope — an empty list there would trap every transaction on the chain. Unlike DENY_LIST_POLICY, which denies on membership, this template denies on absence: if an inspected endpoint is not listed the call reverts with NotInAddressList(listId, account). The policy carries only the list reference and the target; membership is read from the registry at evaluation time, so updates to the list take effect immediately on every referencing policy. It is not registered on the testnet yet (v0.11.1), so binding it there reverts with PolicyNotRegistered("ALLOW_LIST_POLICY").

Parameter struct

From IPcl.sol:
enum AddressListTarget { Unspecified, From, To, Both }

struct AllowListPolicy {
    uint64 listId;              // id of a shared address list (see IPcl.createAddressList)
    AddressListTarget target;   // which endpoint(s) of the call to inspect
}

// Template id: "ALLOW_LIST_POLICY"
// ABI tuple: (uint64, uint8)
Testnet availability. Of the two address-list templates only DENY_LIST_POLICY is registered on the testnet (v0.11.1). ALLOW_LIST_POLICY ships in the chain code but stays unusable until the policy admin registers it with registerPolicyTemplate; until then binding it reverts with PolicyNotRegistered("ALLOW_LIST_POLICY"). Check first with policyTemplate("ALLOW_LIST_POLICY"), which reverts with PolicyTemplateNotFound while the template is missing.

listId must reference an existing list — binding the policy to a missing id reverts with AddressListNotFound(listId). A Disabled list can be bound, but while it is Disabled every evaluation of the policy reverts with AddressListDisabled(listId). target must be one of From, To, or Both. The policy's own shape is checked first, before any list is looked up: a listId of 0, or a target that is Unspecified or out of range, reverts the binding call with InvalidParameter(bytes) — not InvalidAddressListConfig. Binding it at global scope reverts with InvalidAddressListConfig(listId).

Evaluation and target semantics

At evaluation time PCL reads the relevant endpoints from the call. From checks only the sender; To checks only the recipient; Both checks each independently. For every endpoint the policy inspects, if that account is NOT a member of the list the policy rejects with NotInAddressList(listId, account). All inspected endpoints must be members for the policy to admit. Because this template is contract-scope only, it fires only when the call goes through a PCL-wrapped proxy that has an ALLOW_LIST_POLICY bound to it (either in the proxy's preCall/postCall, through a trusted EntryPoint, or inside the policy-aware Privacy precompile).
import { encodeAbiParameters, toHex } from "viem";

// Admit only if BOTH sender and recipient are on the list.
const allowBytes = encodeAbiParameters(
  [
    { type: "uint64", name: "listId" },
    { type: "uint8",  name: "target" },  // 3 = Both
  ],
  [listId, 3],
);

const policySet = {
  templateId: "ALLOW_LIST_POLICY",
  policy:     allowBytes,
  selector:   toHex("", { size: 0 }),  // all calls in this scope
};

Binding to a contract and managing membership

ALLOW_LIST_POLICY is bound to a specific PCL-wrapped proxy through IPcl.changeContractPolicies. The caller must be the current contract policy admin. The referenced list is managed independently — the list admin (which may or may not be the same account as the contract policy admin) controls membership via IPcl.updateAddressList(listId, add, remove) and does not need to update the PolicySet when the member set changes. To rotate ownership of the list to a new account, use IPcl.changeAddressListAdmin. IPcl.setAddressListStatus(listId, AddressListStatus.Disabled) does NOT pause the policy — every policy referencing that list then reverts with AddressListDisabled(listId) until the list is re-activated, so the contract rejects every call the policy covers. This holds wherever the list sits in the policy tree: before evaluating, the chain re-checks every list the policy references, so a Disabled list inside an OR rejects the call even when an earlier child would pass. To stop enforcing the allow list, remove or replace the policy.
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),
});

// TODO: replace with the real proxy address before production.
const proxyAddress = "0x8f3ac2b1d9e74c05a6b18fe27dc4913e5a0f7b62";

await wallet.writeContract({
  address: iPclAddress,
  abi: iPclAbi,
  functionName: "changeContractPolicies",
  args: [{
    _contract: proxyAddress,
    admin:     admin.address,
    policies:  [policySet],
  }],
});

ReasonCodes

Evaluation can revert with any of these typed errors declared on IPcl — decode them with decodeErrorResult using iPclAbi:

ReasonCodeWhen it fires
NotInAddressList(uint64 listId, address account)an inspected endpoint is not a member of the list
AddressListNotFound(uint64 listId)the referenced list does not exist
AddressListDisabled(uint64 listId)the referenced list's status is Disabled
InvalidAddressListConfig(uint64 listId)the referenced list's stored record fails an integrity check (a corrupt registry). A zero listId or a bad target never gets here — binding rejects it with InvalidParameter
AddressListStorageError(uint64 listId)an unexpected storage read failure (should not occur on healthy nodes)
ESC
Type to search