Contract API

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.

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) policy-aware precompiles (addresses listed in PclParams.PolicyAwarePrecompiles) 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.

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.

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. On the first call for a target, msg.sender may be anyone and the payload's admin becomes the future gatekeeper; on subsequent calls msg.sender must equal the currently stored admin, 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.

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.

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 ensure the tuple passed to postCall is byte-identical to the tuple passed to preCall, or the session cannot be closed.

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.

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.

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.

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 aggregate volume across every agent owned by user.

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.

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 accumulate volume across every agent owned by the queried address.

Returns the PCL module's runtime parameters as a PclParams struct with two fields: policyAdmin (the address authorized to register/remove policy templates and to set the global GlobalPolicyConfig) and entrypoints (the addresses recognized as legitimate top-level callers by the PCL evaluator). The set of policy-aware precompiles is no longer part of these parameters — it is fixed in the chain binary and queried via types.IsSupportedPolicyAwarePrecompile internally, so it cannot be reconfigured through module params.

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.

Mints amount of OKRW (in aokrw, 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). Nil or negative amount inputs (only reachable through low-level ABI abuse) surface as plain string reverts, "amount must not be nil" and "amount must not be negative"; these are not decodable typed errors.

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.

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".

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.

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.

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.

Paginated reverse lookup: returns the agent IDs registered to wallet. The Agent precompile exposes this method because walking IdentityRegistry storage from inside a contract is too expensive — the precompile reads from a chain-side index that is kept in sync. For everything else (register, attest, revoke, metadata), call the ERC-8004 IdentityRegistry preinstall at 0x8004000000000000000000000000000000000001 directly.

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.

Escrows the caller's transparent OKRW (attached as msg.value) into the shielded pool and appends the note commitment from request to the Merkle tree. deposit is the only payable method on IPrivacy. The shielded amount is bounded by a 64-bit field, so a single deposit is capped at 18446744073709551615 base units (~18.446744073709551615 OKRW) — larger balances are held as multiple notes. Failures revert with typed custom errors on IPrivacy or inherited errors on IPrecompile.

Spends one or more shielded notes and creates new notes under a Groth16 proof. msg.sender is the effective sender — PCL evaluates policies against the caller directly. 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.

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 (InvalidAmount, InvalidAddress, etc.).

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. Failures now revert with typed custom errors on IPrivacy (authorization checks, request-expiry, nullifier/commitment collisions, batch limits) or inherited errors on IPrecompile (InvalidNumberOfArgs, RequesterIsNotMsgSender, etc.). PCL policy failures still surface as PCL ReasonCodes from IPcl.

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, then 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. "10000000000000000000aokrw" for 10 OKRW).

Applies multiple independently-proved shielded transfers atomically inside a single transaction, all keyed by batchId. Each element is preflighted for duplicate nullifiers, duplicate 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.

Submits a multi-proof batch on behalf of one or more effective senders — each items[i] carries a PrivacyTransferRequest 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.

Applies a batch join-split (multiple inputs, multiple outputs) validated by a single Groth16 proof. Input count must be in 1..BatchJoinSplitV1MaxInputs, output count must be in 1..BatchJoinSplitV1MaxOutputs; out-of-range counts revert with PrivacyBatchSizeOutOfRange(count, max). Failures surface as typed custom errors on IPrivacy or inherited on IPrecompile.

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. 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 — it will 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. One case is still a plain string — an EOA signature that is not exactly 65 bytes is rejected before any typed error is built.