@zentity/fhevm-contracts 0.1.1 → 0.2.0

package/README.md

@@ -6,7 +6,7 @@ fhEVM smart contracts for privacy-preserving identity attestations.
 
 This package provides Solidity contracts using Zama's fhEVM:
 
-- **IdentityRegistry** — encrypted identity attributes (birth year offset, country, KYC, blacklist)
+- **IdentityRegistry** — encrypted identity attributes (birth year offset, country, compliance (KYC) level, blacklist)
 - **ComplianceRules** — encrypted compliance checks with cached results
 - **CompliantERC20** — demo token enforcing compliance on transfers
 
@@ -142,6 +142,7 @@ See `docs/guide.md` for details and best practices.
 
 - `docs/guide.md` (deployment, testing, faucets, ownership)
 - `docs/architecture.md` (contract flow overview)
+- `CONTRIBUTING.md` (pre-commit checklist, changesets, deployments)
 
 ## Development
 

package/abi/ComplianceRules.json

@@ -8,7 +8,7 @@
       },
       {
         "internalType": "uint8",
-        "name": "initialMinKycLevel",
+        "name": "initialMinComplianceLevel",
         "type": "uint8"
       }
     ],
@@ -92,7 +92,7 @@
         "type": "uint8"
       }
     ],
-    "name": "MinKycLevelUpdated",
+    "name": "MinComplianceLevelUpdated",
     "type": "event"
   },
   {
@@ -268,7 +268,7 @@
   },
   {
     "inputs": [],
-    "name": "minKycLevel",
+    "name": "minComplianceLevel",
     "outputs": [
       {
         "internalType": "uint8",
@@ -331,7 +331,7 @@
         "type": "uint8"
       }
     ],
-    "name": "setMinKycLevel",
+    "name": "setMinComplianceLevel",
     "outputs": [],
     "stateMutability": "nonpayable",
     "type": "function"

package/abi/IdentityRegistry.json

@@ -260,7 +260,7 @@
       },
       {
         "internalType": "externalEuint8",
-        "name": "encKycLevel",
+        "name": "encComplianceLevel",
         "type": "bytes32"
       },
       {
@@ -429,10 +429,10 @@
         "type": "address"
       }
     ],
-    "name": "getCountryCode",
+    "name": "getComplianceLevel",
     "outputs": [
       {
-        "internalType": "euint16",
+        "internalType": "euint8",
         "name": "",
         "type": "bytes32"
       }
@@ -448,12 +448,12 @@
         "type": "address"
       },
       {
-        "internalType": "uint16",
-        "name": "country",
-        "type": "uint16"
+        "internalType": "uint8",
+        "name": "minLevel",
+        "type": "uint8"
       }
     ],
-    "name": "getCountryResult",
+    "name": "getComplianceLevelResult",
     "outputs": [
       {
         "internalType": "ebool",
@@ -472,10 +472,10 @@
         "type": "address"
       }
     ],
-    "name": "getKycLevel",
+    "name": "getCountryCode",
     "outputs": [
       {
-        "internalType": "euint8",
+        "internalType": "euint16",
         "name": "",
         "type": "bytes32"
       }
@@ -491,12 +491,12 @@
         "type": "address"
       },
       {
-        "internalType": "uint8",
-        "name": "minLevel",
-        "type": "uint8"
+        "internalType": "uint16",
+        "name": "country",
+        "type": "uint16"
       }
     ],
-    "name": "getKycLevelResult",
+    "name": "getCountryResult",
     "outputs": [
       {
         "internalType": "ebool",
@@ -533,7 +533,7 @@
         "type": "uint8"
       }
     ],
