@zentity/fhevm-contracts 0.1.0

package/README.md

@@ -0,0 +1,160 @@
+# @zentity/fhevm-contracts
+
+fhEVM smart contracts for privacy-preserving identity attestations.
+
+## Overview
+
+This package provides Solidity contracts using Zama's fhEVM:
+
+- **IdentityRegistry** — encrypted identity attributes (birth year offset, country, KYC, blacklist)
+- **ComplianceRules** — encrypted compliance checks with cached results
+- **CompliantERC20** — demo token enforcing compliance on transfers
+
+## Installation
+
+```bash
+npm install @zentity/fhevm-contracts
+```
+
+## Quickstart (local)
+
+```bash
+bun install
+bun run compile
+bun run test:mocked
+
+# terminal 1
+bunx hardhat node
+
+# terminal 2
+bun run deploy:local
+bun run print:deployments localhost --env
+```
+
+## Quickstart (Sepolia)
+
+1) Set env values in `.env.local`:
+
+```
+FHEVM_RPC_URL=...
+FHEVM_PROVIDER_ID=zama # zama = Zama relayer SDK
+PRIVATE_KEY=0x...
+```
+
+Tip: keep shared defaults in `.env` and secrets in `.env.local`.
+See `docs/deployment.md` for the full env-file behavior.
+
+2) Deploy and print addresses:
+
+```bash
+bun run deploy:sepolia
+bun run print:deployments sepolia --env
+```
+
+3) Run integration smoke tests:
+
+```bash
+bun run test:sepolia
+```
+
+## Usage
+
+Minimal setup (addresses + ABI):
+
+```typescript
+import {
+  getContractAddresses,
+  getAbi,
+} from "@zentity/fhevm-contracts";
+
+const addresses = getContractAddresses("hardhat");
+const identityRegistry = new ethers.Contract(
+  addresses.IdentityRegistry,
+  getAbi("IdentityRegistry"),
+  signer
+);
+```
+
+Direct ABI imports:
+
+```typescript
+import { IdentityRegistryABI } from "@zentity/fhevm-contracts";
+// or
+import { IdentityRegistryABI } from "@zentity/fhevm-contracts/abi";
+```
+
+Address helpers:
+
+```typescript
+import {
+  getContractAddresses,
+  resolveContractAddresses,
+  getNetworkName,
+  hasDeployment,
+  CHAIN_ID_BY_NETWORK,
+} from "@zentity/fhevm-contracts";
+
+const network = getNetworkName(31337, "hardhat");
+if (!hasDeployment(network)) throw new Error("Missing deployments");
+
+const addresses = getContractAddresses(network, {
+  overrides: { ComplianceRules: "0x..." },
+});
+
+// Sepolia or other networks without bundled deployments:
+const sepoliaAddresses = resolveContractAddresses("sepolia", {
+  overrides: {
+    IdentityRegistry: "0x...",
+    ComplianceRules: "0x...",
+    CompliantERC20: "0x...",
+  },
+});
+```
+
+## Addresses & deployments
+
+Deployments are stored in `deployments/<network>`. Use the helper script to
+print them as JSON or env-style output:
+
+```bash
+bun run print:deployments
+bun run print:deployments sepolia --env
+```
+
+## Networks
+
+| Network | Chain ID | RPC |
+|---------|----------|-----|
+| Sepolia | 11155111 | https://ethereum-sepolia-rpc.publicnode.com |
+| Localhost | 31337 | http://127.0.0.1:8545 |
+
+Note: only networks with a deployment manifest in `deployments/<network>` are
+available via `getContractAddresses()` out of the box.
+
+## Ownership & admin safety
+
+Admin-managed contracts use **two-step ownership transfer**:
+`transferOwnership(newOwner)` → `acceptOwnership()`.
+
+See `docs/guide.md` for details and best practices.
+
+## Documentation
+
+- `docs/guide.md` (deployment, testing, faucets, ownership)
+- `docs/architecture.md` (contract flow overview)
+
+## Development
+
+This repo uses Bun by default. If you prefer npm, replace `bun run <script>`
+with `npm run <script>`.
+
+Common scripts:
+- `bun run compile`
+- `bun run test:mocked`
+- `bun run test`
+- `bun run deploy:local`
+- `bun run deploy:sepolia`
+
+## License
+
+MIT

