Contract API
Solidity-callable precompile interfaces covering OKRW (stablecoin), PCL (compliance), EAS (attestation), Agent (ERC-8004 indexing) and Privacy (shielded OKRW).
IPcl · Policy management
Register, query, and change policy templates and per-contract policy configurations.
IPcl.registerPolicyTemplate / removePolicyTemplate Chain-wide policy admin operations that add or remove one of the built-in PCL policy templates from the active registry. registerPolicyTemplate makes a template ID available for instantiation inside a PolicySet; removePolicyTemplate withdraws it. Only the address returned by IPcl.policyAdmin() may call these — other callers revert with Unauthorized(). Both calls, when made by the admin against the PCL precompile, bypass PCL policy evaluation via the admin recovery path, so they cannot be blocked by a misconfigured global policy that would otherwise reject the admin's own address.
IPcl.contractPolicies / removeContractPolicies Two operations against the contract-scoped policy binding. contractPolicies(address) is a view returning the currently bound ContractPolicyConfig (or a zeroed struct if none is bound). removeContractPolicies(address) clears the PolicySet[] on a PCL-wrapped proxy — it does NOT remove the contract-admin binding itself, so the admin retains authority to re-attach policies later via changeContractPolicies. Two guardrails: (1) only the current contract admin can remove; (2) a policy-aware precompile — a set fixed in the chain binary, currently only the Privacy precompile at 0x100000000000000000000000000000000000000b — cannot be cleared this way — the call reverts with CannotEmpty("policy-aware precompile policies"). To relax rules on a policy-aware precompile, use changeContractPolicies with a permissive PolicySet instead.
IPcl.policyTemplate Returns the descriptor for a registered PCL policy template. The returned PolicyTemplate struct carries only three fields — templateId, name, and description — and is metadata-only: it does not embed a machine-readable parameter schema. To learn a template's parameter shape, consult the template-specific struct in IPcl.sol (for example DenyListPolicy, EasPolicy). If the requested templateId is not currently registered on this network, the call reverts with PolicyTemplateNotFound.
IPcl.changeContractPolicies Upserts the ContractPolicyConfig for a target address. The target must be either a PCL-registered proxy (deployed via deployPclProxy) OR a binary-supported policy-aware precompile — currently only the Privacy precompile at 0x100000000000000000000000000000000000000b. msg.sender must be the target's current contract admin — for a proxy, the account that called deployPclProxy (it became the admin in that same call); for a policy-aware precompile, the admin the chain installed — and the new admin value in the payload replaces the old one atomically with the policy replacement. Passing an empty policies array to a policy-aware precompile is rejected — those targets must always carry at least one PolicySet. Ordinary PCL proxies may carry an empty policies array (equivalent to no contract-scope rules). The chain-wide policyAdmin cannot mutate these configs unless it also happens to be the stored contract admin. The contract scope accepts both ALLOW_LIST_POLICY and DENY_LIST_POLICY, which reference a shared address list by listId rather than carrying addresses inline.
IPcl · Address lists
Create and manage the shared address lists that ALLOW_LIST_POLICY and DENY_LIST_POLICY reference by listId, and read their members.
IPcl.addressList Reads metadata for a single shared address list from the PCL precompile's registry. Returns an AddressList tuple of { id, admin, status } — membership is NOT included here, use addressListMembers to page through the entries. The status field reports whether the list is Active (policies may evaluate it) or Disabled (policies that reference it revert with AddressListDisabled(listId) at evaluation time, though reads still succeed). The underlying registry backs both ALLOW_LIST_POLICY and DENY_LIST_POLICY.
IPcl.addressListMembers Pages through the member addresses of a single shared address list. Members are returned in canonical byte order and are the exact set a referencing ALLOW_LIST_POLICY or DENY_LIST_POLICY evaluates against. The read succeeds whether the list is Active or Disabled — only policy evaluation gates on status, not reads. A missing list reverts with AddressListNotFound(listId).
IPcl.addressLists 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.
IPcl.changeAddressListAdmin Transfers administrative ownership of a shared address list to newAdmin. Only the current admin may call this; any other sender reverts with Unauthorized. Setting newAdmin to the zero address is rejected with InvalidAddressListConfig — renouncing admin rights is not supported through this entry point. Calling with the same address that is already the admin is a no-op and emits no event. On an actual change the registry emits AddressListAdminChanged(listId, oldAdmin, newAdmin) and all subsequent mutating calls (updateAddressList, setAddressListStatus, further changeAddressListAdmin) must come from newAdmin.
IPcl.createAddressList Allocates a new shared address list and assigns the caller as its administrator. There is no role check — any account or contract may call it. Returns the nonzero listId, which ALLOW_LIST_POLICY and DENY_LIST_POLICY reference via their listId field. The returned list is created with status Active and empty membership; populate it with updateAddressList before binding a policy that references it. The PCL precompile has no EVM bytecode, so a Solidity high-level call to a precompile function that returns a value still works, but callers that want to reach the registry without knowing the ABI shape must call it low-level and decode the returned uint64.
IPcl.isAddressListed Checks whether account is currently a member of the shared address list listId. This is the constant-time membership probe — use it on the hot path when addressListMembers paging would be wasteful. The read succeeds whether the list is Active or Disabled; only policy evaluation gates on status. A missing list reverts with AddressListNotFound(listId).
IPcl.setAddressListStatus Flips a shared address list between Active and Disabled without rewriting any PolicySet that references it. Only the current list admin may call this; any other sender reverts with Unauthorized. The sentinel Unspecified value is rejected with InvalidAddressListConfig. A disabled list stays readable through addressList, addressListMembers, and isAddressListed, but any ALLOW_LIST_POLICY or DENY_LIST_POLICY that references it reverts at evaluation time with AddressListDisabled(listId) — it fails CLOSED: those policies reject every call they evaluate (a global DENY_LIST_POLICY over a disabled list rejects every transaction on the chain), so disabling is not a way to stop enforcing a list. Setting the status to its current value is a no-op and emits no event; a real transition emits AddressListStatusChanged(listId, oldStatus, newStatus).
IPcl.updateAddressList Adds and/or removes members of an existing shared address list in a single atomic batch. Only the current list admin may call this; every other sender reverts with Unauthorized. Idempotent per address: re-adding an existing member or removing a non-member is a no-op and does not revert, but the add and remove arrays together must contain no duplicate addresses and must not both be empty. The call emits AddressListMembersAdded and/or AddressListMembersRemoved carrying only the addresses whose membership actually changed. A call that changes nothing (every add address is already a member and every remove address is not) succeeds without emitting either event, so confirm the call from the receipt status, not from an event. A policy bound to this list reflects the new membership on its next evaluation.
IPcl · Regulated execution
The Regulated Track execution surface: PCL proxies and the preCall / postCall hooks. Policy evaluation runs on the proxy hook path; there is no single-call entry point that both checks policy and executes for you. Use eth_call for pre-flight.
IPcl.deployPclProxy Deploys a PCL-wrapped proxy of the requested kind using the canonical bytecode embedded in the chain binary, registers it in the on-chain proxy registry, and sets the immediate EVM caller (msg.sender) as its initial policy admin. The returned proxy address is the address dApps should publish as the canonical contract address, because only calls that go through this registered proxy trigger the contract-scoped PCL enforcement path (preCall / postCall). After deployment, IPcl.pclProxy(proxy) returns the registry entry with the proxy's kind, its current admin, and the proxy address itself; that admin field stays in sync when changeContractPolicies rotates the contract admin.
IPcl.postCall Closes the PCL enforcement session opened by preCall. Given a sessionId returned by preCall, postCall re-runs the post-execution half of the policy evaluation — recording periodic volume, enforcing after-call rules, and emitting PolicyCheckPassed — using the session's stored context. The precompile verifies that the immediate caller (msg.sender of postCall), the target contractAddress, the forwarded principal, and the leading 4-byte selector of data all match the values captured when the session was opened; any divergence reverts with Unauthorized. The PCL-wrapped proxy invokes this hook automatically after the inner call returns; direct callers must pass postCall the same contractAddress, principal, and leading selector of data they passed to preCall, or the session cannot be closed.
IPcl.preCall Opens a PCL enforcement session for a regulated call. The immediate msg.sender must be one of two authorized caller kinds: a PCL-registered proxy invoking its own target (contractAddress == msg.sender), or a governance-trusted ERC-4337 EntryPoint executing a bundle. In both cases PCL evaluates global and contract-scoped policies against the forwarded principal (the EOA or smart-account that originated the call) with the extracted 4-byte selector and value. If any before-execution policy fails the call reverts with the corresponding PCL ReasonCode; otherwise PCL installs an internal tracer, registers a session keyed by a derived sessionId, and returns it. The paired postCall invocation must present the same sessionId to close the session and run after-execution evaluation. A staticcall (readonly) execution returns the zero bytes32 and does not open a session — policy state is evaluated inside a cached context and discarded.
IPcl.pclProxy Returns the on-chain registry entry for a PCL-wrapped proxy address. The PclProxyEntry tuple contains the proxy variant (kind), the currently-bound policy admin (admin), and the registered proxy address (proxy). If proxy is not registered, every field of the returned entry is zero (kind = Unspecified, admin = 0x0, proxy = 0x0) — the call does not revert. The admin field is a projection of the canonical contract-admin record: it is set the moment deployPclProxy runs and is kept in sync when a subsequent changeContractPolicies rotates the admin, so a client reading this view sees the current gatekeeper without a second query to contractPolicies.
IPcl · Periodic volume queries
Read the fixed-window volume counters behind periodic volume limit policies (windows reset together, aligned to the Unix epoch).
IPcl.contractPeriodicList Lists every PERIODIC_VOLUME_POLICY running counter attached to contractAddress that applies to user. Filter by asset and optionally by function selector — pass empty bytes ("0x") to match PolicySets registered without a selector. One entry per distinct reset-period bucket configured on the contract.
IPcl.contractPeriodicVolume Returns every contract-scoped periodic-volume counter matching the requested (selector, asset, resetPeriodSeconds) tuple for user on contractAddress. A single reset period can back several distinct maxAmount limits (for example, a wallet-tier cap layered under a per-function cap), so callers must fold across the returned array rather than assume a single record. An empty array means no contract policy currently matches the tuple. Pass an empty selector to read counters registered without a function-selector scope; pass resolveAgentOwners = true to read an agent wallet's owners' counters instead (the largest is returned).
IPcl.globalPeriodicList Lists every PERIODIC_VOLUME_POLICY running counter for user under the global policy config, one entry per distinct reset-period bucket. Use this when the user is subject to multiple global periodic caps at different window lengths (for example a 24-hour cap and a 30-day cap on the same asset) and you want to render or check all of them at once.
IPcl.globalPeriodicVolume Returns every global periodic-volume counter that shares the requested (asset, resetPeriodSeconds) pair for user. The array is empty when no global PERIODIC_VOLUME_POLICY matches the (asset, reset-period) tuple; otherwise it contains one PeriodicVolume entry per registered limit — a single reset period can back several distinct maxAmount variants, and each is returned so callers can pick the tightest applicable cap. Set resolveAgentOwners to true to read an agent wallet's owners' counters instead — the largest of them is returned.
IPcl · Params
Read PCL module parameters.
OKRW
The OKRW stablecoin precompile — params, minting, and mint events.
IOkrw.getParams Returns the OKRW module parameters — the authorized minter address and the mint denom. The return struct is named OkrwParams (the un-namespaced Params name was renamed so multiple precompile interfaces can be imported together without struct-name collisions). The minter address rotation is a consortium-governance action; clients should treat this as a read-only discovery endpoint.
IOkrw.mint Mints amount of OKRW (in atokrw, the 18-decimal base denom) and credits it to recipient. Only the authorized minter address configured in the x/okrw module parameters can call this successfully; any other caller reverts with the module-owned UnauthorizedMinter(address caller, address authorizedMinter) custom error. Zero-address recipients and zero amounts revert with the shared IPrecompile.InvalidAddress(string bad) and IPrecompile.InvalidAmount(string amount) typed errors respectively (note: both carry a string payload — the offending address or amount rendered as text — not the raw address/uint256). The source's plain string reverts for a nil or negative amount ("amount must not be nil", "amount must not be negative") cannot be reached: the ABI decoder always yields a non-negative uint256, even from a low-level call.
OKRW.Mint (event) Emitted by the OKRW precompile upon a successful call to the mint function. This event provides a verifiable, on-chain record of all OKRW minting activity originating from the EVM. Indexers and client applications can subscribe to this event to track the OKRW supply and distribution.
EAS
Attestation queries against the EAS precompile.
IEas.getParams Returns the canonical Ethereum Attestation Service addresses for this chain: the schemaRegistry, eas, and indexer preinstall addresses. Call this at startup so your dApp resolves the addresses at runtime instead of hard-coding per-network values. The precompile inherits the shared IPrecompile error surface — argument-shape failures revert with typed errors, while a not-yet-initialized keeper still surfaces as a plain string revert "eas keeper is not initialized".
EAS.getAttestation Returns the full Attestation struct for a given UID, or an Attestation with uid == 0x00.. if the UID is unknown. This is the canonical read on the EAS contract preinstall — every other surface (@ethereum-attestation-service/eas-sdk, the Indexer, PCL's EAS_POLICY evaluator) ultimately calls this. dApp code should validate revocationTime == 0 and (expirationTime == 0 || expirationTime > now) before treating an attestation as valid.
Indexer.getReceivedAttestationUIDCount Returns the number of attestations issued to recipient under schemaUid. A cheap existence check — call this before paginating with getReceivedAttestationUIDs. The count tracks issuance only; revoked or expired attestations still increment it, so use the count as a search bound rather than a validity gate.
Indexer.getReceivedAttestationUIDs Paginated reverse-lookup: returns up to length attestation UIDs issued to recipient under schemaUid. Use reverseOrder = true to start from the most recent. Each returned UID feeds EAS.getAttestation(uid) to fetch the actual struct and check revocation/expiration.
Agent
ERC-8004 agent registry queries.
IAgent.getAgentIds Paginated lookup by agent wallet: returns the IDs of the agents whose ERC-8004 agent wallet is wallet. The agent wallet is set to the registrant by register and changed with setAgentWallet / unsetAgentWallet; when the agent NFT is transferred, its entry is removed. So this is not a list of the agents an address OWNS — for that, use the IdentityRegistry's ERC-721 surface (balanceOf, Transfer events). The Agent precompile exposes this method because walking IdentityRegistry storage from inside a contract is too expensive; it reads a chain-side index. Registration, the agent URI, metadata, the agent wallet and ERC-721 ownership live on the ERC-8004 IdentityRegistry preinstall at 0x8004000000000000000000000000000000000001 — call it directly. The registry has no attest or revoke function.
IAgent.getParams Returns the canonical addresses that the Agent module resolves for this chain — the ERC-8004 identityRegistry and reputationRegistry preinstalls. Call this once at startup so your dApp can locate the registries without hard-coding an address per network. The precompile inherits the shared IPrecompile error surface, so any failure surfaces as a typed error rather than a bespoke one.
IPrivacy · Shielded value flow
Move value into, within, and out of the shielded pool: deposit commits funds, transfer spends a note to new commitments, withdraw returns value to a transparent recipient. The caller submits and pays gas.
IPrivacy.deposit Escrows the caller's transparent OKRW (attached as msg.value) into the shielded pool and appends the new note commitment from request.output to the Merkle tree. deposit is the only payable method on IPrivacy. The shielded amount is bounded by a 128-bit field, so one operation carries at most 340282366920938463463374607431768211455 base units (~340282366920938463463.374607431768211455 OKRW) — above that the node rejects the request. Failures revert with typed custom errors on IPrivacy or inherited errors on IPrecompile.
IPrivacy.transfer Spends one or more shielded notes and creates new notes under a Groth16 proof over BN254. msg.sender is the effective sender — PCL evaluates policies against the caller directly. The request now carries its new notes as a PrivacyOutputEffect[] (commitment, ciphertext, view tag, and per-output disclosure fields) plus a mandatory PrivacyAuditAuthorization binding the active audit key and the encrypted audit envelope. Failures revert with typed custom errors declared on IPrivacy (request-expiry, nullifier/commitment collisions, Merkle capacity, per-transaction limits) or inherited from IPrecompile. PCL policy failures surface as PCL ReasonCodes from IPcl instead.
IPrivacy.withdraw Spends a shielded note and pays the underlying transparent OKRW to request.recipient. msg.sender is the effective sender for PCL policy purposes. Failures revert with typed custom errors declared on IPrivacy (request-expiry, native-denom mismatch, nullifier collision) or inherited from IPrecompile (InvalidAddress, etc.); a malformed, zero or over-cap amount is rejected earlier, by the audit-message check, with a plain Error(string).
IPrivacy · Authorized relay
The same actions submitted by someone else. The effective sender signs an EIP-712 authorization binding the request to one executor, a nonce, and a deadline; the executor pays gas while balances, policy, and event attribution still read as the effective sender.
IPrivacy.transferWithAuthorization Executes a shielded transfer on behalf of an effectiveSender who signed an EIP-712 PrivacyActionAuthorization. The relayer is msg.sender; the authorization designates the sender whose nonce is spent and whose PCL rules apply. The request payload is the same PrivacyTransferRequest the direct transfer path uses — its new notes live in a PrivacyOutputEffect[] and a mandatory PrivacyAuditAuthorization binds the active audit key and encrypted envelope. Failures revert with typed custom errors on IPrivacy (authorization checks, request-expiry, nullifier/commitment collisions, batch limits) or inherited errors on IPrecompile (ABISetupFailed, RequesterIsNotMsgSender, etc.). PCL policy failures still surface as PCL ReasonCodes from IPcl.
IPrivacy.withdrawWithAuthorization Withdraws funds from the shielded pool back to a transparent EVM recipient on behalf of an effectiveSender who signed an EIP-712 authorization. The executor (typically a relayer) submits the transaction; the precompile verifies the signature, enforces nonce / deadline replay protection, and performs the same nullifier-consuming withdraw state transition as the direct withdraw method. The amount field is a coin string parsed by the chain (e.g. "1000000000000000000000atokrw" for 1,000 OKRW).
IPrivacy · Batch transfers
Many shielded transfers in one call. batchTransfer carries a proof per item; singleProofBatchTransfer proves the whole batch once, which is cheaper but constrains batch shape. Both have authorized-relay variants.
IPrivacy.batchTransfer Applies multiple independently-proved shielded transfers atomically inside a single transaction, all keyed by batchId. Each PrivacyTransferRequest carries its new notes in a PrivacyOutputEffect[] and a mandatory PrivacyAuditAuthorization. Each element is preflighted for duplicate nullifiers, duplicate output commitments, and Merkle capacity against the whole batch — a single failure reverts the entire call. Failures surface as typed custom errors on IPrivacy or inherited on IPrecompile.
IPrivacy.batchTransferWithAuthorization Submits a multi-proof batch on behalf of one or more effective senders — each items[i] carries a PrivacyTransferRequest (with its own PrivacyOutputEffect[] outputs and PrivacyAuditAuthorization) and a PrivacyActionAuthorization whose signature covers that specific item's request under the shared batchId and per-item batchItemIndex. The caller (msg.sender) is recorded as the executor on every authorization; a mismatch between the recovered signer and authorization.effectiveSender, an expired deadline, or a reused nonce reverts the entire batch. The 20-item protocol limit (MaxPrivacyMultiProofBatchItems) is enforced identically to the direct batchTransfer path.
IPrivacy.singleProofBatchTransfer Applies a batch join-split (multiple inputs, multiple outputs) validated by a single Groth16 proof over BN254. The request carries one proof, one root, an array of input nullifiers, an array of PrivacyOutputEffect outputs (each a self-contained tuple with commitment, ciphertext, view tag, and disclosure fields), an expiresAtUnix, and a PrivacyAuditAuthorization tuple (keyId, epoch, envelope) that binds the batch to the active audit key. Only deposit is payable; attaching msg.value here reverts with PrivacyNonPayable(methodName). Input and output counts must be in 1..BatchJoinSplitV1MaxInputs / 1..BatchJoinSplitV1MaxOutputs; out-of-range counts revert with PrivacyBatchSizeOutOfRange(count, max). Failures surface as typed custom errors on IPrivacy or inherited on IPrecompile.
IPrivacy.singleProofBatchTransferWithAuthorization Meta-transaction variant of singleProofBatchTransfer: a relayer submits the batch on behalf of authorization.effectiveSender, who signed an off-chain authorization binding the request hash to a specific executor, nonce, and deadline. The request now carries a PrivacyAuditAuthorization tuple (keyId, epoch, envelope) and an array of PrivacyOutputEffect outputs instead of the earlier inline audit fields. Supports EOA signatures, ERC-1271 smart-account signatures, and EIP-7702 delegated-EOA signatures, chosen via authorization.authorizationKind. The request-hash domain is dedicated to the single-proof batch method, so it does not collide with authorizations for other privacy calls. Failures revert with a typed custom error — IPrivacy declares its own and inherits the shared protocol errors from IPrecompile, so a client decodes the 4-byte selector rather than matching reason text. An EOA signature that is not exactly 65 bytes is no exception: it reverts with PrivacyAuthorizationRejected(1).