@zentity/fhevm-contracts 0.1.0

package/contracts/ARCHITECTURE.md

@@ -0,0 +1,66 @@
+# Zentity FHEVM Architecture (Web3 Data Flow)
+
+This document focuses on the Web3 data flow and where encryption happens in the
+fhEVM flow. It is meant to be a high-level map for developers and reviewers.
+
+## Web3 Data Flow (Encrypted State + Compliance)
+
+```mermaid
+flowchart TD
+    User["User Wallet + Zama SDK"] -- "1) Encrypt input: externalEuint" --> EncIn["Ciphertext handle + proof"]
+    EncIn -- "2) tx call" --> IR["IdentityRegistry"]
+    EncIn -- "2) tx call" --> ERC["CompliantERC20"]
+
+    subgraph OnChain["On-chain fhEVM"]
+      IR -- "3) Stores encrypted attrs" --> IRState["Encrypted attributes: birthYear/country/kyc/blacklist"]
+      IR -- "4) ACL grants" --> ACL["ACL per ciphertext handle"]
+      ERC -- "5) calls" --> CR["ComplianceRules"]
+      CR -- "6) queries" --> IR
+      CR -- "7) returns ebool" --> ERC
+      ERC -- "8) select transfer amount" --> ERCState["Encrypted balances"]
+    end
+
+    subgraph OffChain["Off-chain FHE coprocessor"]
+      FHE["FHE Coprocessor"] <--> OnChain
+    end
+
+    User -- "9) grantAccessTo ComplianceRules" --> IR
+    IR -- "10) AccessGranted event" --> UI["UI / dApp"]
+
+    note1["Encryption happens client-side. Values are stored on-chain as ciphertext handles with ACL permissions."]
+    note2["ComplianceRules evaluates only for allowed callers; results are encrypted and ACL-protected."]
+
+    note1 -.-> User
+    note2 -.-> CR
+```
+
+### Key points
+- **Encryption happens client-side** using the Zama SDK. Inputs are submitted as
+  `externalEuint*` handles with a proof.
+- **On-chain storage is always encrypted** (ciphertext handles), guarded by the
+  ACL. No plaintext identity data is stored on-chain.
+- **Ciphertexts remain polymorphically encrypted** under FHE operations, so
+  computation happens without decryption and without changing confidentiality.
+- **Compliance is evaluated under encryption** in `ComplianceRules`, and the
+  encrypted boolean is consumed by `CompliantERC20` using `FHE.select`.
+- **Access grants are explicit**: users must call `IdentityRegistry.grantAccessTo`
+  for any contract to read or compute on their identity ciphertexts.
+- **Silent failure**: if compliance or balance checks fail, the transfer silently
+  becomes a zero transfer to avoid leaking sensitive conditions.
+
+## How encryption is saved on-chain
+- Encrypted values are stored as **ciphertext handles** in contract state.
+- The ACL contract enforces who may use each handle for computation or decryption.
+- `grantAccessTo` updates ACL rights for the user's ciphertext handles.
+
+## Contracts involved
+- `IdentityRegistry`: encrypted identity attributes + ACL grants.
+- `ComplianceRules`: encrypted compliance checks (authorized or self-only).
+- `CompliantERC20`: encrypted balances, compliance-gated transfers.
+
+## Ownership and admin safety
+- These contracts use **two-step ownership transfer**:
+  1. `transferOwnership(newOwner)` by current owner
+  2. `acceptOwnership()` by pending owner
+- This reduces the risk of accidental loss of admin control.
+- For production, transfer ownership to a multisig once deployments are verified.

package/contracts/ARCHITECTURE_EXPLAINER.md