package/abi/ComplianceRules.json

@@ -0,0 +1,352 @@
+[
+  {
+    "inputs": [
+      {
+        "internalType": "address",
+        "name": "registry",
+        "type": "address"
+      },
+      {
+        "internalType": "uint8",
+        "name": "initialMinKycLevel",
+        "type": "uint8"
+      }
+    ],
+    "stateMutability": "nonpayable",
+    "type": "constructor"
+  },
+  {
+    "inputs": [],
+    "name": "AccessProhibited",
+    "type": "error"
+  },
+  {
+    "inputs": [],
+    "name": "CallerNotAuthorized",
+    "type": "error"
+  },
+  {
+    "inputs": [],
+    "name": "InvalidOwner",
+    "type": "error"
+  },
+  {
+    "inputs": [],
+    "name": "OnlyOwner",
+    "type": "error"
+  },
+  {
+    "inputs": [],
+    "name": "OnlyPendingOwner",
+    "type": "error"
+  },
+  {
+    "inputs": [],
+    "name": "RegistryNotSet",
+    "type": "error"
+  },
+  {
+    "inputs": [],
+    "name": "ZamaProtocolUnsupported",
+    "type": "error"
+  },
+  {
+    "anonymous": false,
+    "inputs": [
+      {
+        "indexed": true,
+        "internalType": "address",
+        "name": "caller",
+        "type": "address"
+      },
+      {
+        "indexed": false,
+        "internalType": "bool",
+        "name": "allowed",
+        "type": "bool"
+      }
+    ],
+    "name": "AuthorizedCallerUpdated",
+    "type": "event"
+  },
+  {
+    "anonymous": false,
+    "inputs": [
+      {
+        "indexed": true,
+        "internalType": "address",
+        "name": "user",
+        "type": "address"
+      }
+    ],
+    "name": "ComplianceChecked",
+    "type": "event"
+  },
+  {
+    "anonymous": false,
+    "inputs": [
+      {
+        "indexed": true,
+        "internalType": "uint8",
+        "name": "newLevel",
+        "type": "uint8"
+      }
+    ],
+    "name": "MinKycLevelUpdated",
+    "type": "event"
+  },
+  {
+    "anonymous": false,
+    "inputs": [
+      {
+        "indexed": true,
+        "internalType": "address",
+        "name": "currentOwner",
+        "type": "address"
+      },
+      {
+        "indexed": true,
+        "internalType": "address",
+        "name": "pendingOwner",
+        "type": "address"
+      }
+    ],
+    "name": "OwnershipTransferStarted",
+    "type": "event"
+  },
+  {
+    "anonymous": false,
+    "inputs": [
+      {
+        "indexed": true,
+        "internalType": "address",
+        "name": "previousOwner",
+        "type": "address"
+      },
+      {
+        "indexed": true,
+        "internalType": "address",
+        "name": "newOwner",
+        "type": "address"
+      }
+    ],
+    "name": "OwnershipTransferred",
+    "type": "event"
+  },
+  {
+    "inputs": [],
+    "name": "acceptOwnership",
+    "outputs": [],
+    "stateMutability": "nonpayable",
+    "type": "function"
+  },
+  {
+    "inputs": [
+      {
+        "internalType": "address",
+        "name": "caller",
+        "type": "address"
+      }
+    ],
+    "name": "authorizedCallers",
+    "outputs": [
+      {
+        "internalType": "bool",
+        "name": "authorized",
+        "type": "bool"
+      }
+    ],
+    "stateMutability": "view",
+    "type": "function"
+  },
+  {
+    "inputs": [
+      {
+        "internalType": "address",
+        "name": "user",
+        "type": "address"
+      }
+    ],
+    "name": "checkCompliance",
+    "outputs": [
+      {
+        "internalType": "ebool",
+        "name": "",
+        "type": "bytes32"
+      }
+    ],
+    "stateMutability": "nonpayable",
+    "type": "function"
+  },
+  {
+    "inputs": [
+      {
+        "internalType": "address",
+        "name": "user",
+        "type": "address"
+      },
+      {
+        "internalType": "uint16",
+        "name": "allowedCountry",
+        "type": "uint16"
+      }
+    ],
+    "name": "checkComplianceWithCountry",
+    "outputs": [
+      {
+        "internalType": "ebool",
+        "name": "",
+        "type": "bytes32"
+      }
+    ],
+    "stateMutability": "nonpayable",
+    "type": "function"
+  },
+  {
+    "inputs": [],
+    "name": "confidentialProtocolId",
+    "outputs": [
+      {
+        "internalType": "uint256",
+        "name": "",
+        "type": "uint256"
+      }
+    ],
+    "stateMutability": "view",
+    "type": "function"
+  },
+  {
+    "inputs": [
+      {
+        "internalType": "address",
+        "name": "user",
+        "type": "address"
+      }
+    ],
+    "name": "getComplianceResult",
+    "outputs": [
+      {
+        "internalType": "ebool",
+        "name": "",
+        "type": "bytes32"
+      }
+    ],
+    "stateMutability": "view",
+    "type": "function"
+  },
+  {
+    "inputs": [
+      {
+        "internalType": "address",
+        "name": "user",
+        "type": "address"
+      }
+    ],
+    "name": "hasComplianceResult",
+    "outputs": [
+      {
+        "internalType": "bool",
+        "name": "",
+        "type": "bool"
+      }
+    ],
+    "stateMutability": "view",
+    "type": "function"
+  },
+  {
+    "inputs": [],
+    "name": "identityRegistry",
+    "outputs": [
+      {
+        "internalType": "contract IIdentityRegistry",
+        "name": "",
+        "type": "address"
+      }
+    ],
+    "stateMutability": "view",
+    "type": "function"
+  },
+  {
+    "inputs": [],
+    "name": "minKycLevel",
+    "outputs": [
+      {
+        "internalType": "uint8",
+        "name": "",
+        "type": "uint8"
+      }
+    ],
+    "stateMutability": "view",
+    "type": "function"
+  },
+  {
+    "inputs": [],
+    "name": "owner",
+    "outputs": [
+      {
+        "internalType": "address",
+        "name": "",
+        "type": "address"
+      }
+    ],
+    "stateMutability": "view",
+    "type": "function"
+  },
+  {
+    "inputs": [],
+    "name": "pendingOwner",
+    "outputs": [
+      {
+        "internalType": "address",
+        "name": "",
+        "type": "address"
+      }
+    ],
+    "stateMutability": "view",
+    "type": "function"
+  },
+  {
+    "inputs": [
+      {
+        "internalType": "address",
+        "name": "caller",
+        "type": "address"
+      },
+      {
+        "internalType": "bool",
+        "name": "allowed",
+        "type": "bool"
+      }
+    ],
+    "name": "setAuthorizedCaller",
+    "outputs": [],
+    "stateMutability": "nonpayable",
+    "type": "function"
+  },
+  {
+    "inputs": [
+      {
+        "internalType": "uint8",
+        "name": "newLevel",
+        "type": "uint8"
+      }
+    ],
+    "name": "setMinKycLevel",
+    "outputs": [],
+    "stateMutability": "nonpayable",
+    "type": "function"
+  },
+  {
+    "inputs": [
+      {
+        "internalType": "address",
+        "name": "newOwner",
+        "type": "address"
+      }
+    ],
+    "name": "transferOwnership",
+    "outputs": [],
+    "stateMutability": "nonpayable",
+    "type": "function"
+  }
+]