-    "name": "hasMinKycLevel",
+    "name": "hasMinComplianceLevel",
     "outputs": [
       {
         "internalType": "ebool",

package/contracts/ARCHITECTURE.md

@@ -12,7 +12,7 @@ flowchart TD
     EncIn -- "2) tx call" --> ERC["CompliantERC20"]
 
     subgraph OnChain["On-chain fhEVM"]
-      IR -- "3) Stores encrypted attrs" --> IRState["Encrypted attributes: birthYear/country/kyc/blacklist"]
+      IR -- "3) Stores encrypted attrs" --> IRState["Encrypted attributes: birthYear/country/compliance/blacklist"]
       IR -- "4) ACL grants" --> ACL["ACL per ciphertext handle"]
       ERC -- "5) calls" --> CR["ComplianceRules"]
       CR -- "6) queries" --> IR

package/contracts/ARCHITECTURE_EXPLAINER.md

@@ -11,7 +11,7 @@ sequenceDiagram
     actor User
     participant UI as Zentity Web App (Web2)
     participant BE as Zentity Backend (Web2)
-    participant KYC as KYC/Liveness Services (Web2)
+    participant Verifier as KYC/Liveness Services (Web2)
     participant Registrar as Registrar Wallet (Web3)
     participant IR as IdentityRegistry (fhEVM)
     participant CR as ComplianceRules (fhEVM)
@@ -19,8 +19,8 @@ sequenceDiagram
 
     User->>UI: Complete verification flow (docs + liveness)
     UI->>BE: Submit verification data
-    BE->>KYC: Verify identity and liveness
-    KYC-->>BE: KYC result + attributes
+    BE->>Verifier: Verify identity and liveness
+    Verifier-->>BE: Compliance result + attributes
 
     BE->>UI: Verification complete (Web2)
     UI->>Registrar: Request on-chain attestation
@@ -44,7 +44,7 @@ sequenceDiagram
 
 ### Web2 (Zentity Backend)
 - **Collects and verifies identity data** (documents, liveness, etc.).
-- **Produces the final KYC result** and attribute set.
+- **Produces the final compliance result** and attribute set.
 - **Never stores plaintext on-chain**. Only encrypted attributes are sent to
   Web3 via the registrar flow.
 

package/contracts/compliance/ComplianceRules.sol

@@ -36,8 +36,8 @@ contract ComplianceRules is ZamaEthereumConfig {
     /// @notice Pending owner for two-step ownership transfer
     address public pendingOwner;
 
-    /// @notice Minimum KYC level required for compliance
-    uint8 public minKycLevel;
+    /// @notice Minimum compliance level required for compliance
+    uint8 public minComplianceLevel;
 
     /// @notice Store last compliance check result for each user
     mapping(address user => ebool result) private complianceResults;
@@ -47,9 +47,9 @@ contract ComplianceRules is ZamaEthereumConfig {
 
     // ============ 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 the minimum compliance level requirement is updated
+    /// @param newLevel The new minimum compliance level required for compliance
+    event MinComplianceLevelUpdated(uint8 indexed newLevel);
 
     /// @notice Emitted when a compliance check is performed for a user
     /// @param user Address of the user whose compliance was checked
@@ -107,24 +107,24 @@ contract ComplianceRules is ZamaEthereumConfig {
     /**
      * @notice Initialize with identity registry reference
      * @param registry Address of the IdentityRegistry contract
-     * @param initialMinKycLevel Initial minimum KYC level (default: 1)
+     * @param initialMinComplianceLevel Initial minimum compliance level (default: 1)
      */
-    constructor(address registry, uint8 initialMinKycLevel) {
+    constructor(address registry, uint8 initialMinComplianceLevel) {
         if (registry == address(0)) revert RegistryNotSet();
         identityRegistry = IIdentityRegistry(registry);
         owner = msg.sender;
-        minKycLevel = initialMinKycLevel;
+        minComplianceLevel = initialMinComplianceLevel;
     }
 
     // ============ Admin Functions ============
 
     /**
-     * @notice Update minimum KYC level
+     * @notice Update minimum compliance level
      * @param newLevel New minimum level
      */
-    function setMinKycLevel(uint8 newLevel) external onlyOwner {
-        minKycLevel = newLevel;
-        emit MinKycLevelUpdated(newLevel);
+    function setMinComplianceLevel(uint8 newLevel) external onlyOwner {
+        minComplianceLevel = newLevel;
+        emit MinComplianceLevelUpdated(newLevel);
     }
 
     /**
@@ -162,7 +162,7 @@ contract ComplianceRules is ZamaEthereumConfig {
 
     /**
      * @notice Check if user passes all compliance requirements
-     * @dev Combines: hasMinKycLevel AND isNotBlacklisted
+     * @dev Combines: hasMinComplianceLevel AND isNotBlacklisted
      * @param user Address to check
      * @return Encrypted boolean indicating compliance status
      *
@@ -181,11 +181,11 @@ contract ComplianceRules is ZamaEthereumConfig {
         }
 
         // Get individual compliance checks
-        ebool hasKyc = identityRegistry.hasMinKycLevel(user, minKycLevel);
+        ebool hasCompliance = identityRegistry.hasMinComplianceLevel(user, minComplianceLevel);
         ebool notBlacklisted = identityRegistry.isNotBlacklisted(user);
 
         // Combine all conditions
-        ebool result = FHE.and(hasKyc, notBlacklisted);
+        ebool result = FHE.and(hasCompliance, notBlacklisted);
 
         // Store and grant permissions
         complianceResults[user] = result;
@@ -216,12 +216,12 @@ contract ComplianceRules is ZamaEthereumConfig {
         }
 
         // Get individual compliance checks
-        ebool hasKyc = identityRegistry.hasMinKycLevel(user, minKycLevel);
+        ebool hasCompliance = identityRegistry.hasMinComplianceLevel(user, minComplianceLevel);
         ebool notBlacklisted = identityRegistry.isNotBlacklisted(user);
         ebool isFromAllowedCountry = identityRegistry.isFromCountry(user, allowedCountry);
 
         // Combine all conditions
-        ebool result = FHE.and(FHE.and(hasKyc, notBlacklisted), isFromAllowedCountry);
+        ebool result = FHE.and(FHE.and(hasCompliance, notBlacklisted), isFromAllowedCountry);
 
         // Grant permissions
         FHE.allowThis(result);

package/contracts/core/IdentityRegistry.sol

@@ -9,7 +9,7 @@ import {IIdentityRegistry} from "../interfaces/IIdentityRegistry.sol";
 /**
  * @title IdentityRegistry
  * @author Gustavo Valverde
- * @notice On-chain encrypted identity registry for KYC or compliance platforms
+ * @notice On-chain encrypted identity registry for compliance platforms
  * @dev Part of zentity-fhevm-contracts - Builder Track
  *
  * @custom:category identity
@@ -35,8 +35,8 @@ contract IdentityRegistry is IIdentityRegistry, ZamaEthereumConfig {
     /// @notice Encrypted country code (ISO 3166-1 numeric)
     mapping(address user => euint16 countryCode) private countryCodes;
 
-    /// @notice Encrypted KYC verification level (0-5)
-    mapping(address user => euint8 kycLevel) private kycLevels;
+    /// @notice Encrypted compliance verification level (0-5)
+    mapping(address user => euint8 complianceLevel) private complianceLevels;
 
     /// @notice Encrypted blacklist status
     mapping(address user => ebool blacklisted) private isBlacklisted;
@@ -118,7 +118,7 @@ contract IdentityRegistry is IIdentityRegistry, ZamaEthereumConfig {
         address user,
         externalEuint8 encBirthYearOffset,
         externalEuint16 encCountryCode,
-        externalEuint8 encKycLevel,
+        externalEuint8 encComplianceLevel,
         externalEbool encIsBlacklisted,
         bytes calldata inputProof
     ) external onlyRegistrar {
@@ -127,24 +127,24 @@ contract IdentityRegistry is IIdentityRegistry, ZamaEthereumConfig {
         // Convert and store encrypted values
         euint8 birthYear = FHE.fromExternal(encBirthYearOffset, inputProof);
         euint16 country = FHE.fromExternal(encCountryCode, inputProof);
-        euint8 kyc = FHE.fromExternal(encKycLevel, inputProof);
+        euint8 compliance = FHE.fromExternal(encComplianceLevel, inputProof);
         ebool blacklisted = FHE.fromExternal(encIsBlacklisted, inputProof);
 
         birthYearOffsets[user] = birthYear;
         countryCodes[user] = country;
-        kycLevels[user] = kyc;
+        complianceLevels[user] = compliance;
         isBlacklisted[user] = blacklisted;
 
         // Grant contract permission to all values
         FHE.allowThis(birthYear);
         FHE.allowThis(country);
-        FHE.allowThis(kyc);
+        FHE.allowThis(compliance);
         FHE.allowThis(blacklisted);
 
         // Grant user permission to their own data
         FHE.allow(birthYear, user);
         FHE.allow(country, user);
-        FHE.allow(kyc, user);
+        FHE.allow(compliance, user);
         FHE.allow(blacklisted, user);
 
         uint256 newAttestationId = latestAttestationId[user] + 1;
@@ -169,7 +169,7 @@ contract IdentityRegistry is IIdentityRegistry, ZamaEthereumConfig {
         // Set encrypted values to encrypted zeros
         birthYearOffsets[user] = FHE.asEuint8(0);
         countryCodes[user] = FHE.asEuint16(0);
-        kycLevels[user] = FHE.asEuint8(0);
+        complianceLevels[user] = FHE.asEuint8(0);
         isBlacklisted[user] = FHE.asEbool(false);
         attestationTimestamp[user] = 0;
         currentAttestationId[user] = 0;
@@ -200,10 +200,10 @@ contract IdentityRegistry is IIdentityRegistry, ZamaEthereumConfig {
     }
 
     /// @inheritdoc IIdentityRegistry
-    function getKycLevel(address user) external view returns (euint8) {
+    function getComplianceLevel(address user) external view returns (euint8) {
         if (attestationTimestamp[user] == 0) revert NotAttested();
-        if (!FHE.isSenderAllowed(kycLevels[user])) revert AccessProhibited();
-        return kycLevels[user];
+        if (!FHE.isSenderAllowed(complianceLevels[user])) revert AccessProhibited();
+        return complianceLevels[user];
     }
 
     /// @inheritdoc IIdentityRegistry
@@ -216,10 +216,10 @@ contract IdentityRegistry is IIdentityRegistry, ZamaEthereumConfig {
     // ============ Verification Helpers ============
 
     /// @inheritdoc IIdentityRegistry
-    function hasMinKycLevel(address user, uint8 minLevel) external returns (ebool) {
+    function hasMinComplianceLevel(address user, uint8 minLevel) external returns (ebool) {
         if (attestationTimestamp[user] == 0) revert NotAttested();
-        if (!FHE.isSenderAllowed(kycLevels[user])) revert AccessProhibited();
-        ebool result = FHE.ge(kycLevels[user], FHE.asEuint8(minLevel));
+        if (!FHE.isSenderAllowed(complianceLevels[user])) revert AccessProhibited();
+        ebool result = FHE.ge(complianceLevels[user], FHE.asEuint8(minLevel));
 
         // Store result for later retrieval
         bytes32 key = keccak256(abi.encodePacked(user, uint8(0), uint256(minLevel)));
@@ -269,12 +269,12 @@ contract IdentityRegistry is IIdentityRegistry, ZamaEthereumConfig {
     // ============ Result Getters ============
 
     /**
-     * @notice Get the last KYC level verification result
+     * @notice Get the last compliance level verification result
      * @param user Address that was checked
      * @param minLevel Level that was checked
      * @return Encrypted boolean result
      */
-    function getKycLevelResult(address user, uint8 minLevel) external view returns (ebool) {
+    function getComplianceLevelResult(address user, uint8 minLevel) external view returns (ebool) {
         bytes32 key = keccak256(abi.encodePacked(user, uint8(0), uint256(minLevel)));
         ebool result = verificationResults[key];
         if (!FHE.isSenderAllowed(result)) revert AccessProhibited();
@@ -330,7 +330,7 @@ contract IdentityRegistry is IIdentityRegistry, ZamaEthereumConfig {
 
         FHE.allow(birthYearOffsets[msg.sender], grantee);
         FHE.allow(countryCodes[msg.sender], grantee);
-        FHE.allow(kycLevels[msg.sender], grantee);
+        FHE.allow(complianceLevels[msg.sender], grantee);
         FHE.allow(isBlacklisted[msg.sender], grantee);
 
         emit AccessGranted(msg.sender, grantee);

package/contracts/interfaces/IIdentityRegistry.sol

@@ -108,14 +108,14 @@ interface IIdentityRegistry {
     /// @param user Address of the user being attested
     /// @param encBirthYearOffset Encrypted birth year offset (years since 1900)
     /// @param encCountryCode Encrypted ISO 3166-1 numeric country code
-    /// @param encKycLevel Encrypted KYC verification level (0-3)
+    /// @param encComplianceLevel Encrypted compliance verification level (0-3)
     /// @param encIsBlacklisted Encrypted blacklist status
     /// @param inputProof FHE proof for encrypted inputs
     function attestIdentity(
         address user,
         externalEuint8 encBirthYearOffset,
         externalEuint16 encCountryCode,
-        externalEuint8 encKycLevel,
+        externalEuint8 encComplianceLevel,
         externalEbool encIsBlacklisted,
         bytes calldata inputProof
     ) external;
@@ -136,10 +136,10 @@ interface IIdentityRegistry {
     /// @return Encrypted ISO 3166-1 numeric country code
     function getCountryCode(address user) external view returns (euint16);
 
-    /// @notice Get user's encrypted KYC level
+    /// @notice Get user's encrypted compliance level
     /// @param user Address of the user
-    /// @return Encrypted KYC verification level (0-3)
-    function getKycLevel(address user) external view returns (euint8);
+    /// @return Encrypted compliance (KYC) verification level (0-3)
+    function getComplianceLevel(address user) external view returns (euint8);
 
     /// @notice Get user's encrypted blacklist status
     /// @param user Address of the user
@@ -148,11 +148,11 @@ interface IIdentityRegistry {
 
     // ============ Verification Helpers ============
 
-    /// @notice Check if user has minimum KYC level (encrypted comparison)
+    /// @notice Check if user has minimum compliance level (encrypted comparison)
     /// @param user Address of the user
-    /// @param minLevel Minimum KYC level required
+    /// @param minLevel Minimum compliance level required
     /// @return Encrypted boolean result of comparison
-    function hasMinKycLevel(address user, uint8 minLevel) external returns (ebool);
+    function hasMinComplianceLevel(address user, uint8 minLevel) external returns (ebool);
 
     /// @notice Check if user is from a specific country (encrypted comparison)
     /// @param user Address of the user