IPcl.addressLists

addressLists(
  PageRequest calldata pageRequest
) external view returns (AddressList[] memory lists, PageResponse memory pageResponse)

Pages through every shared address list registered on the PCL precompile, in numeric ID order. Each returned AddressList carries only metadata — { id, admin, status } — so this call is safe to run against networks with large registries; use addressListMembers(listId, …) to drill into one list's addresses. Both Active and Disabled lists are returned; filter on status client-side if a policy audit should ignore disabled ones.

Parameters

Name Type Required Description
pageRequest PageRequest ✓ Standard pagination input (key, offset, limit, countTotal, reverse). Pass { key: "0x", offset: 0, limit: 100, countTotal: false, reverse: false } for the first page; on subsequent calls carry pageResponse.nextKey forward in pageRequest.key.

Returns

Type: (AddressList[] lists, PageResponse pageResponse)

lists is the page of metadata tuples, ordered by numeric id ascending (or descending when reverse is set). pageResponse.nextKey is empty once the last page has been returned.

Errors

Code Name Description
InvalidPageRequest InvalidPageRequest Inherited from IPrecompile; raised only when the PageRequest tuple cannot be converted. Setting both key and offset is rejected by the pagination layer instead and arrives as QueryFailed("addressLists", reason). Encoded as InvalidPageRequest(string method, uint256 index, string value).
InvalidAddressListConfig InvalidAddressListConfig Reverts with InvalidAddressListConfig(uint64 listId) when a stored list's metadata is internally inconsistent during iteration.
AddressListStorageError AddressListStorageError Reverts with AddressListStorageError(uint64 listId) when the registry iterator fails. The underlying cause is kept off the wire.
ABISetupFailed ABISetupFailed Inherited from IPrecompile. Reverts with ABISetupFailed(string reason) when calldata cannot be decoded against the precompile ABI.

Examples

Page through every address list with viem

Walks the registry in 100-row pages until nextKey comes back empty. Only metadata crosses the wire; per-list addresses are fetched separately when needed.

import { createPublicClient, http, type Hex } from "viem";
import { iPclAbi, iPclAddress } from "@maroo-chain/contracts/abi/precompiles/pcl/IPcl";

const publicClient = createPublicClient({
  transport: http("https://rpc-testnet.maroo.io"),
});

let nextKey: Hex = "0x";
do {
  const [lists, page] = await publicClient.readContract({
    address: iPclAddress,
    abi: iPclAbi,
    functionName: "addressLists",
    args: [{
      key: nextKey,
      offset: 0n,
      limit: 100n,
      countTotal: false,
      reverse: false,
    }],
  });

  for (const list of lists) {
    // status: 1 = Active, 2 = Disabled.
    console.log(`list ${list.id} admin=${list.admin} status=${list.status}`);
  }
  nextKey = page.nextKey;
} while (nextKey !== "0x" && nextKey.length > 2);

Filter to Active lists in Solidity

Reads one page and returns only the IDs whose status is Active. Production audits should iterate until pageResponse.nextKey is empty.

// SPDX-License-Identifier: Apache-2.0
pragma solidity ^0.8.28;

import {IPcl, AddressList, AddressListStatus, PCL_CONTRACT} from "@maroo-chain/contracts/precompiles/pcl/IPcl.sol";
import {PageRequest, PageResponse} from "cosmos-evm-contracts/precompiles/common/Types.sol";

contract ActiveLists {
    function firstActivePage(uint64 limit) external view returns (uint64[] memory activeIds) {
        PageRequest memory req = PageRequest({
            key: "",
            offset: 0,
            limit: limit,
            countTotal: false,
            reverse: false
        });
        (AddressList[] memory lists, ) = PCL_CONTRACT.addressLists(req);

        uint256 count;
        activeIds = new uint64[](lists.length);
        for (uint256 i; i < lists.length; ++i) {
            if (lists[i].status == AddressListStatus.Active) {
                activeIds[count++] = lists[i].id;
            }
        }
        // Trim the trailing zero slots in place.
        assembly { mstore(activeIds, count) }
    }
}
ESC
Type to search