@@ -0,0 +1,77 @@
+# Zentity Architecture Explainer (Web2 -> Web3 Flow)
+
+This document explains the end-to-end flow from Web2 verification to Web3
+attestation and encrypted compliance checks.
+
+## Web2 -> Web3 Data Flow
+
+```mermaid
+sequenceDiagram
+    autonumber
+    actor User
+    participant UI as Zentity Web App (Web2)
+    participant BE as Zentity Backend (Web2)
+    participant KYC as KYC/Liveness Services (Web2)
+    participant Registrar as Registrar Wallet (Web3)
+    participant IR as IdentityRegistry (fhEVM)
+    participant CR as ComplianceRules (fhEVM)
+    participant ERC as CompliantERC20 (fhEVM)
+
+    User->>UI: Complete verification flow (docs + liveness)
+    UI->>BE: Submit verification data
+    BE->>KYC: Verify identity and liveness
+    KYC-->>BE: KYC result + attributes
+
+    BE->>UI: Verification complete (Web2)
+    UI->>Registrar: Request on-chain attestation
+
+    Note over UI,Registrar: Identity attributes are encrypted client-side<br/>and sent as externalEuint handles + proof.
+
+    Registrar->>IR: attestIdentity(user, encAttrs, proof)
+    IR-->>Registrar: Encrypted state stored + ACL for user
+
+    User->>IR: grantAccessTo(ComplianceRules)
+    IR-->>User: AccessGranted event
+
+    User->>ERC: transfer(to, encAmount, proof)
+    ERC->>CR: checkCompliance(user)
+    CR->>IR: read encrypted attributes (ACL-protected)
+    CR-->>ERC: encrypted compliance result
+    ERC-->>User: transaction confirmed (silent failure if non-compliant)
+```
+
+## What stays in Web2 vs Web3
+
+### Web2 (Zentity Backend)
+- **Collects and verifies identity data** (documents, liveness, etc.).
+- **Produces the final KYC result** and attribute set.
+- **Never stores plaintext on-chain**. Only encrypted attributes are sent to
+  Web3 via the registrar flow.
+
+### Web3 (fhEVM + Zama)
+- **Stores encrypted identity attributes** in `IdentityRegistry` as ciphertext
+  handles.
+- **Enforces access via ACL**. Only explicitly granted contracts/users can use
+  a given handle.
+- **Computes compliance under encryption** in `ComplianceRules`.
+- **Transfers are guarded** by encrypted compliance checks in `CompliantERC20`.
+
+## Why the flow is secure (and complex)
+- **Confidentiality** is preserved because the EVM never sees plaintext values.
+- **Integrity** is enforced through ACL permissions and explicit caller checks.
+- **Non-reverting patterns** (silent failure) prevent information leakage.
+
+## Operational responsibilities
+- **Users** must grant access to `ComplianceRules` once per network.
+- **Deployments** must authorize `CompliantERC20` as an allowed caller in
+  `ComplianceRules`.
+- **UI** should surface access requirements and avoid caching access state
+  locally (rely on on-chain events).
+ - **Owners** should transfer ownership to a multisig using the two-step flow
+   (`transferOwnership` → `acceptOwnership`) after deployments are verified.
+
+## Practical checklist for integrators
+- Ensure `grantAccessTo(ComplianceRules)` is called before any transfer attempts.
+- Ensure `ComplianceRules.setAuthorizedCaller(tokenAddress, true)` is done at deploy.
+- Handle silent failures in the UI (show effective transfer or warning).
+- Avoid exposing arbitrary external calls from privileged contracts.

package/contracts/compliance/ComplianceRules.sol

