@lfdecentralizedtrust/zeto-contracts 0.2.2 → 0.5.0

package/README.md

@@ -1,191 +1,99 @@
-# Sample Implementations of Zeto base Privacy Preserving Tokens
+# Zeto Solidity contracts
 
-This project contains sample implementations of privacy preserving tokens for both fungible and non-fungible assets, using the Zeto toolkit.
+Privacy-preserving token implementations for fungible and non-fungible assets, built with the Zeto ZK toolkit (Groth16 circuits, UTXO model, optional nullifiers and encryption).
 
-# Prerequisites
+## Prerequisites
 
-Running the included tests requires Hardhat:
+- Node.js (see repo CI for supported versions).
+- From this directory (`solidity/`), install dependencies:
+
+  ```console
+  npm install
+  ```
+
+  Hardhat and related tooling are pulled in via `@nomicfoundation/hardhat-toolbox`; you do not need to run `hardhat init` in this repository.
+
+### Circuits and proving keys
+
+Hardhat tests load circuit WASM via **`zeto-js`** (`file:../zkp/js`). Before running tests:
+
+1. Build **zkp/js** and produce **proving keys** and verification artifacts as described in [`../zkp/js/README.md`](../zkp/js/README.md) (build section).
+2. Ensure **`zeto-js` unit tests pass** in `zkp/js` before relying on Solidity tests here.
+3. Set environment variables so tests can find WASM and keys (same layout as CI):
+
+   - **`CIRCUITS_ROOT`**: directory containing compiled circuit artifacts (e.g. `anon_js/`, `anon_nullifier_transfer_js/`, …).
+   - **`PROVING_KEYS_ROOT`**: directory containing the proving key files referenced by the test harness.
+
+Example:
 
 ```console
-npm install --save-dev hardhat
-npx hardhat init
+export CIRCUITS_ROOT=/path/to/zeto-artifacts
+export PROVING_KEYS_ROOT=/path/to/zeto-artifacts
+npm test
 ```
 
