zk-eligibility-sdk 1.0.0-beta.1

package/LICENSE

@@ -0,0 +1,30 @@
+# DUAL LICENSE
+
+ZK Eligibility SDK uses a dual licensing model:
+
+## Apache 2.0 License
+
+The following components are licensed under Apache License 2.0:
+- SDK source code (src/ directory)
+- ZK circuits (circuits/ directory)
+- Circom library (circomlib/ directory)
+- CLI tooling (cli/ directory)
+- Test infrastructure (tests/ directory)
+- Documentation files (README.md, IMPLEMENTATION_GUIDE.md, RULES.md, SECURITY.md)
+
+See LICENSE-APACHE2.0 for the full Apache 2.0 license text.
+
+## MIT License
+
+The following components are licensed under MIT License:
+- Smart contracts (contracts/ directory)
+
+See LICENSE-MIT for the full MIT license text.
+
+## Usage
+
+- If you are using the SDK for ZK eligibility checking, the Apache 2.0 license applies.
+- If you are deploying the smart contracts or integrating with the verifier contracts, the MIT license applies.
+- You may use both licenses depending on which components you are using.
+
+For more details, see the respective LICENSE files.

package/LICENSE-APACHE2.0

@@ -0,0 +1,165 @@
+Apache License
+Version 2.0, January 2004
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+   "License" shall mean the terms and conditions for use, reproduction,
+   and distribution as defined in Sections 1 through 9 of this document.
+
+   "Licensor" shall mean the copyright owner or entity authorized by
+   the copyright owner that is granting the License.
+
+   "Legal Entity" shall mean the union of the acting entity and all
+   other entities that control, are controlled by, or are under common
+   control with that entity. For the purposes of this definition,
+   "control" means (i) the power, direct or indirect, to cause the
+   direction or management of such entity, whether by contract or
+   otherwise, or (ii) ownership of fifty percent (50%) or more of the
+   outstanding shares, or (iii) beneficial ownership of such entity.
+
+   "You" (or "Your") shall mean an individual or Legal Entity exercising
+   permissions granted by this License.
+
+   "Source" form shall mean the preferred form for making modifications,
+   including but not limited to software source code, documentation
+   source, and configuration files.
+
+   "Object" form shall mean any form resulting from mechanical
+   transformation or translation of a Source form, including but
+   not limited to compiled object code, generated documentation,
+   and conversions to other media types.
+
+   "Work" shall mean the work of authorship, whether in Source or Object
+   form, made available under the License, as indicated by a copyright
+   notice that is included in or attached to the work.
+
+   "Derivative Works" shall mean any work, whether in Source or Object
+   form, that is based on (or derived from) the Work and for which the
+   editorial revisions, annotations, elaborations, or other modifications
+   represent, as a whole, an original work of authorship, thus including
+   the Work and any other modifications that You make.
+
+   "Contribution" shall mean any work of authorship, including
+   the original Work and any Derivative Works thereof, submitted to,
+   or received by, Licensor for inclusion in the Work by the copyright owner
+   or by an individual or Legal Entity authorized to submit on behalf of
+   the copyright owner. For the purposes of this definition, "submitted"
+   means any form of electronic, verbal, or written communication sent
+   to the Licensor or its representatives, such as but not limited to
+   communication on electronic mailing lists, source code control systems,
+   and issue tracking systems that are managed by, or on behalf of, the
+   Licensor for the purpose of discussing and improving the Work, but
+   excluding communication that is conspicuously marked or otherwise
+   designated in writing by the copyright owner as "Not a Contribution."
+
+   "Contributor" shall mean Licensor and any Legal Entity on behalf of
+   whom a Contribution has been received by Licensor and subsequently
+   incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of
+   this License, each Contributor hereby grants to You a perpetual,
+   worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+   copyright license to reproduce, prepare Derivative Works of,
+   publicly display, publicly perform, sublicense, and distribute the
+   Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of
+   this License, each Contributor hereby grants to You a perpetual,
+   worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+   (except as stated in this section) patent license to make, have made,
+   use, offer to sell, sell, import, and otherwise transfer the Work,
+   where such license applies only to those patent claims licensable
+   by such Contributor that are necessarily infringed by their
+   Contribution(s) alone or by combination of their Contribution(s)
+   with the Work to which such Contribution(s) was submitted. If You
+   institute patent litigation against any entity (including a
+   cross-claim or counterclaim in a lawsuit) alleging that the Work
+   or a Contribution incorporated within the Work constitutes direct
+   or contributory patent infringement, then any patent licenses
+   granted to You under this License for that Work shall terminate
+   as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the
+   Work or Derivative Works thereof in any medium, with or without
+   modifications, and in Source or Object form, provided that You
+   meet the following conditions:
+
+   (a) You must give any other recipients of the Work or
+       Derivative Works a copy of this License; and
+
+   (b) You must cause any modified files to carry prominent notices
+       stating that You changed the files; and
+
+   (c) You must retain, in the Source form of any Derivative Works
+       that You distribute, all copyright, patent, trademark, and
+       attribution notices from the Source form of the Work,
+       excluding those notices that do not pertain to any part of
+       the Derivative Works; and
+
+   (d) If the Work includes a "NOTICE" text file, then any
+       Derivative Works that You distribute must include a readable
+       copy of the attribution notices contained within such NOTICE file.
+
+5. Submission of Contributions. Unless You explicitly state otherwise,
+   any Contribution intentionally submitted for inclusion in the Work
+   by You to Licensor shall be under the terms and conditions of
+   this License, without any additional terms or conditions.
+   Notwithstanding the above, nothing herein shall supersede or modify
+   the terms of any separate license agreement you may have executed
+   with Licensor regarding such Contribution.
+
+6. Trademarks. This License does not grant permission to use the trade
+   names, trademarks, service marks, or product names of the Licensor,
+   except as required for reasonable and customary use in describing the
+   origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or
+   agreed to in writing, Licensor provides the Work (and each
+   Contributor provides its Contributions) on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+   implied, including, without limitation, any warranties or conditions
+   of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+   PARTICULAR PURPOSE. You are solely responsible for determining the
+   appropriateness of using or redistributing the Work and assume any
+   risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory,
+   whether in tort (including negligence), contract, or otherwise,
+   unless required by applicable law (such as deliberate and grossly
+   negligent acts) or agreed to in writing, shall any Contributor be
+   liable to You for damages, including any direct, indirect, special,
+   incidental, or consequential damages of any character arising as a
+   result of this License or out of the use or inability to use the
+   Work (including but not limited to damages for loss of goodwill,
+   work stoppage, computer failure or malfunction, or any and all
+   other commercial damages or losses), even if such Contributor
+   has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing
+   the Work or Derivative Works thereof, You may choose to offer,
+   and charge a fee for, acceptance of support, warranty, indemnity,
+   or other liability obligations and/or rights consistent with this
+   License. However, in accepting such obligations, You may act only
+   on Your own behalf and on Your sole responsibility, not on behalf
+   of any other Contributor, and only if You agree to indemnify,
+   defend, and hold each Contributor harmless for any liability
+   incurred by, or claims asserted against, such Contributor by reason
+   of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+Copyright © 2024 Srivishnu G V
+
+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.