@@ -0,0 +1,255 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.27;
+
+import {FHE, ebool} from "@fhevm/solidity/lib/FHE.sol";
+import {ZamaEthereumConfig} from "@fhevm/solidity/config/ZamaConfig.sol";
+import {IIdentityRegistry} from "../interfaces/IIdentityRegistry.sol";
+
+/**
+ * @title ComplianceRules
+ * @author Gustavo Valverde
+ * @notice Combines multiple compliance checks using FHE operations
+ * @dev Part of zentity-fhevm-contracts - Builder Track
+ *
+ * @custom:category compliance
+ * @custom:concept Combining encrypted compliance checks with FHE.and()
+ * @custom:difficulty intermediate
+ *
+ * This contract aggregates compliance checks from IdentityRegistry and returns
+ * encrypted boolean results. Consumer contracts (like CompliantERC20) can use
+ * these results with FHE.select() for branch-free logic.
+ *
+ * Key patterns demonstrated:
+ * 1. FHE.and() for combining multiple encrypted conditions
+ * 2. Integration with IdentityRegistry
+ * 3. Configurable compliance parameters
+ * 4. Encrypted result caching
+ */
+contract ComplianceRules is ZamaEthereumConfig {
+    // ============ State ============
+
+    /// @notice Reference to the identity registry
+    IIdentityRegistry public immutable identityRegistry;
+
+    /// @notice Owner/admin
+    address public owner;
+    /// @notice Pending owner for two-step ownership transfer
+    address public pendingOwner;
+
+    /// @notice Minimum KYC level required for compliance
+    uint8 public minKycLevel;
+
+    /// @notice Store last compliance check result for each user
+    mapping(address user => ebool result) private complianceResults;
+
+    /// @notice Authorized callers that can request compliance checks for others
+    mapping(address caller => bool authorized) public authorizedCallers;
+
+    // ============ Events ============
+
+    /// @notice Emitted when the minimum KYC level requirement is updated
+    /// @param newLevel The new minimum KYC level required for compliance
+    event MinKycLevelUpdated(uint8 indexed newLevel);
+
+    /// @notice Emitted when a compliance check is performed for a user
+    /// @param user Address of the user whose compliance was checked
+    event ComplianceChecked(address indexed user);
+
+    /// @notice Emitted when a caller's authorization is updated
+    /// @param caller Address being authorized or revoked
+    /// @param allowed Whether the caller is allowed
+    event AuthorizedCallerUpdated(address indexed caller, bool allowed);
+
+    /// @notice Emitted when ownership transfer is initiated
+    /// @param currentOwner Current owner address
+    /// @param pendingOwner Address that can accept ownership
+    event OwnershipTransferStarted(address indexed currentOwner, address indexed pendingOwner);
+
+    /// @notice Emitted when ownership transfer is completed
+    /// @param previousOwner Previous owner address
+    /// @param newOwner New owner address
+    event OwnershipTransferred(address indexed previousOwner, address indexed newOwner);
+
+    // ============ Errors ============
+
+    /// @notice Thrown when caller is not the contract owner
+    error OnlyOwner();
+    /// @notice Thrown when caller is not the pending owner
+    error OnlyPendingOwner();
+    /// @notice Thrown when new owner is the zero address
+    error InvalidOwner();
+
+    /// @notice Thrown when registry address is zero
+    error RegistryNotSet();
+
+    /// @notice Thrown when caller is not authorized to check another user
+    error CallerNotAuthorized();
+
+    /// @notice Thrown when caller lacks permission for encrypted result
+    error AccessProhibited();
+
+    // ============ Modifiers ============
+
+    modifier onlyOwner() {
+        if (msg.sender != owner) revert OnlyOwner();
+        _;
+    }
+
+    modifier onlyAuthorizedOrSelf(address user) {
+        if (msg.sender != user && !authorizedCallers[msg.sender]) {
+            revert CallerNotAuthorized();
+        }
+        _;
+    }
+
+    // ============ Constructor ============
+
+    /**
+     * @notice Initialize with identity registry reference
+     * @param registry Address of the IdentityRegistry contract
+     * @param initialMinKycLevel Initial minimum KYC level (default: 1)
+     */
+    constructor(address registry, uint8 initialMinKycLevel) {
+        if (registry == address(0)) revert RegistryNotSet();
+        identityRegistry = IIdentityRegistry(registry);
+        owner = msg.sender;
+        minKycLevel = initialMinKycLevel;
+    }
+
+    // ============ Admin Functions ============
+
+    /**
+     * @notice Update minimum KYC level
+     * @param newLevel New minimum level
+     */
+    function setMinKycLevel(uint8 newLevel) external onlyOwner {
+        minKycLevel = newLevel;
+        emit MinKycLevelUpdated(newLevel);
+    }
+
+    /**
+     * @notice Allow or revoke a caller to check compliance for other users
+     * @param caller Address to update
+     * @param allowed Whether the caller is allowed
+     */
+    function setAuthorizedCaller(address caller, bool allowed) external onlyOwner {
+        authorizedCallers[caller] = allowed;
+        emit AuthorizedCallerUpdated(caller, allowed);
+    }
+
+    /**
+     * @notice Initiate transfer of contract ownership
+     * @param newOwner Address that can accept ownership
+     */
+    function transferOwnership(address newOwner) external onlyOwner {
+        if (newOwner == address(0)) revert InvalidOwner();
+        pendingOwner = newOwner;
+        emit OwnershipTransferStarted(owner, newOwner);
+    }
+
+    /**
+     * @notice Accept ownership transfer
+     */
+    function acceptOwnership() external {
+        if (msg.sender != pendingOwner) revert OnlyPendingOwner();
+        address previousOwner = owner;
+        owner = pendingOwner;
+        pendingOwner = address(0);
+        emit OwnershipTransferred(previousOwner, owner);
+    }
+
+    // ============ Compliance Checks ============
+
+    /**
+     * @notice Check if user passes all compliance requirements
+     * @dev Combines: hasMinKycLevel AND isNotBlacklisted
+     * @param user Address to check
+     * @return Encrypted boolean indicating compliance status
+     *
+     * Note: This function makes external calls to IdentityRegistry which
+     * computes and stores verification results. The combined result is
+     * stored locally for later retrieval.
+     */
+    function checkCompliance(address user) external onlyAuthorizedOrSelf(user) returns (ebool) {
+        // Check if user is attested
+        if (!identityRegistry.isAttested(user)) {
+            ebool notAttestedResult = FHE.asEbool(false);
+            FHE.allowThis(notAttestedResult);
+            FHE.allow(notAttestedResult, msg.sender);
+            complianceResults[user] = notAttestedResult;
+            return notAttestedResult;
+        }
+
+        // Get individual compliance checks
+        ebool hasKyc = identityRegistry.hasMinKycLevel(user, minKycLevel);
+        ebool notBlacklisted = identityRegistry.isNotBlacklisted(user);
+
+        // Combine all conditions
+        ebool result = FHE.and(hasKyc, notBlacklisted);
+
+        // Store and grant permissions
+        complianceResults[user] = result;
+        FHE.allowThis(result);
+        FHE.allow(result, msg.sender);
+
+        emit ComplianceChecked(user);
+
+        return result;
+    }
+
+    /**
+     * @notice Check compliance with additional country restriction
+     * @param user Address to check
+     * @param allowedCountry Country code that is allowed
+     * @return Encrypted boolean indicating compliance status
+     */
+    function checkComplianceWithCountry(
+        address user,
+        uint16 allowedCountry
+    ) external onlyAuthorizedOrSelf(user) returns (ebool) {
+        // Check if user is attested
+        if (!identityRegistry.isAttested(user)) {
+            ebool notAttestedResult = FHE.asEbool(false);
+            FHE.allowThis(notAttestedResult);
+            FHE.allow(notAttestedResult, msg.sender);
+            return notAttestedResult;
+        }
+
+        // Get individual compliance checks
+        ebool hasKyc = identityRegistry.hasMinKycLevel(user, minKycLevel);
+        ebool notBlacklisted = identityRegistry.isNotBlacklisted(user);
+        ebool isFromAllowedCountry = identityRegistry.isFromCountry(user, allowedCountry);
+
+        // Combine all conditions
+        ebool result = FHE.and(FHE.and(hasKyc, notBlacklisted), isFromAllowedCountry);
+
+        // Grant permissions
+        FHE.allowThis(result);
+        FHE.allow(result, msg.sender);
+
+        emit ComplianceChecked(user);
+
+        return result;
+    }
+
+    /**
+     * @notice Get the last compliance check result for a user
+     * @dev Call checkCompliance first to compute and store the result
+     * @param user Address to get result for
+     * @return Encrypted boolean result
+     */
+    function getComplianceResult(address user) external view returns (ebool) {
+        ebool result = complianceResults[user];
+        if (!FHE.isSenderAllowed(result)) revert AccessProhibited();
+        return result;
+    }
+
+    /**
+     * @notice Check if compliance result exists for user
+     * @param user Address to check
+     * @return Whether a cached result exists
+     */
+    function hasComplianceResult(address user) external view returns (bool) {
+        return FHE.isInitialized(complianceResults[user]);
+    }
+}