-The hardhat test cases make use of the `zeto-js` library, which must be built first. Refer to the steps in [the library's README](/zkp/js/README.md#build) to build the proving keys, and verification keys. Make sure you can successfully run the unit tests for the zeto-js library, before returning back here to continue with the hardhat tests for the Solidity implementation.
+### `@iden3/contracts` (nullifier / SMT)
+
+Tokens that use nullifiers depend on iden3’s Sparse Merkle Tree Solidity library. This workspace expects it at **`../../contracts`** relative to `solidity/` (see `package.json`: `"@iden3/contracts": "file:../../contracts"`).
 
-# Deploy Zeto Token Contracts
+Clone [kaleido-io/contracts](https://github.com/kaleido-io/contracts) (branch **`keccak256`**) next to the **zeto** repo root so the layout is:
+
+```text
+contracts/          # iden3 SMT package (branch keccak256)
+  package.json
+  ...
+zeto/
+  solidity/
+  zkp/
+  ...
+```
 
-Zeto token contracts can be deployed to your hardhat test environment as either upgradeable contracts or cloneable contracts with one of the two hardhat scripts:
+Run **`npm install`** in the **`contracts`** checkout so the file dependency resolves.
 
-## `deploy_upgradeable`
+## Deploying token contracts
 
-Deploys the target contract, designated by the `ZETO_NAME` environment variable, as a [UUPSUpgradeable contract](https://docs.openzeppelin.com/contracts/4.x/api/proxy#transparent-vs-uups). This allows contracts to receive software updates after their initial deployment. For more information about this design pattern, refer to the [OpenZeppelin documentation](https://docs.openzeppelin.com/upgrades-plugins/proxies).
+Scripts deploy the token named by **`ZETO_NAME`** (see `scripts/tokens.json` / Ignition modules for valid names).
+
+### Upgradeable (UUPS proxy)
+
+Deploys the implementation plus an ERC1967 proxy and runs `initialize`. Suitable when you want upgradeability via OpenZeppelin’s UUPS pattern.
 
 ```console
 export ZETO_NAME=Zeto_AnonEncNullifier
 npx hardhat run scripts/deploy_upgradeable.ts
 ```
 
-## `deploy_cloneable`
+Background: [Transparent vs UUPS proxies](https://docs.openzeppelin.com/contracts/5.x/api/proxy#transparent-vs-uups), [Upgrades plugin](https://docs.openzeppelin.com/upgrades-plugins/proxies).
 
-Deploys the target contract, designated by the `ZETO_NAME` environment variable, as a [cloneable contract](https://blog.openzeppelin.com/workshop-recap-cheap-contract-deployment-through-clones).
+### Cloneable / factory workflow
 
 ```console
 export ZETO_NAME=Zeto_AnonEncNullifier
 npx hardhat run scripts/deploy_cloneable.ts
 ```
 
-A cloneable contract can cheaply be cloned into separate instances after deployment. Non-cloneable contracts require re-initializing and copying all contract state, which can result in high gas fees. For more information, refer to the [OpenZeppelin documentation](https://docs.openzeppelin.com/contracts/4.x/api/proxy#Clones).
+This deploys the **implementation only**. Leaf tokens lock the impl with `_disableInitializers()`; **`initialize` runs on proxies** created by **`ZetoTokenFactory`**. Tests use **`USE_FACTORY=true`** in `test/lib/deploy.ts` to register the impl and deploy initialized clones. Running the script **by itself** does not yield a ready-to-use initialized token unless you finish that factory flow.
+
+For a single initialized deployment without the factory path, use **`deploy_upgradeable.ts`**.
 
-# Run The Hardhat Tests
+Cheap repeat deployments: OpenZeppelin [minimal proxies / Clones](https://docs.openzeppelin.com/contracts/5.x/api/utils#Clones).
 
-Once you have run one of the sample deployment scripts above, you can proceed to run the hardhat tests in this project.
+## Running tests
 
 ```console
-npm i
-npm t
-
-> zeto@0.0.1 test
-> npx hardhat test
-
-
-
-  Registry tests
-Registry deployed to 0x5FbDB2315678afecb367f032d93F642f64180aa3
-    ✔ should register a new user (43ms)
-    ✔ should return the correct public key
-
-  Zeto based fungible token with anonymity without encryption or nullifier
-Method mint() complete. Gas used: 75301
-Witness calculation time: 38ms, Proof generation time: 334ms
-Method transfer() complete. Gas used: 336231
-    ✔ mint to Alice and transfer UTXOs honestly to Bob should succeed (395ms)
-Method mint() complete. Gas used: 50947
-Witness calculation time: 19ms, Proof generation time: 179ms
-Method transfer() complete. Gas used: 336337
-    ✔ Bob transfers UTXOs, previously received from Alice, honestly to Charlie should succeed (215ms)
-    ✔ mint existing unspent UTXOs should fail
-    ✔ mint existing spent UTXOs should fail
-Witness calculation time: 20ms, Proof generation time: 178ms
-    ✔ transfer non-existing UTXOs should fail (207ms)
-Witness calculation time: 20ms, Proof generation time: 181ms
-    ✔ transfer spent UTXOs should fail (double spend protection) (210ms)
-Witness calculation time: 19ms, Proof generation time: 193ms
-    ✔ spend by using the same UTXO as both inputs should fail (222ms)
-
-  Zeto based fungible token with anonymity and encryption
-Method mint() complete. Gas used: 75301
-Witness calculation time: 52ms, Proof generation time: 359ms
-Method transfer() complete. Gas used: 362628
-    ✔ mint to Alice and transfer UTXOs honestly to Bob should succeed (449ms)
-Witness calculation time: 33ms, Proof generation time: 336ms
-Method transfer() complete. Gas used: 355662
-    ✔ Bob transfers UTXOs, previously received from Alice, honestly to Charlie should succeed (383ms)
-    ✔ mint existing unspent UTXOs should fail
-    ✔ mint existing spent UTXOs should fail
-Witness calculation time: 32ms, Proof generation time: 334ms
-    ✔ transfer non-existing UTXOs should fail (376ms)
-Witness calculation time: 33ms, Proof generation time: 378ms
-    ✔ transfer spent UTXOs should fail (double spend protection) (421ms)
-Method mint() complete. Gas used: 50959
-Witness calculation time: 33ms, Proof generation time: 341ms
-    ✔ spend by using the same UTXO as both inputs should fail (385ms)
-
-  Zeto based fungible token with anonymity using nullifiers and encryption
-    ✔ onchain SMT root should be equal to the offchain SMT root
-Method mint() complete. Gas used: 823254
-Witness calculation time: 118ms. Proof generation time: 2288ms.
-Time to execute transaction: 40ms. Gas used: 1763072
-    ✔ mint to Alice and transfer UTXOs honestly to Bob should succeed (2491ms)
-Witness calculation time: 80ms. Proof generation time: 2235ms.
-Time to execute transaction: 28ms. Gas used: 1677252
-    ✔ Bob transfers UTXOs, previously received from Alice, honestly to Charlie should succeed (2351ms)
-    ✔ mint existing unspent UTXOs should fail
-    ✔ mint existing spent UTXOs should fail
-Witness calculation time: 77ms. Proof generation time: 2345ms.
-    ✔ transfer spent UTXOs should fail (double spend protection) (2435ms)
-Method mint() complete. Gas used: 878936
-Witness calculation time: 78ms. Proof generation time: 2248ms.
-    ✔ transfer with existing UTXOs in the output should fail (mass conservation protection) (2362ms)
-Witness calculation time: 77ms. Proof generation time: 2292ms.
-    ✔ spend by using the same UTXO as both inputs should fail (2381ms)
-Witness calculation time: 78ms. Proof generation time: 2324ms.
-    ✔ transfer non-existing UTXOs should fail (2454ms)
-
-  Zeto based fungible token with anonymity using nullifiers without encryption
-    ✔ onchain SMT root should be equal to the offchain SMT root
-Method mint() complete. Gas used: 906173
-Witness calculation time: 105ms. Proof generation time: 2151ms.
-Time to execute transaction: 30ms. Gas used: 1737824
-    ✔ mint to Alice and transfer UTXOs honestly to Bob should succeed (2312ms)
-Witness calculation time: 63ms. Proof generation time: 2137ms.
-Time to execute transaction: 33ms. Gas used: 2025451
-    ✔ Bob transfers UTXOs, previously received from Alice, honestly to Charlie should succeed (2245ms)
-    ✔ mint existing unspent UTXOs should fail
-    ✔ mint existing spent UTXOs should fail
-Witness calculation time: 64ms. Proof generation time: 2181ms.
-    ✔ transfer spent UTXOs should fail (double spend protection) (2256ms)
-Method mint() complete. Gas used: 941948
-Witness calculation time: 64ms. Proof generation time: 2171ms.
-    ✔ transfer with existing UTXOs in the output should fail (mass conservation protection) (2272ms)
-Witness calculation time: 64ms. Proof generation time: 2128ms.
-    ✔ spend by using the same UTXO as both inputs should fail (2202ms)
-Witness calculation time: 63ms. Proof generation time: 2183ms.
-    ✔ transfer non-existing UTXOs should fail (2294ms)
-
-  Zeto based non-fungible token with anonymity without encryption or nullifiers
-Method mint() complete. Gas used: 50959
-Witness calculation time: 39ms, Proof generation time: 116ms
-Method transfer() complete. Gas used: 288112
-    ✔ mint to Alice and transfer UTXOs honestly to Bob should succeed (170ms)
-Witness calculation time: 19ms, Proof generation time: 120ms
-Method transfer() complete. Gas used: 288136
-    ✔ Bob transfers UTXOs, previously received from Alice, honestly to Charlie should succeed (152ms)
-    ✔ mint existing unspent UTXOs should fail
-    ✔ mint existing spent UTXOs should fail
-Witness calculation time: 19ms, Proof generation time: 150ms
-    ✔ transfer non-existing UTXOs should fail (179ms)
-Witness calculation time: 18ms, Proof generation time: 115ms
-    ✔ transfer spent UTXOs should fail (double spend protection) (141ms)
-
-  Zeto based non-fungible token with anonymity using nullifiers without encryption
-    ✔ onchain SMT root should be equal to the offchain SMT root
-Method mint() complete. Gas used: 338260
-Witness calculation time: 84ms. Proof generation time: 1137ms.
-Time to execute transaction: 17ms. Gas used: 796127
-    ✔ mint to Alice and transfer UTXOs honestly to Bob should succeed (1250ms)
-Witness calculation time: 46ms. Proof generation time: 1172ms.
-Time to execute transaction: 19ms. Gas used: 909983
-    ✔ Bob transfers UTXOs, previously received from Alice, honestly to Charlie should succeed (1243ms)
-    ✔ mint existing unspent UTXOs should fail
-    ✔ mint existing spent UTXOs should fail
-Witness calculation time: 41ms. Proof generation time: 1146ms.
-    ✔ transfer spent UTXOs should fail (double spend protection) (1196ms)
-Witness calculation time: 38ms. Proof generation time: 1163ms.
-    ✔ transfer non-existing UTXOs should fail (1229ms)
-
-  DvP flows between fungible and non-fungible tokens based on Zeto with anonymity without encryption or nullifiers
-ZK Asset contract deployed at 0xf4B146FbA71F41E0592668ffbF264F1D186b2Ca8
-ZK Payment contract deployed at 0xBEc49fA140aCaA83533fB00A2BB19bDdd0290f25
-Method mint() complete. Gas used: 75289
-    ✔ mint to Alice some payment tokens
-Method mint() complete. Gas used: 75277
-    ✔ mint to Bob some asset tokens
-    ✔ Initiating a DvP transaction without payment input or asset input should fail
-    ✔ Initiating a DvP transaction with payment input but no payment output should fail
-    ✔ Initiating a DvP transaction with payment inputs and asset inputs should fail
-    ✔ Initiating a DvP transaction with asset input but no asset output should fail
-    ✔ Initiating a successful DvP transaction with payment inputs
-    ✔ Initiating a successful DvP transaction with asset inputs
-    ✔ Accepting a trade using an invalid trade ID should fail
-    ✔ Failing cases for accepting a trade with payment terms
-    ✔ Failing cases for accepting a trade with asset terms
-Method mint() complete. Gas used: 50959
-Method mint() complete. Gas used: 50959
-Witness calculation time: 36ms, Proof generation time: 183ms
-Witness calculation time: 38ms, Proof generation time: 121ms
-    ✔ Initiating a successful DvP transaction with payment inputs and accepting by specifying asset inputs (421ms)
-
-
-  59 passing (41s)
+npm install
+npm test
 ```
+
+`pretest` runs Prettier on `contracts`, `scripts`, `ignition`, and `test`; fix formatting or run `npm run prettier:fix` if the check fails.
+
+Optional:
+
+- **`USE_FACTORY=true`**: exercise the factory deployment path (cloneable impl + `ZetoTokenFactory`) in addition to the default upgradeable path when relevant tests support it.
+
+Successful runs exercise mint/transfer/withdraw flows, nullifier trees, registry helpers, DvP samples, and gas-heavy suites depending on which circuits and keys are present.
+
+## Further reading
+
+- Token variants and feature matrix: [`doc-site/docs/implementations/`](../doc-site/docs/implementations/) (repository root).
+- Circuit sources: [`../zkp/circuits/`](../zkp/circuits/).

package/contracts/factory.sol

@@ -15,9 +15,9 @@
 // limitations under the License.
 pragma solidity ^0.8.27;
 
-import {Clones} from "@openzeppelin/contracts/proxy/Clones.sol";
 import {Ownable} from "@openzeppelin/contracts/access/Ownable.sol";
-import {IZetoInitializable} from "./lib/interfaces/izeto_initializable.sol";
+import {ERC1967Proxy} from "@openzeppelin/contracts/proxy/ERC1967/ERC1967Proxy.sol";
+import {IZetoInitializable} from "./lib/interfaces/IZetoInitializable.sol";
 
 contract ZetoTokenFactory is Ownable {
     // all the addresses needed by the factory to
@@ -36,7 +36,7 @@ contract ZetoTokenFactory is Ownable {
     constructor() Ownable(msg.sender) {}
 
     function registerImplementation(
-        string memory name,
+        string calldata name,
         ImplementationInfo memory implementation
     ) public onlyOwner {
         require(
@@ -44,7 +44,7 @@ contract ZetoTokenFactory is Ownable {
             "Factory: implementation address is required"
         );
         require(
-            implementation.verifiers.verifier != address(0),
+            address(implementation.verifiers.verifier) != address(0),
             "Factory: verifier address is required"
         );
         // the depositVerifier and withdrawVerifier are optional
@@ -53,9 +53,9 @@ contract ZetoTokenFactory is Ownable {
     }
 
     function deployZetoFungibleToken(
-        string memory name,
-        string memory symbol,
-        string memory tokenImplementation,
+        string calldata name,
+        string calldata symbol,
+        string calldata tokenImplementation,
         address initialOwner
     ) public returns (address) {
         ImplementationInfo memory args = implementations[tokenImplementation];
@@ -66,40 +66,38 @@ contract ZetoTokenFactory is Ownable {
         // check that the registered implementation is for a fungible token
         // and has the required verifier addresses
         require(
-            args.verifiers.depositVerifier != address(0),
+            address(args.verifiers.depositVerifier) != address(0),
             "Factory: depositVerifier address is required"
         );
         require(
-            args.verifiers.withdrawVerifier != address(0),
+            address(args.verifiers.withdrawVerifier) != address(0),
             "Factory: withdrawVerifier address is required"
         );
         require(
-            args.verifiers.batchVerifier != address(0),
+            address(args.verifiers.batchVerifier) != address(0),
             "Factory: batchVerifier address is required"
         );
         require(
-            args.verifiers.batchWithdrawVerifier != address(0),
+            address(args.verifiers.batchWithdrawVerifier) != address(0),
             "Factory: batchWithdrawVerifier address is required"
         );
-        address instance = Clones.clone(args.implementation);
-        require(
-            instance != address(0),
-            "Factory: failed to clone implementation"
-        );
-        (IZetoInitializable(instance)).initialize(
-            name,
-            symbol,
-            initialOwner,
-            args.verifiers
+        address instance = address(
+            new ERC1967Proxy(
+                args.implementation,
+                abi.encodeCall(
+                    IZetoInitializable.initialize,
+                    (name, symbol, initialOwner, args.verifiers)
+                )
+            )
         );
         emit ZetoTokenDeployed(instance);
         return instance;
     }
 
     function deployZetoNonFungibleToken(
-        string memory name,
-        string memory symbol,
-        string memory tokenImplementation,
+        string calldata name,
+        string calldata symbol,
+        string calldata tokenImplementation,
         address initialOwner
     ) public returns (address) {
         ImplementationInfo memory args = implementations[tokenImplementation];
@@ -107,16 +105,14 @@ contract ZetoTokenFactory is Ownable {
             args.implementation != address(0),
             "Factory: failed to find implementation"
         );
-        address instance = Clones.clone(args.implementation);
-        require(
-            instance != address(0),
-            "Factory: failed to clone implementation"
-        );
-        (IZetoInitializable(instance)).initialize(
-            name,
-            symbol,
-            initialOwner,
-            args.verifiers
+        address instance = address(
+            new ERC1967Proxy(
+                args.implementation,
+                abi.encodeCall(
+                    IZetoInitializable.initialize,
+                    (name, symbol, initialOwner, args.verifiers)
+                )
+            )
         );
         emit ZetoTokenDeployed(instance);
         return instance;

package/contracts/factory_upgradeable.sol

@@ -19,9 +19,13 @@ import {Initializable} from "@openzeppelin/contracts-upgradeable/proxy/utils/Ini
 import {OwnableUpgradeable} from "@openzeppelin/contracts-upgradeable/access/OwnableUpgradeable.sol";
 import {UUPSUpgradeable} from "@openzeppelin/contracts-upgradeable/proxy/utils/UUPSUpgradeable.sol";
 import {Clones} from "@openzeppelin/contracts/proxy/Clones.sol";
-import {IZetoInitializable} from "./lib/interfaces/izeto_initializable.sol";
+import {IZetoInitializable} from "./lib/interfaces/IZetoInitializable.sol";
 
-contract ZetoTokenFactoryUpgradeable is Initializable, OwnableUpgradeable, UUPSUpgradeable {
+contract ZetoTokenFactoryUpgradeable is
+    Initializable,
+    OwnableUpgradeable,
+    UUPSUpgradeable
+{
     // all the addresses needed by the factory to
     // clone a Zeto token and initialize it. The
     // "implementation" is used to clone the token,
@@ -71,7 +75,7 @@ contract ZetoTokenFactoryUpgradeable is Initializable, OwnableUpgradeable, UUPSU
             "Factory: implementation address is required"
         );
         require(
-            implementation.verifiers.verifier != address(0),
+            address(implementation.verifiers.verifier) != address(0),
             "Factory: verifier address is required"
         );
         // the depositVerifier and withdrawVerifier are optional
@@ -95,19 +99,19 @@ contract ZetoTokenFactoryUpgradeable is Initializable, OwnableUpgradeable, UUPSU
         // check that the registered implementation is for a fungible token
         // and has the required verifier addresses
         require(
-            args.verifiers.depositVerifier != address(0),
+            address(args.verifiers.depositVerifier) != address(0),
             "Factory: depositVerifier address is required"
         );
         require(
-            args.verifiers.withdrawVerifier != address(0),
+            address(args.verifiers.withdrawVerifier) != address(0),
             "Factory: withdrawVerifier address is required"
         );
         require(
-            args.verifiers.batchVerifier != address(0),
+            address(args.verifiers.batchVerifier) != address(0),
             "Factory: batchVerifier address is required"
         );
         require(
-            args.verifiers.batchWithdrawVerifier != address(0),
+            address(args.verifiers.batchWithdrawVerifier) != address(0),
             "Factory: batchWithdrawVerifier address is required"
         );
         address instance = Clones.clone(args.implementation);

package/contracts/lib/common/util.sol

@@ -0,0 +1,40 @@
+// Copyright © 2025 Kaleido, Inc.
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+pragma solidity ^0.8.27;
+
+import {Arrays} from "@openzeppelin/contracts/utils/Arrays.sol";
+import {PoseidonUnit3L} from "@iden3/contracts/contracts/lib/Poseidon.sol";
+
+library Util {
+    function sortCommitments(
+        uint256[] memory utxos
+    ) internal pure returns (uint256[] memory) {
+        uint256[] memory sorted = new uint256[](utxos.length);
+        for (uint256 i = 0; i < utxos.length; ++i) {
+            sorted[i] = utxos[i];
+        }
+        sorted = Arrays.sort(sorted);
+        return sorted;
+    }
+
+    function getLeafNodeHash(
+        uint256 index,
+        uint256 value
+    ) internal pure returns (uint256) {
+        uint256[3] memory params = [index, value, uint256(1)];
+        return PoseidonUnit3L.poseidon(params);
+    }
+}