package/README.md

@@ -0,0 +1,398 @@
+# ZK Eligibility SDK
+
+**Cryptographically Proven Eligibility. Zero Data Leakage.**
+
+A zero-knowledge eligibility framework for Web3. Prove wallet properties—age, activity, holdings, cooldowns—without revealing transaction history, balances, or user identities.
+
+For airdrop designers, DAO treasuries, and DeFi protocols that demand both security and privacy.
+
+---
+
+## The Problem
+
+Today, Web3 teams face an impossible choice:
+
+| Option | Problem |
+|--------|----------|
+| **Public allowlists** | Leaks entire wallet histories. Privacy nightmare. |
+| **Centralized gatekeeping** | Requires trusting a third party. Single point of failure. |
+| **Simple heuristics** | Easy to game. Sybil attacks succeed. |
+| **This SDK** | ✅ Cryptographically proven. ✅ Privacy-preserving. ✅ Sybil-resistant. |
+
+**With ZK Eligibility SDK, you get all three.**
+
+---
+
+## What You Get
+
+✅ **Cryptographic Guarantees**
+- If a proof verifies, the statement is mathematically true
+- Forging eligibility is computationally infeasible under standard cryptographic assumptions 
+- Industry-standard Groth16 zk-SNARK implementation
+
+✅ **Zero Data Leakage**
+- Users prove eligibility without revealing wallet history
+- No transaction hashes exposed
+- No balance information leaked
+- No timing patterns revealed
+
+✅ **Production-Ready**
+- 5 battle-tested eligibility rules
+- CLI + SDK + on-chain verifier ready
+- 11/11 edge cases passing
+- Comprehensive edge-case test coverage
+- Comprehensive security documentation
+
+✅ **Easy Integration**
+- TypeScript SDK (REST-style)
+- Verifiable proofs for on-chain or off-chain use
+- Drop-in replacement for centralized allowlists
+
+---
+
+## 5 Eligibility Rules (Composable)
+
+### 1️⃣ Wallet Age
+**Prove:** First transaction before block N  
+**Use case:** Sybil resistance, legacy user access, loyalty tiers  
+**Privacy:** Exact age hidden, only proves eligibility  
+
+### 2️⃣ Minimum Activity
+**Prove:** At least N outbound transactions  
+**Use case:** Active user filtering, engagement gates, bot detection  
+**Privacy:** Exact count hidden, only proves threshold  
+
+### 3️⃣ Cooldown Period
+**Prove:** Inactive for N+ blocks  
+**Use case:** Rate limiting, anti-spam, sequential access control  
+**Privacy:** Last activity block hidden  
+
+### 4️⃣ Token Hold Duration
+**Prove:** Held token X for N+ blocks  
+**Use case:** Holder privileges, loyalty programs, time-weighted access  
+**Privacy:** Balances and transfer history hidden  
+
+### 5️⃣ Activity Classification
+**Prove:** Wallet falls into activity band (0–3)  
+**Use case:** Fair distribution, tier-based rewards, heuristic filtering  
+**Privacy:** Exact metrics hidden, only rough band revealed  
+
+---
+
+## Real-World Examples
+
+**Airdrop Designer**
+```
+Requirement: "Only wallets active for 6+ months"
+With ZK SDK: Users prove eligibility → receive airdrop
+Result: No data breach. Sybil-resistant. Privacy-preserved.
+```
+
+**DAO Treasury Manager**
+```
+Requirement: "Community governance token for users with 10+ tx"
+With ZK SDK: Prove activity tier → vote with privacy
+Result: Only qualified members participate. No doxxing.
+```
+
+**DeFi Protocol**
+```
+Requirement: "Risk-based access for established users"
+With ZK SDK: Prove wallet age + activity → access premium features
+Result: Fair, sybil-resistant gate. User privacy maintained.
+```
+
+---
+
+## Why This Matters
+
+|  Traditional Approach  |  ZK Eligibility SDK  |
+
+| 📋 Off-chain allowlist | 🔐 Cryptographic proof |
+| 🔓 Public wallet history | 🤖 Minimal Data Disclosure |
+| 🙏 Trust required | ✅ Trust-minimized |
+| ❌ Sybil-vulnerable | ✅ Sybil-resistant |
+| 💸 Manual curation cost | 🤖 Automated verification |
+| 🌍 Privacy nightmare | 🛡️ Privacy-first |
+
+---
+
+## How It Works
+
+
+┌──────────────────────────────┐
+│ User's Wallet (public)       │
+└──────────────┬───────────────┘
+               │
+               v
+┌──────────────────────────────────────┐
+│ Blockchain Data (on-chain, public)   │ ← RPC Provider
+│ fetched via Alchemy/Infura           │
+└──────────────┬───────────────────────┘
+               │ (private processing)
+               v
+┌──────────────────────────────────────┐
+│ TypeScript SDK                       │ ← Validates inputs
+│ (verify constraints, policy)         │   Prevents abuse
+└──────────────┬───────────────────────┘
+               │ (private witness)
+               v
+┌──────────────────────────────────────┐
+│ ZK Circuit (Circom)                  │ ← Groth16 proof
+│ Cryptographic proof generation       │   generation
+└──────────────┬───────────────────────┘
+               │ (public proof)
+               v
+┌──────────────────────────────────────┐
+│ Proof + Public Signals               │ ← Verifiable by anyone
+│ (cryptographically proven)           │   Off-chain or on-chain
+└──────────────────────────────────────┘
+
+
+**Key insight:** Only the proof is shared. Private data never leaves the user's machine.
+
+---
+
+## Security Guarantees
+
+✅ **Cryptographically Sound**
+- Groth16 zk-SNARK (industry standard)
+- Formal constraint verification
+- No silent overflows or edge case failures
+
+✅ **Conservative Design**
+- Fail fast (TypeScript) on invalid parameters
+- Fail loudly (ZK) on false statements
+- Never default to true
+- Explicit assumptions documented
+
+✅ **Fail-Safe Behavior**
+- All failures are deterministic
+- No silent successes
+- Clear error codes and reasons
+- No ambiguous states
+
+⚠️ **Important Notice**
+- All circuits are **deterministic** (same input always produces same output)
+- Circuits are **not audited** — use at your own risk in production environments
+- The SDK minimizes data disclosure to only what is strictly required to verify eligibility
+
+**See [SECURITY.md](./SECURITY.md) for detailed threat model and assumptions.**
+
+---
+
+## Quick Start
+
+### Installation
+```bash
+npm install zk-eligibility-sdk
+```
+
+### Basic Usage
+```typescript
+import "dotenv/config";
+import { ZKEligibilitySDK } from "zk-eligibility-sdk";
+
+// Prove wallet has at least 10 transactions
+const proof = await ZKEligibilitySDK.prove(
+  "MIN_ACTIVITY",
+  "0xWalletAddress",
+  { minTx: 10 }
+);
+
+if (proof.isValid) {
+  console.log("User is eligible ✅");
+  // Grant access / send airdrop / etc
+}
+```
+
+### CLI
+```bash
+# List all rules
+npx zkesdk list-rules
+
+# Generate a proof
+npx zkesdk prove MIN_ACTIVITY 0xWallet '{"minTx":10}'
+
+# Verify a proof
+npx zkesdk verify MIN_ACTIVITY proof.json public.json
+```
+
+### On-Chain Verification
+Proofs can be verified in a Solidity contract:
+```solidity
+groth16Verifier.verifyProof(
+  proof.pi_a,
+  proof.pi_b,
+  proof.pi_c,
+  publicSignals
+);
+ 
+```
+We have also added a helper contract (EligibilityGate.sol) which will guarentee proper verification of calls based on the RuleId's 
+
+RuleID's are the keccak256 hashes of the rule names and are enforced consistently across the SDK,CLI and on-chain contracts
+
+1) keccak256(WALLET_AGE)
+2) keccak256(COOLDOWN)
+3) keccak256(MIN_ACTIVITY)
+4) keccak256(TOKEN_HOLD)
+5) keccak256(ACTIVITY_CLASS)
+
+For Additional Information refer (contracts\README.md)
+---
+
+## Deployment Options
+
+### Option 1: Off-Chain (Fastest)
+- User generates proof locally
+- SDK verifies proof
+- Instant access/allowlisting
+- **Best for:** Airdrops, quick distributions
+
+### Option 2: On-Chain (Most Trustless)
+- User generates proof
+- Smart contract verifies proof
+- Transparent, auditable, trustless
+- **Best for:** DAOs, protocols, public systems
+
+### Option 3: Hybrid (Flexible)
+- Backend verifies proof
+- Backend gates access
+- Best of both worlds
+- **Best for:** Enterprise integrations
+
+---
+
+## What This Does NOT Do
+
+❌ Prove wallet ownership (no sig checks)  
+❌ Prove identity or KYC status  
+❌ Guarantee real-time state under reorgs  
+❌ Prevent smart contract wallets  
+
+**These are features, not bugs.** This SDK does one thing and does it extremely well:
+
+> Prove wallet properties without leaking wallet history.
+
+Everything else is your application's responsibility.
+
+---
+
+## Specs
+
+| Aspect | Spec |
+|--------|------|
+| **Proof System** | Groth16 (BN128 curve) |
+| **Circuit Language** | Circom 2.0.0 |
+| **Verification** | Off-chain + on-chain |
+| **Supported Chains** | Ethereum (extendable) |
+| **Languages** | TypeScript/JavaScript |
+| **Test Coverage** | 11/11 edge cases passing |
+| **Status** | Production-ready (v1.0) |
+
+---
+
+## Governance & Support
+
+**Version Guarantees**
+- v1.x: All cryptographic guarantees locked
+- Breaking changes → v2.0 only
+- Backward-compatible minor versions
+
+**Security Policy**
+- Responsible disclosure for vulnerabilities
+- Private contact for security issues
+- See [SECURITY.md](./SECURITY.md) for details
+
+---
+
+## Required: RPC Provider
+
+This SDK does NOT ship with an RPC key.
+
+You must set one of the following (Infura is not supported in this version as of yet):
+
+- ALCHEMY_API_KEY
+- INFURA_API_KEY
+
+Example:
+
+export ALCHEMY_API_KEY=your_key_here
+
+## FAQ
+
+**Q: Can I fake a proof?**
+A: No. Cryptographically impossible. Groth16 soundness guarantees ensure only valid proofs verify.
+
+**Q: What if the RPC provider lies?**
+A: Proofs reflect the RPC provider's data. Use a trusted provider (Alchemy, Infura, Quicknode, or your own node).
+
+**Q: Can I combine multiple rules?**
+A: Yes. Generate multiple proofs and combine them at the application layer. Each proof is independent and verifiable.
+
+**Q: What about wallet privacy?**
+A: The proof proves eligibility. Transaction history, balances, and transfers are never revealed or computed by the SDK.
+
+**Q: How much gas does on-chain verification cost?**
+A: Typically ~250k-400k gas per verification. depending on the network and the calldata size.
+
+**Q: Can this run on-chain natively?**
+A: Proof generation happens off-chain. Verification happens on-chain. This is by design (privacy + efficiency).
+
+---
+
+## License
+
+This project uses a **dual licensing model**:
+
+### 📄 Apache 2.0 License
+The following components are licensed under **Apache License 2.0**:
+- SDK source code (`src/` directory)
+- ZK circuits (`circuits/` directory)
+- Circom library (`circomlib/` directory)
+- CLI tooling (`cli/` directory)
+- Test infrastructure (`tests/` directory)
+- Documentation (README.md, IMPLEMENTATION_GUIDE.md, RULES.md, SECURITY.md)
+
+**Use case:** Open-source usage, commercial integration, derivative works  
+**Requirement:** Include Apache 2.0 license and provide attribution
+
+### 📝 MIT License
+The following components are licensed under **MIT License**:
+- Smart contracts (`contracts/` directory)
+
+**Use case:** Contract deployment, integration with verifiers, modification and distribution  
+**Requirement:** Include MIT license and provide attribution
+
+### How to Use
+
+- **Using the SDK for eligibility checking?** → Apache 2.0 applies. Include `LICENSE-APACHE2.0`.
+- **Deploying smart contracts?** → MIT applies. Include `LICENSE-MIT`.
+- **Using both?** → Both licenses apply to their respective components.
+
+See [LICENSE](./LICENSE), [LICENSE-APACHE2.0](./LICENSE-APACHE2.0), and [LICENSE-MIT](./LICENSE-MIT) for full license texts.
+
+---
+
+## Next Steps
+
+🚀 **Start now:**
+1. Clone the repo
+2. `npm install`
+3. Run `npm run test:all` (11 edge cases pass)
+4. Integrate the SDK into your app
+
+📖 **Learn more:**
+- [RULES.md](./RULES.md) — Detailed rule specifications
+- [SECURITY.md](./SECURITY.md) — Threat model & guarantees
+- CLI: `npm run cli`
+
+🤝 **Questions?**
+- File an issue 
+- Check docs
+- Security issues → private disclosure
+
+---
+
+**Made with intent. Shipped with integrity.**