@maroo-chain/contracts

A library of smart contracts for Maroo blockchain development.

Installation

npm install @maroo-chain/contracts

pnpm add @maroo-chain/contracts

Included Contracts

| Contract | Path | Description | |----------|------|-------------| | IOkrw | precompiles/okrw/IOkrw.sol | OKRW token minting interface | | IPcl | precompiles/pcl/IPcl.sol | Policy Control Layer interface | | IPrivacy | precompiles/privacy/IPrivacy.sol | Clairveil privacy precompile interface for deposit, transfer, withdraw, authorization, and batch transfer flows |

Usage

Import in Solidity

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.22;

import "@maroo-chain/contracts/precompiles/pcl/IPcl.sol";

contract PolicyManager {
    function getGlobalPolicies() external view returns (GlobalPolicyConfig memory) {
        return PCL_CONTRACT.globalPolicies();
    }
    
    function getPolicyAdmin() external view returns (address) {
        return PCL_CONTRACT.policyAdmin();
    }
}

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.22;

import "@maroo-chain/contracts/precompiles/privacy/IPrivacy.sol";

contract ContractOwnedPrivacyBatchAccount {
    function submit(bytes32 batchId, PrivacyTransferRequest[] calldata requests) external {
        // The precompile sees this contract, not the external msg.sender, as the
        // operator and contract-PCL subject. The shielded note owner proven by
        // each request is a separate cryptographic subject.
        PRIVACY_CONTRACT.batchTransfer(batchId, requests);
    }
}

The Solidity example above is a contract-owned privacy account: the immediate caller of batchTransfer is the contract, so that contract is the operator and contract-PCL subject for the top-level batch. It does not preserve the external user's msg.sender identity. A relayer or forwarding contract can call batchTransferWithAuthorization to bind each Clairveil message, event attribution, and authorization nonce to a signed effectiveSender; the PCL subject remains the immediate operator. Neither plain nor authorized attribution proves that the transparent subject is the shielded note owner; that owner is established by the Clairveil proof.

Import ABI in TypeScript/JavaScript

// ethers.js example
import { ethers } from "ethers";
import { iPclAbi } from "@maroo-chain/contracts/abi/precompiles/pcl/IPcl";

const provider = new ethers.JsonRpcProvider("https://rpc.maroo.network");

const pclContract = new ethers.Contract(
  "0x1000000000000000000000000000000000000005",
  iPclAbi,
  provider
);

const admin = await pclContract.policyAdmin();
console.log("Policy Admin:", admin);

// Privacy precompile ABI example
import { ethers } from "ethers";
import { iPrivacyAbi } from "@maroo-chain/contracts/abi/precompiles/privacy/IPrivacy";

const privacy = new ethers.Contract(
  "0x100000000000000000000000000000000000000b",
  iPrivacyAbi,
  signer
);

// Because the signer calls the precompile directly, signer.address is the
// operator, effectiveSender, and contract-PCL subject for this batch.
await privacy.batchTransfer(batchId, transferRequests);

// deposit is payable. msg.value is the only transparent amount source; the
// PrivacyDepositRequest tuple intentionally has no amount field.
await privacy.deposit(depositRequest, { value: depositAmount });

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

const client = createPublicClient({
  transport: http("https://rpc.maroo.network"),
});

const pclContract = getContract({
  address: "0x1000000000000000000000000000000000000005",
  abi: iPclAbi,
  client,
});

const admin = await pclContract.read.policyAdmin();
console.log("Policy Admin:", admin);

Privacy Precompile Notes

IPrivacy is an EVM ABI wrapper for Clairveil privacy operations. It does not generate Clairveil notes, disclosure payloads, or ZK proofs by itself. Wallets and applications must build valid Clairveil request payloads off-chain, then submit them through the precompile.

• Withdraw amount uses a Cosmos SDK coin string such as "100aokrw". Deposit has no amount field and uses only EVM msg.value.
• PrivacyTransferRequest.expiresAtUnix is required by Clairveil v0.2 and is included in transfer request hashes and authorization signatures.
• deposit, transfer, withdraw, batchTransfer, and singleProofBatchTransfer execute with the immediate EVM caller as the privacy effectiveSender.
• deposit is payable; msg.value is the only amount source. A valid proof with zero value remains valid. depositWithAuthorization no longer exists.
• transferWithAuthorization, withdrawWithAuthorization, batchTransferWithAuthorization, and singleProofBatchTransferWithAuthorization execute with the signed effectiveSender after EOA, ERC-1271, or EIP-7702 authorization validation.
• Contract PCL always evaluates the immediate EVM caller (operator), including authorized calls. effectiveSender is used for authorization, nonce handling, Clairveil message attribution, and events, not as the contract-PCL subject.
• Each top-level mutating Privacy call executes exactly one contract-scoped PCL operation through the full Before → Execute → After → Record lifecycle. Global PCL remains owned by the normal EVM ante/hook path.
• Direct batchTransfer is the plain account-call rail: an EOA, smart account, or contract caller is the effectiveSender for every item. A forwarding contract therefore creates a contract-owned batch instead of attributing items to the forwarding contract's users.
• Use batchTransferWithAuthorization for relayed or contract-submitted batches that require signed Clairveil message attribution. Each item carries its own signed effectiveSender; do not substitute an untrusted calldata address for authorization. The whole top-level batch still has one operator-based PCL evaluation.
• batchTransfer(bytes32 batchId, PrivacyTransferRequest[] requests) and batchTransferWithAuthorization(bytes32 batchId, AuthorizedTransferItem[] items) are all-or-nothing transfer batches.
• The existing EVM batch methods execute an ordered list of independent Clairveil MsgTransfer proofs. They are not replaced by the one-proof API.
• singleProofBatchTransfer(PrivacySingleProofBatchTransferRequest request) and its authorized variant execute one upstream Clairveil v0.2 MsgBatchTransfer proof for 1..16 inputs and 1..32 outputs. The authorized variant signs the whole request once; it does not create per-output authorizations.
• One-proof batch success emits only PrivacySingleProofBatchTransfer(effectiveSender, operator, requestHash, root, inputCount, outputCount). Ciphertexts, disclosure payloads, proofs, and private witnesses are never logged.
• batchId is an application/client operation id used in events and reconciliation. The Maroo precompile rejects zero and duplicate (immediate operator, batchId) pairs within the same outer EVM transaction.
• Solidity/TypeScript consumers can use the generated ABI directly with ethers, viem, wagmi, smart accounts, or ERC-4337 SimpleAccount.execute(...).

Current client integration documentation:

• Privacy documentation index
• Privacy precompile client guide
• Current Clairveil integration guide

Authorization and request-hash test vectors live in:

precompiles/privacy/testdata/privacy_authorization_vectors.json

Foundry Setup

Add the following to remappings.txt:

@maroo-chain/contracts/=node_modules/@maroo-chain/contracts/

License

MIT