@permissionless-technologies/upp-sdk 0.1.0

package/package.json

@@ -0,0 +1,119 @@
+{
+  "name": "@permissionless-technologies/upp-sdk",
+  "version": "0.1.0",
+  "description": "Universal Private Pool SDK - Privacy-preserving token operations for any ERC20",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./core": {
+      "types": "./dist/core/index.d.ts",
+      "import": "./dist/core/index.js",
+      "require": "./dist/core/index.cjs"
+    },
+    "./utils": {
+      "types": "./dist/utils/index.d.ts",
+      "import": "./dist/utils/index.js",
+      "require": "./dist/utils/index.cjs"
+    },
+    "./keys": {
+      "types": "./dist/keys/index.d.ts",
+      "import": "./dist/keys/index.js",
+      "require": "./dist/keys/index.cjs"
+    },
+    "./react": {
+      "types": "./dist/react/index.d.ts",
+      "import": "./dist/react/index.js",
+      "require": "./dist/react/index.cjs"
+    },
+    "./indexer": {
+      "types": "./dist/indexer/index.d.ts",
+      "import": "./dist/indexer/index.js",
+      "require": "./dist/indexer/index.cjs"
+    },
+    "./stwo-prover": {
+      "types": "./stwo-prover/pkg/upp_stwo_prover.d.ts",
+      "import": "./stwo-prover/pkg/upp_stwo_prover.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src/deployments/*.json",
+    "src/contracts/interfaces/*.sol"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest",
+    "test:run": "vitest run",
+    "lint": "eslint src --ext .ts",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build",
+    "circuits:compile": "node scripts/compile-circuits.js",
+    "circuits:setup": "node scripts/setup-circuits.js",
+    "circuits:verifiers": "node scripts/generate-verifiers.js",
+    "deploy:local": "forge script src/contracts/script/DeployUPP.s.sol:DeployUPPLocal --rpc-url http://localhost:8545 --broadcast --private-key 0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80 && node scripts/extract-deployment.js 31337",
+    "deploy:sepolia": "source .env && forge script src/contracts/script/DeployUPP.s.sol:DeployUPPSepolia --rpc-url ${RPC_ENDPOINT_TESTNET} --broadcast --private-key ${PRIVATE_KEY_TESTNET} && node scripts/extract-deployment.js 11155111",
+    "extract:deployment": "node scripts/extract-deployment.js",
+    "generate:abis": "node scripts/generate-abis.js"
+  },
+  "keywords": [
+    "ethereum",
+    "privacy",
+    "zk",
+    "zero-knowledge",
+    "stealth-address",
+    "erc20",
+    "viem"
+  ],
+  "author": "",
+  "license": "AGPL-3.0-or-later",
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0",
+    "viem": "^2.0.0",
+    "wagmi": "^2.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "wagmi": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "@noble/curves": "^1.4.0",
+    "@permissionless-technologies/upc-sdk": "^0.1.0",
+    "@zk-kit/lean-imt.sol": "^2.0.1",
+    "@zk-kit/poseidon-cipher": "^0.3.0",
+    "bech32": "^2.0.0",
+    "circomlib": "^2.0.5",
+    "circomlibjs": "^0.1.7",
+    "poseidon-solidity": "^0.0.5",
+    "snarkjs": "^0.7.4"
+  },
+  "devDependencies": {
+    "@rainbow-me/rainbowkit": "^2.0.0",
+    "@tanstack/react-query": "^5.0.0",
+    "@types/node": "^20.0.0",
+    "@types/react": "^18.0.0 || ^19.0.0",
+    "@types/react-dom": "^19.2.3",
+    "@types/snarkjs": "^0.7.8",
+    "eslint": "^8.0.0",
+    "react": "^19.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0",
+    "viem": "^2.0.0",
+    "vitest": "^1.0.0",
+    "wagmi": "^2.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/src/contracts/interfaces/IASPRegistry.sol

@@ -0,0 +1,36 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.20;
+
+/// @notice ASP Registry Hub interface
+/// @dev Manages multiple ASP (Association Set Provider) whitelists
+interface IASPRegistryHub {
+    /// @notice Check if an ASP root is valid for a given ASP ID
+    /// @param aspId The ASP identifier
+    /// @param root The claimed ASP Merkle root
+    /// @return True if the root is currently valid for that ASP
+    function isValidASPRoot(uint256 aspId, uint256 root) external view returns (bool);
+
+    /// @notice Get current ASP root for an ASP ID
+    /// @param aspId The ASP identifier
+    /// @return The current root of that ASP's whitelist tree
+    function getCurrentRoot(uint256 aspId) external view returns (uint256);
+
+    /// @notice Register a new ASP
+    /// @param name Human-readable name for the ASP
+    /// @return aspId The assigned ASP identifier
+    function registerASP(string calldata name) external returns (uint256 aspId);
+
+    /// @notice Update an ASP's root (only ASP operator)
+    /// @param aspId The ASP identifier
+    /// @param newRoot The new whitelist root
+    function updateRoot(uint256 aspId, uint256 newRoot) external;
+}
+
+/// @notice Individual ASP information
+struct ASPInfo {
+    uint256 id;
+    address operator;
+    string name;
+    uint256 currentRoot;
+    uint256 lastUpdated;
+}

package/src/contracts/interfaces/IUniversalPrivatePool.sol

@@ -0,0 +1,260 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.20;
+
+/// @notice Interface for the Universal Private Pool
+interface IUniversalPrivatePool {
+    // ============ Events ============
+
+    event CommitmentInserted(
+        bytes32 indexed commitment,
+        uint256 leafIndex,
+        uint256 timestamp
+    );
+
+    event StarkCommitmentInserted(
+        uint128 indexed commitment,
+        uint256 leafIndex,
+        uint256 timestamp
+    );
+
+    event Shielded(
+        address indexed token,
+        address indexed depositor,
+        bytes32 indexed commitment,
+        uint256 leafIndex,
+        bytes encryptedNote
+    );
+
+    event Transferred(
+        bytes32 indexed nullifier,
+        bytes32 indexed outputCommitment1,
+        bytes32 indexed outputCommitment2,
+        bytes encryptedNote1,
+        bytes encryptedNote2
+    );
+
+    event Merged(
+        bytes32 indexed outputCommitment,
+        bytes32 indexed nullifier1,
+        bytes32 indexed nullifier2,
+        address merger,
+        address token
+    );
+
+    event Withdrawn(
+        address indexed token,
+        address indexed recipient,
+        bytes32 indexed nullifier,
+        uint256 amount,
+        bool isRagequit
+    );
+
+    event JoinSplit(
+        bytes32[4] nullifiers,
+        bytes32 indexed outputCommitment1,
+        bytes32 indexed outputCommitment2,
+        bytes encryptedNote1,
+        bytes encryptedNote2
+    );
+
+    event MergeTransfer(
+        bytes32 indexed nullifier1,
+        bytes32 indexed nullifier2,
+        bytes32 nullifier3,
+        bytes32 nullifier4,
+        bytes32 outputCommitment1,
+        bytes32 outputCommitment2,
+        address merger,
+        address token
+    );
+
+    event SwapOrderPlaced(
+        bytes32 indexed orderId,
+        address indexed sellToken,
+        address indexed buyToken,
+        uint256 sellAmount,
+        uint256 rate,
+        uint256 makerAspId,
+        uint256 requiredFillerAspId,
+        uint256 expiry
+    );
+
+    event SwapOrderFilled(
+        bytes32 indexed orderId,
+        bytes32 indexed fillerNullifier,
+        uint256 takeAmount,
+        uint256 giveAmount,
+        uint256 fillerAspId
+    );
+
+    event SwapOrderClaimed(
+        bytes32 indexed orderId,
+        uint256 accumulatedBuyAmount,
+        uint256 refundedSellAmount
+    );
+
+    event SwapOrderCancelled(
+        bytes32 indexed orderId,
+        uint256 refundedSellAmount
+    );
+
+    // ============ Shield ============
+
+    function shield(
+        address token,
+        uint256 amount,
+        bytes32 commitment,
+        bytes calldata encryptedNote
+    ) external;
+
+    function shieldWithPermit(
+        address token,
+        uint256 amount,
+        bytes32 commitment,
+        bytes calldata encryptedNote,
+        uint256 deadline,
+        uint8 v,
+        bytes32 r,
+        bytes32 s
+    ) external;
+
+    function shieldFor(
+        address depositor,
+        address token,
+        uint256 amount,
+        bytes32 commitment,
+        bytes calldata encryptedNote
+    ) external;
+
+    // ============ Transfer ============
+
+    function transfer(
+        uint256[8] calldata proof,
+        bytes32 nullifier,
+        uint256 stateRoot,
+        uint256 aspRoot,
+        address token,
+        bytes32 outputCommitment1,
+        bytes32 outputCommitment2,
+        bytes calldata encryptedNote1,
+        bytes calldata encryptedNote2
+    ) external;
+
+    // ============ Merge ============
+
+    function merge(
+        uint256[8] calldata proof,
+        bytes32 nullifier1,
+        bytes32 nullifier2,
+        uint256 stateRoot,
+        address token,
+        bytes32 outputCommitment,
+        bytes calldata encryptedNote
+    ) external;
+
+    // ============ Withdraw ============
+
+    function withdraw(
+        uint256[8] calldata proof,
+        bytes32 nullifier,
+        uint256 stateRoot,
+        uint256 aspRoot,
+        uint256 aspId,
+        address token,
+        uint256 amount,
+        address recipient,
+        bool isRagequit
+    ) external;
+
+    // ============ JoinSplit ============
+
+    function joinSplit(
+        uint256[8] calldata proof,
+        bytes32[4] calldata nullifiers,
+        uint256 stateRoot,
+        uint256 aspRoot,
+        uint256 aspId,
+        address token,
+        bytes32 outputCommitment1,
+        bytes32 outputCommitment2,
+        bytes calldata encryptedNote1,
+        bytes calldata encryptedNote2
+    ) external;
+
+    // ============ MergeTransfer ============
+
+    function mergeTransfer2x2(
+        uint256[8] calldata proof,
+        bytes32 nullifier1,
+        bytes32 nullifier2,
+        uint256 stateRoot,
+        address token,
+        bytes32 outputCommitment1,
+        bytes32 outputCommitment2,
+        bytes calldata encryptedNote1,
+        bytes calldata encryptedNote2
+    ) external;
+
+    function mergeTransfer4x2(
+        uint256[8] calldata proof,
+        bytes32[4] calldata nullifiers,
+        uint256 stateRoot,
+        address token,
+        bytes32 outputCommitment1,
+        bytes32 outputCommitment2,
+        bytes calldata encryptedNote1,
+        bytes calldata encryptedNote2
+    ) external;
+
+    // ============ Swap ============
+
+    function swapOrder(
+        uint256[8] calldata proof,
+        bytes32 nullifier,
+        uint256 stateRoot,
+        uint256 aspRoot,
+        uint256 aspId,
+        address sellToken,
+        uint256 sellAmount,
+        address buyToken,
+        uint256 rate,
+        uint256 requiredFillerAspId,
+        bytes32 cancelKeyHash,
+        uint256 expiry
+    ) external;
+
+    function swapFill(
+        bytes32 orderId,
+        uint256[8] calldata proof,
+        bytes32 nullifier,
+        uint256 stateRoot,
+        uint256 aspRoot,
+        uint256 aspId,
+        uint256 takeAmount,
+        bytes32 fillerOutputCommitment,
+        bytes calldata encryptedFillerNote
+    ) external;
+
+    function swapClaim(
+        bytes32 orderId,
+        bytes32 cancelSecret,
+        bytes32 buyOutputCommitment,
+        bytes calldata encryptedBuyNote,
+        bytes32 refundCommitment,
+        bytes calldata encryptedRefundNote
+    ) external;
+
+    function swapCancel(
+        bytes32 orderId,
+        bytes32 cancelSecret,
+        bytes32 refundCommitment,
+        bytes calldata encryptedRefundNote
+    ) external;
+
+    // ============ View Functions ============
+
+    function isKnownRoot(uint256 root) external view returns (bool);
+    function nullifierUsed(bytes32 nullifier) external view returns (bool);
+    function getMerkleRoot() external view returns (uint256);
+    function getMerkleSize() external view returns (uint256);
+}

package/src/contracts/interfaces/IVerifiers.sol

@@ -0,0 +1,68 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.20;
+
+/// @notice Verifier interface for shield proofs
+interface IShieldVerifier {
+    function verifyProof(
+        uint256[8] calldata proof,
+        uint256[4] calldata pubSignals // [commitment, amount, origin, token]
+    ) external view returns (bool);
+}
+
+/// @notice Verifier interface for transfer proofs
+interface ITransferVerifier {
+    function verifyProof(
+        uint256[8] calldata proof,
+        uint256[6] calldata pubSignals // [stateRoot, aspRoot, nullifier, outCommitment1, outCommitment2, token]
+    ) external view returns (bool);
+}
+
+/// @notice Verifier interface for merge proofs (2-in-1-out)
+interface IMergeVerifier {
+    function verifyProof(
+        uint256[8] calldata proof,
+        uint256[6] calldata pubSignals // [stateRoot, nullifier1, nullifier2, outCommitment, merger, token]
+    ) external view returns (bool);
+}
+
+/// @notice Verifier interface for withdrawal proofs
+interface IWithdrawVerifier {
+    function verifyProof(
+        uint256[8] calldata proof,
+        uint256[7] calldata pubSignals // [stateRoot, aspRoot, nullifier, amount, recipient, token, isRagequit]
+    ) external view returns (bool);
+}
+
+/// @notice Verifier interface for JoinSplit proofs (4-in-2-out, same origin)
+interface IJoinSplitVerifier {
+    function verifyProof(
+        uint256[8] calldata proof,
+        uint256[9] calldata pubSignals // [stateRoot, aspRoot, nullifier1-4, outCommitment1-2, token]
+    ) external view returns (bool);
+}
+
+/// @notice Verifier interface for MergeTransfer 2x2 proofs (2-in-2-out, origin changes)
+interface IMergeTransfer2x2Verifier {
+    function verifyProof(
+        uint256[8] calldata proof,
+        uint256[7] calldata pubSignals // [stateRoot, nullifier1-2, outCommitment1-2, merger, token]
+    ) external view returns (bool);
+}
+
+/// @notice Verifier interface for MergeTransfer 4x2 proofs (4-in-2-out, origin changes)
+interface IMergeTransfer4x2Verifier {
+    function verifyProof(
+        uint256[8] calldata proof,
+        uint256[9] calldata pubSignals // [stateRoot, nullifier1-4, outCommitment1-2, merger, token]
+    ) external view returns (bool);
+}
+
+/// @notice Verifier interface for Circle STARK withdrawal proofs (post-quantum)
+interface ICircleStarkWithdrawVerifier {
+    function verify(bytes calldata proof, bytes32 publicInputsSeed) external view returns (bool);
+}
+
+/// @notice Verifier interface for Circle STARK transfer proofs (post-quantum, 1-in-2-out)
+interface ICircleStarkTransferVerifier {
+    function verify(bytes calldata proof, bytes32 publicInputsSeed) external view returns (bool);
+}

package/src/deployments/11155111.json

@@ -0,0 +1,19 @@
+{
+  "UniversalPrivatePool": "0xb111a861cba83b16b9cab613b31b1f0ca03e1996",
+  "ASPRegistryHub": "0xfd11c56a23314aa88dfbcc36254f33e5e8b010df",
+  "TestToken": "0x93d4baee17a99734d88717ead15f98ef803c4e38",
+  "TestToken2": "0xc9169f12033d020a74c89ae8ab25d580846e0910",
+  "verifiers": {
+    "TransferVerifier": "0xa34bde414650a7cd6dbd2d5a08a09df7b4a5951d",
+    "MergeVerifier": "0xd016825bc5aa7dd3b1cad100c1ac291581a1e2c5",
+    "WithdrawVerifier": "0x50c624fc273d8e584e46ba9dce2660f5b8c3d3ac",
+    "JoinSplitVerifier": "0x6799d8a5d4d8cf82a842270916ba71dbf2d1810f",
+    "MergeTransfer2x2Verifier": "0x0cb522e58d10b8c86c10a8cc7f208ed625444579",
+    "MergeTransfer4x2Verifier": "0xc22364ff54c102e54c1f44a43284c932983603b6"
+  },
+  "starkVerifiers": {
+    "CircleStarkVerifier": "0xeb2a0cb5a1c4265dd2acbd46060328b87dc8dcce"
+  },
+  "deployBlock": 10477882,
+  "deployTimestamp": 1773936927201
+}

package/src/deployments/31337.json

@@ -0,0 +1,19 @@
+{
+  "UniversalPrivatePool": "0x2279b7a0a67db372996a5fab50d91eaa73d2ebe6",
+  "ASPRegistryHub": "0xe7f1725e7734ce288f8367e1bb143e90bb3f0512",
+  "TestToken": "0x610178da211fef7d417bc0e6fed39f05609ad788",
+  "TestToken2": "0xb7f8bc63bbcad18155201308c8f3540b07f84f5e",
+  "verifiers": {
+    "TransferVerifier": "0x9fe46736679d2d9a65f0992f2272de9f3c7fa6e0",
+    "MergeVerifier": "0xcf7ed3acca5a467e9e704c703e8d87f634fb0fc9",
+    "WithdrawVerifier": "0xdc64a140aa3e981100a9beca4e685f962f0cf6c9",
+    "JoinSplitVerifier": "0x5fc8d32690cc91d4c39d9d3abcbd16989f875707",
+    "MergeTransfer2x2Verifier": "0x0165878a594ca255338adfa4d48449f69242eb8f",
+    "MergeTransfer4x2Verifier": "0xa513e6e4b8f2a923d98304ec87f64353c4d5c853"
+  },
+  "starkVerifiers": {
+    "CircleStarkVerifier": "0x0dcd1bf9a1b36ce34237eeafef220932846bcd82"
+  },
+  "deployBlock": 1,
+  "deployTimestamp": 1774604726045
+}