PCL 주소 리스트
PCL의 allow-list와 deny-list 정책이 listId로 참조하는 공유 주소 레지스트리입니다. 리스트 하나가 여러 정책을 지원하며, 멤버가 바뀌어도 PolicySet을 다시 작성할 필요가 없습니다.
주소 리스트는 PCL의 독립 레지스트리 항목입니다. 숫자 listId, 현재 admin, 상태(Active 또는 Disabled), 그리고 EVM 주소 멤버 집합으로 구성됩니다. allow-list와 deny-list 정책은 주소를 내부에 담지 않고 listId와 AddressListTarget(From, To, Both)만 가진 뒤 평가 시점에 리스트를 읽습니다. 리스트 하나가 여러 정책을 지원하며, 리스트 관리자가 PolicySet을 건드리지 않고 멤버를 추가하거나 제거할 수 있고, 리스트 관리자가 호출 한 번으로 리스트의 사용을 멈출 수도 있습니다. 다만 Disabled는 참조하는 정책을 끄는 것이 아니라, 그 정책들이 모두 AddressListDisabled(listId)로 revert되게 하므로 거절 쪽으로 닫힙니다. 이 레지스트리는 v0.10의 인라인 DENYLIST_POLICY를 대체하며, 해당 ID는 이제 예약되어 있습니다.
아키텍처
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; 공유 주소 리스트는 PCL 프리컴파일의 레지스트리에 저장되며, PolicySet은 listId로 이를 참조하고 평가 시점에 멤버십을 읽습니다. 현재 admin만 멤버를 수정하거나 리스트 상태를 변경할 수 있습니다.
Solidity 인터페이스
IPcl.sol에서 가져왔습니다. 리스트는 메타데이터만 담으며, 멤버 집합은 별도의 페이지네이션 쿼리로 조회합니다. AddressListTarget enum은 참조 정책이 사용하며 리스트 자체에는 들어가지 않습니다.enum AddressListTarget { Unspecified, From, To, Both }
enum AddressListStatus { Unspecified, Active, Disabled }
struct AddressList {
uint64 id;
address admin;
AddressListStatus status;
}
// 관리 (admin 전용)
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;
// 조회
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); 리스트 생성과 멤버 채우기
createAddressList()는 다음 listId를 할당하고 호출자를 admin으로 기록합니다. 리스트는 Active 상태이자 빈 상태로 시작합니다. Solidity에서 PCL 프리컴파일은 EVM 바이트코드가 없으므로, 반환값이 없는 함수(예: updateAddressList)를 고수준으로 호출하면 빈 데이터로 revert됩니다. 이런 함수는 저수준 call로 호출합니다. createAddressList는 값을 반환하므로 일반 호출 문법이 그대로 동작합니다. viem이나 ethers로 EOA에서 호출할 때는 코드 크기 검사가 없으므로 두 함수 모두 일반 writeContract로 호출하면 됩니다.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) {
// 값을 반환하므로 고수준 호출이 그대로 컴파일됩니다.
listId = pcl.createAddressList();
// updateAddressList는 반환값이 없으므로, 프리컴파일의 코드 크기 검사를
// 피하기 위해 저수준으로 호출합니다.
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)) } }
} 정책이 리스트를 참조하는 방식
AllowListPolicy와 DenyListPolicy는 모두 { listId, target }을 가집니다. target은 검사할 호출 엔드포인트를 선택합니다. From은 송신자, To는 수신자, Both는 양쪽입니다. AllowListPolicy는 컨트랙트 범위 전용이며, 선택된 엔드포인트가 모두 멤버일 때만 트랜잭션을 허용합니다. 테스트넷에는 그 템플릿인 ALLOW_LIST_POLICY가 아직 등록되지 않았으므로, 바인딩하면 PolicyNotRegistered("ALLOW_LIST_POLICY")로 revert됩니다. DenyListPolicy는 전역 또는 컨트랙트 범위에서 사용할 수 있고, 선택된 엔드포인트 중 하나라도 멤버이면 트랜잭션을 거절합니다. 멤버 여부는 평가 시점에 읽으므로, 리스트를 갱신하면 그 리스트를 참조하는 모든 정책에 즉시 반영됩니다.import {
IPcl, PolicySet, AllowListPolicy, DenyListPolicy, AddressListTarget
} from "@maroo-chain/contracts/precompiles/pcl/IPcl.sol";
// 어느 쪽 엔드포인트든 리스트에 있으면 거절하는 deny-list PolicySet을 만듭니다.
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 회전과 상태 관리
리스트는 현재 admin만 변경할 수 있습니다.
updateAddressList, changeAddressListAdmin, setAddressListStatus는 모두 호출자가 list.admin과 일치해야 하며, 그렇지 않으면 타입 지정 오류 Unauthorized()로 revert되며, IPcl ABI로 디코드할 수 있습니다. changeAddressListAdmin은 소유권을 원자적으로 넘깁니다. 호출이 성공하는 순간 이전 admin은 접근 권한을 잃습니다. 상태를 Disabled로 두면 리스트는 조회할 수 있지만, 이 리스트를 참조하는 모든 정책이 평가 시점에 타입 지정 오류 AddressListDisabled(uint64 listId)로 revert됩니다. 즉 거절 쪽으로 닫힙니다. Disabled 리스트를 참조하는 정책은 평가하는 모든 호출을 거절하고, 그런 리스트를 참조하는 전역 DENY_LIST_POLICY는 체인의 모든 트랜잭션을 거절합니다. 리스트가 정책 트리의 어디에 있든 마찬가지입니다. 체인은 정책을 평가하기 전에 그 정책이 참조하는 모든 리스트를 다시 검사하므로, OR 안에 있는 Disabled 리스트도 앞의 자식이 통과하는지와 관계없이 AddressListDisabled로 호출을 거절합니다. 없거나 손상된 리스트도 같은 방식으로 걸립니다(AddressListNotFound / InvalidAddressListConfig). 반면 NotInAddressList 같은 일반 거절은 OR의 다음 자식으로 넘어갑니다. 리스트 적용을 멈추려면 리스트를 비활성화하지 말고 그 리스트를 참조하는 정책을 제거하거나 교체합니다. 다시 사용하려면 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),
});
// 공유 제재 리스트를 비활성화합니다. 이 리스트를 참조하는 모든 정책은
// 다시 활성화될 때까지 AddressListDisabled(listId)로 revert됩니다.
await wallet.writeContract({
address: iPclAddress,
abi: iPclAbi,
functionName: "setAddressListStatus",
args: [listId, 2 /* Disabled */],
}); 리스트 상태 조회
조회 메서드는 네 가지입니다.
addressList(listId)는 메타데이터(id, admin, status)를 반환합니다. addressLists(pageRequest)는 등록된 모든 리스트의 메타데이터를 숫자 id 순으로 페이지네이션합니다. addressListMembers(listId, pageRequest)는 한 리스트의 멤버를 페이지네이션합니다. isAddressListed(listId, account)는 리스트 상태와 무관하게 멤버 여부를 bool로 돌려줍니다. 비활성화된 리스트에 대한 멤버 조회도 현재 멤버십을 그대로 반환합니다. 비활성 상태는 정책 평가에서만 관찰됩니다.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 }],
}); 범위 규칙과 v0.10 이전 마이그레이션
AllowListPolicy는 컨트랙트 범위 전용입니다. 전역 범위에서 빈 리스트는 체인의 모든 트랜잭션을 차단하므로 전역 범위 사용은 InvalidAddressListConfig(listId)로 거절됩니다. DenyListPolicy는 전역과 컨트랙트 범위 어디에서나 사용할 수 있습니다. v0.10의 인라인 DENYLIST_POLICY(자체 address[]를 담던 UnitPolicy 래퍼)는 제거되었고 해당 템플릿 ID는 예약되어 있습니다. 테스트넷은 이 ID를 UnknownPolicyType으로 거절합니다. v0.11 업그레이드 핸들러는 저장된 모든 인라인 denylist를 마이그레이션합니다. 멤버를 담은 새 주소 리스트를 만들고, 그 listId를 참조하는 DENY_LIST_POLICY로 정책을 교체합니다. 전역 정책에서 마이그레이션된 리스트는 정책 관리자(getParams().policyAdmin)가 관리하고, 컨트랙트 정책에서 마이그레이션된 리스트는 그 컨트랙트 설정의 admin이 관리합니다. 그 admin이 이미 포기된 상태(0 주소)였다면 리스트는 변경할 수 없으며, 누구도 멤버를 바꾸거나 관리자를 넘기거나 비활성화할 수 없습니다. 폐지된 반복 정책 형식으로 저장된 정책 세트는 마이그레이션되지 않고 삭제되었습니다.