ciphera 0.1.0__tar.gz

ciphera-0.1.0/.gitignore

@@ -0,0 +1,170 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/#use-with-ide
+.pdm.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Ruff (linter)
+.ruff_cache/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+.idea/
+!.idea/runConfigurations
+
+# macOS
+.DS_Store
+
+# Received approval test files
+*.received.*
+
+# NPM
+node_modules
+

ciphera-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aditya Pandey
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ciphera-0.1.0/PKG-INFO

@@ -0,0 +1,217 @@
+Metadata-Version: 2.4
+Name: ciphera
+Version: 0.1.0
+Summary: Zero-Knowledge KYC for Algorand — verify KYC status on-chain without exposing personal data
+Project-URL: Homepage, https://github.com/Aditya060806/Ciphera
+Project-URL: Repository, https://github.com/Aditya060806/Ciphera
+Project-URL: Issues, https://github.com/Aditya060806/Ciphera/issues
+Project-URL: Documentation, https://github.com/Aditya060806/Ciphera#readme
+Author-email: Aditya Pandey <adityapandey060806@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2026 Aditya Pandey
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: aadhaar,algorand,blockchain,groth16,kyc,privacy,snarkjs,zero-knowledge,zk-proof
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Security :: Cryptography
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Requires-Dist: py-algorand-sdk>=2.6.0
+Provides-Extra: algorand
+Requires-Dist: py-algorand-sdk>=2.6.0; extra == 'algorand'
+Provides-Extra: dev
+Requires-Dist: build>=1.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: twine>=5.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# ciphera
+
+**Zero-Knowledge KYC for Algorand** — verify KYC status on-chain without exposing personal data.
+
+[![PyPI version](https://img.shields.io/pypi/v/ciphera)](https://pypi.org/project/ciphera)
+[![Python](https://img.shields.io/pypi/pyversions/ciphera)](https://pypi.org/project/ciphera)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Install
+
+```bash
+pip install ciphera
+```
+
+## What is Ciphera?
+
+Ciphera is a privacy-preserving zero-knowledge KYC system on Algorand. Users prove they are KYC-verified Indian adults **without revealing any personal data**. ZK proofs are generated in the browser — private inputs never leave the device.
+
+## Quick Start
+
+### Check KYC Status (any dApp)
+
+```python
+from ciphera import CipheraClient
+
+client = CipheraClient()  # connects to Algorand Testnet by default
+
+# Check total registered credentials on-chain
+status = client.verify_kyc()
+print(status.is_verified)        # True if any credentials registered
+print(status.total_registered)   # e.g. 42
+print(status.app_id)             # 756272073
+```
+
+### Check a Specific Nullifier
+
+```python
+client = CipheraClient()
+
+# Check if a specific nullifier is registered
+is_verified = client.is_nullifier_registered("3b1f8a2c" + "0" * 56)
+print(is_verified)  # True / False
+```
+
+### Verify a ZK Proof (Issuer Backend)
+
+```python
+import json
+from ciphera import verify_proof
+
+vk = json.load(open("verification_key.json"))
+
+result = verify_proof(
+    verification_key=vk,
+    proof=proof_dict,           # from browser SDK
+    public_signals=signals_list,
+    expected_app_id=756272073   # prevents cross-app attacks
+)
+
+if result.valid:
+    print(result.nullifier_hex)    # 32-byte hex to register on-chain
+    print(result.public_signals.is_adult)   # "1"
+else:
+    print(result.error)
+```
+
+### Connect to Different Networks
+
+```python
+from ciphera import CipheraClient
+
+# Testnet (default)
+client = CipheraClient()
+
+# Mainnet
+client = CipheraClient(network="mainnet")
+
+# LocalNet (development)
+client = CipheraClient(network="localnet")
+
+# Custom endpoint
+client = CipheraClient(
+    algod_url="https://my-algod.example.com",
+    algod_token="my-token"
+)
+```
+
+---
+
+## API Reference
+
+### `CipheraClient`
+
+```python
+CipheraClient(
+    network="testnet",   # "testnet" | "mainnet" | "localnet"
+    algod_url=None,      # Override endpoint
+    algod_token="",      # Override token
+    contract_ids=None,   # Override deployed contract IDs (dict)
+)
+```
+
+| Method | Returns | Description |
+|---|---|---|
+| `verify_kyc(wallet_address=None)` | `KYCStatus` | Check on-chain KYC registry |
+| `is_nullifier_registered(hex)` | `bool` | Direct nullifier box check |
+| `get_credential_asa_id()` | `int` | KYCRED ASA ID |
+| `CipheraClient.explorer_tx_url(txid)` | `str` | Allo.info TX URL |
+| `CipheraClient.explorer_app_url(app_id)` | `str` | Allo.info app URL |
+
+### `verify_proof(vk, proof, public_signals, expected_app_id=None)`
+
+Verify a Groth16 ZK proof off-chain.
+
+> **Requires Node.js** (`node` must be in PATH) as it delegates to snarkjs.
+
+Returns `ProofResult` with `.valid`, `.nullifier_hex`, `.public_signals`, `.error`.
+
+---
+
+## Models
+
+```python
+@dataclass
+class KYCStatus:
+    is_verified: bool
+    app_id: int
+    total_registered: Optional[int]
+    nullifier: Optional[str]
+    error: Optional[str]
+
+@dataclass
+class ProofResult:
+    valid: bool
+    nullifier_hex: Optional[str]
+    public_signals: Optional[PublicSignals]
+    error: Optional[str]
+```
+
+---
+
+## Deployed Contracts (Algorand Testnet)
+
+| Contract | App ID |
+|---|---|
+| NullifierRegistry | 756272073 |
+| SMTRegistry | 756272075 |
+| KYCBoxStorage | 756272299 |
+| CredentialManager | 756281076 |
+| KYCRED ASA | 756281102 |
+
+---
+
+## Requirements
+
+- Python 3.9+
+- `py-algorand-sdk` (installed automatically)
+- Node.js (only required for `verify_proof()`)
+
+---
+
+## License
+
+MIT © [Aditya Pandey](https://github.com/Aditya060806)

ciphera-0.1.0/README.md

@@ -0,0 +1,164 @@
+# ciphera
+
+**Zero-Knowledge KYC for Algorand** — verify KYC status on-chain without exposing personal data.
+
+[![PyPI version](https://img.shields.io/pypi/v/ciphera)](https://pypi.org/project/ciphera)
+[![Python](https://img.shields.io/pypi/pyversions/ciphera)](https://pypi.org/project/ciphera)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Install
+
+```bash
+pip install ciphera
+```
+
+## What is Ciphera?
+
+Ciphera is a privacy-preserving zero-knowledge KYC system on Algorand. Users prove they are KYC-verified Indian adults **without revealing any personal data**. ZK proofs are generated in the browser — private inputs never leave the device.
+
+## Quick Start
+
+### Check KYC Status (any dApp)
+
+```python
+from ciphera import CipheraClient
+
+client = CipheraClient()  # connects to Algorand Testnet by default
+
+# Check total registered credentials on-chain
+status = client.verify_kyc()
+print(status.is_verified)        # True if any credentials registered
+print(status.total_registered)   # e.g. 42
+print(status.app_id)             # 756272073
+```
+
+### Check a Specific Nullifier
+
+```python
+client = CipheraClient()
+
+# Check if a specific nullifier is registered
+is_verified = client.is_nullifier_registered("3b1f8a2c" + "0" * 56)
+print(is_verified)  # True / False
+```
+
+### Verify a ZK Proof (Issuer Backend)
+
+```python
+import json
+from ciphera import verify_proof
+
+vk = json.load(open("verification_key.json"))
+
+result = verify_proof(
+    verification_key=vk,
+    proof=proof_dict,           # from browser SDK
+    public_signals=signals_list,
+    expected_app_id=756272073   # prevents cross-app attacks
+)
+
+if result.valid:
+    print(result.nullifier_hex)    # 32-byte hex to register on-chain
+    print(result.public_signals.is_adult)   # "1"
+else:
+    print(result.error)
+```
+
+### Connect to Different Networks
+
+```python
+from ciphera import CipheraClient
+
+# Testnet (default)
+client = CipheraClient()
+
+# Mainnet
+client = CipheraClient(network="mainnet")
+
+# LocalNet (development)
+client = CipheraClient(network="localnet")
+
+# Custom endpoint
+client = CipheraClient(
+    algod_url="https://my-algod.example.com",
+    algod_token="my-token"
+)
+```
+
+---
+
+## API Reference
+
+### `CipheraClient`
+
+```python
+CipheraClient(
+    network="testnet",   # "testnet" | "mainnet" | "localnet"
+    algod_url=None,      # Override endpoint
+    algod_token="",      # Override token
+    contract_ids=None,   # Override deployed contract IDs (dict)
+)
+```
+
+| Method | Returns | Description |
+|---|---|---|
+| `verify_kyc(wallet_address=None)` | `KYCStatus` | Check on-chain KYC registry |
+| `is_nullifier_registered(hex)` | `bool` | Direct nullifier box check |
+| `get_credential_asa_id()` | `int` | KYCRED ASA ID |
+| `CipheraClient.explorer_tx_url(txid)` | `str` | Allo.info TX URL |
+| `CipheraClient.explorer_app_url(app_id)` | `str` | Allo.info app URL |
+
+### `verify_proof(vk, proof, public_signals, expected_app_id=None)`
+
+Verify a Groth16 ZK proof off-chain.
+
+> **Requires Node.js** (`node` must be in PATH) as it delegates to snarkjs.
+
+Returns `ProofResult` with `.valid`, `.nullifier_hex`, `.public_signals`, `.error`.
+
+---
+
+## Models
+
+```python
+@dataclass
+class KYCStatus:
+    is_verified: bool
+    app_id: int
+    total_registered: Optional[int]
+    nullifier: Optional[str]
+    error: Optional[str]
+
+@dataclass
+class ProofResult:
+    valid: bool
+    nullifier_hex: Optional[str]
+    public_signals: Optional[PublicSignals]
+    error: Optional[str]
+```
+
+---
+
+## Deployed Contracts (Algorand Testnet)
+
+| Contract | App ID |
+|---|---|
+| NullifierRegistry | 756272073 |
+| SMTRegistry | 756272075 |
+| KYCBoxStorage | 756272299 |
+| CredentialManager | 756281076 |
+| KYCRED ASA | 756281102 |
+
+---
+
+## Requirements
+
+- Python 3.9+
+- `py-algorand-sdk` (installed automatically)
+- Node.js (only required for `verify_proof()`)
+
+---
+
+## License
+
+MIT © [Aditya Pandey](https://github.com/Aditya060806)

ciphera-0.1.0/ciphera/__init__.py

@@ -0,0 +1,34 @@
+"""
+ciphera — Zero-Knowledge KYC SDK for Algorand (Python)
+
+Install:
+    pip install ciphera
+
+Usage:
+    from ciphera import CipheraClient
+
+    client = CipheraClient()
+    status = client.verify_kyc("WALLET_ADDRESS")
+    print(status.is_verified)
+"""
+
+from .client import CipheraClient
+from .models import KYCStatus, ProofResult, PublicSignals
+from .verifier import verify_proof
+from .exceptions import CipheraError, ProofVerificationError, NetworkError
+
+__version__ = "0.1.0"
+__author__ = "Aditya Pandey"
+__license__ = "MIT"
+
+__all__ = [
+    "CipheraClient",
+    "KYCStatus",
+    "ProofResult",
+    "PublicSignals",
+    "verify_proof",
+    "CipheraError",
+    "ProofVerificationError",
+    "NetworkError",
+    "__version__",
+]

ciphera-0.1.0/ciphera/client.py

@@ -0,0 +1,182 @@
+"""
+client.py — CipheraClient for Python
+
+Connect to Algorand and query the Ciphera KYC contracts.
+
+Usage:
+    from ciphera import CipheraClient
+
+    client = CipheraClient()                     # Testnet (default)
+    client = CipheraClient(network="mainnet")    # Mainnet
+    client = CipheraClient(algod_url="http://localhost:4001", algod_token="aaaa...")  # LocalNet
+
+    # Check KYC status
+    status = client.verify_kyc("WALLET_ADDRESS")
+    print(status.is_verified)
+
+    # Check a specific nullifier
+    registered = client.is_nullifier_registered("deadbeef...")
+"""
+
+from __future__ import annotations
+
+import base64
+from typing import Optional, Dict, Any
+
+try:
+    import algosdk
+    from algosdk.v2client import algod as algod_client
+    _ALGOSDK_AVAILABLE = True
+except ImportError:
+    _ALGOSDK_AVAILABLE = False
+
+from .models import KYCStatus
+from .exceptions import NetworkError, ContractError
+
+
+# ── Default Algorand Testnet endpoints ───────────────────────────────────────
+_TESTNET_ALGOD = "https://testnet-api.algonode.cloud"
+_MAINNET_ALGOD = "https://mainnet-api.algonode.cloud"
+_LOCALNET_ALGOD = "http://localhost:4001"
+_LOCALNET_TOKEN = "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
+
+
+# ── Deployed contract IDs on Algorand Testnet ─────────────────────────────────
+DEFAULT_CONTRACT_IDS = {
+    "nullifier_registry": 756272073,
+    "smt_registry":       756272075,
+    "kyc_box_storage":    756272299,
+    "credential_manager": 756281076,
+    "credential_asa_id":  756281102,
+}
+
+
+class CipheraClient:
+    """
+    Python client for the Ciphera ZK-KYC system on Algorand.
+
+    Args:
+        network:      "testnet" (default) | "mainnet" | "localnet"
+        algod_url:    Custom Algod endpoint URL (overrides network preset)
+        algod_token:  Custom Algod API token (default: empty for AlgoNode)
+        contract_ids: Override deployed contract IDs (dict)
+
+    Example:
+        client = CipheraClient()
+        status = client.verify_kyc("AAAA...")
+        print(status.is_verified)
+    """
+
+    def __init__(
+        self,
+        network: str = "testnet",
+        algod_url: Optional[str] = None,
+        algod_token: str = "",
+        contract_ids: Optional[Dict[str, int]] = None,
+    ) -> None:
+        if not _ALGOSDK_AVAILABLE:
+            raise ImportError(
+                "py-algorand-sdk is required: pip install ciphera[algorand]"
+            )
+
+        # Resolve endpoint
+        if algod_url:
+            url, token = algod_url, algod_token
+        elif network == "mainnet":
+            url, token = _MAINNET_ALGOD, ""
+        elif network == "localnet":
+            url, token = _LOCALNET_ALGOD, _LOCALNET_TOKEN
+        else:  # testnet (default)
+            url, token = _TESTNET_ALGOD, ""
+
+        self._algod = algod_client.AlgodClient(token, url)
+
+        # Merge contract IDs
+        self._contracts = {**DEFAULT_CONTRACT_IDS, **(contract_ids or {})}
+
+    # ── Public Methods ─────────────────────────────────────────────────────
+
+    def verify_kyc(self, wallet_address: Optional[str] = None) -> KYCStatus:
+        """
+        Check KYC status via the on-chain NullifierRegistry.
+
+        Reads the `total_registered` global state variable.
+        A non-zero value means at least one credential has been registered.
+
+        For wallet-specific KYC, use is_nullifier_registered() with
+        the wallet's nullifier hex.
+
+        Args:
+            wallet_address: Not currently used (reserved for future wallet-level checks).
+
+        Returns:
+            KYCStatus with is_verified, total_registered, app_id
+
+        Example:
+            status = client.verify_kyc()
+            print(f"Registry has {status.total_registered} verified users")
+        """
+        app_id = self._contracts["nullifier_registry"]
+        try:
+            app_info = self._algod.application_info(app_id)
+            global_state = app_info.get("params", {}).get("global-state", [])
+
+            total_registered = 0
+            for kv in global_state:
+                key = base64.b64decode(kv["key"]).decode("utf-8", errors="ignore")
+                if key == "total_registered":
+                    total_registered = kv["value"].get("uint", 0)
+
+            return KYCStatus(
+                is_verified=total_registered > 0,
+                app_id=app_id,
+                total_registered=total_registered,
+            )
+        except Exception as e:
+            raise NetworkError(f"Failed to query NullifierRegistry (app {app_id}): {e}") from e
+
+    def is_nullifier_registered(self, nullifier_hex: str) -> bool:
+        """
+        Check if a specific nullifier is registered in box storage.
+
+        More precise than verify_kyc() — directly confirms a specific
+        credential nullifier exists on-chain.
+
+        Args:
+            nullifier_hex: 32-byte nullifier as hex string (64 chars, no 0x prefix)
+
+        Returns:
+            True if the nullifier is registered, False otherwise
+
+        Example:
+            registered = client.is_nullifier_registered("deadbeef" * 8)
+        """
+        app_id = self._contracts["nullifier_registry"]
+        try:
+            # Box name = b"nul_" + 32-byte nullifier
+            prefix = b"nul_"
+            nullifier_bytes = bytes.fromhex(nullifier_hex.lstrip("0x").zfill(64))
+            box_name = base64.b64encode(prefix + nullifier_bytes).decode()
+
+            result = self._algod.application_box_by_name(app_id, box_name)
+            return bool(result.get("value"))
+        except algosdk.error.AlgodHTTPError as e:
+            if "box not found" in str(e).lower() or e.code == 404:
+                return False
+            raise NetworkError(f"Box lookup failed: {e}") from e
+        except Exception as e:
+            return False
+
+    def get_credential_asa_id(self) -> int:
+        """Return the KYCRED ASA (Algorand Standard Asset) ID."""
+        return self._contracts["credential_asa_id"]
+
+    @staticmethod
+    def explorer_tx_url(txid: str) -> str:
+        """Return Allo.info explorer URL for a transaction."""
+        return f"https://allo.info/tx/{txid}"
+
+    @staticmethod
+    def explorer_app_url(app_id: int) -> str:
+        """Return Allo.info explorer URL for an application."""
+        return f"https://allo.info/application/{app_id}"

ciphera-0.1.0/ciphera/exceptions.py

@@ -0,0 +1,23 @@
+"""
+exceptions.py — Ciphera SDK custom exceptions
+"""
+
+
+class CipheraError(Exception):
+    """Base exception for all Ciphera SDK errors."""
+    pass
+
+
+class ProofVerificationError(CipheraError):
+    """Raised when a ZK proof fails verification."""
+    pass
+
+
+class NetworkError(CipheraError):
+    """Raised when Algorand network requests fail."""
+    pass
+
+
+class ContractError(CipheraError):
+    """Raised when smart contract interactions fail."""
+    pass

ciphera-0.1.0/ciphera/models.py

@@ -0,0 +1,56 @@
+"""
+models.py — Ciphera SDK Pydantic models
+"""
+
+from __future__ import annotations
+from dataclasses import dataclass, field
+from typing import Optional, List
+
+
+@dataclass
+class PublicSignals:
+    """Public signals output from the ZK circuit."""
+    nullifier: str          # BN254 field element as decimal string
+    merkle_root: str        # SMT root
+    app_id: str             # Algorand NullifierRegistry app ID
+    is_indian: str          # "1"
+    is_adult: str           # "1"
+    is_kyc_verified: str    # "1"
+
+    @classmethod
+    def from_list(cls, signals: List[str]) -> "PublicSignals":
+        """Parse from snarkjs publicSignals array."""
+        if len(signals) < 6:
+            raise ValueError(f"Expected >= 6 public signals, got {len(signals)}")
+        return cls(
+            nullifier=signals[0],
+            merkle_root=signals[1],
+            app_id=signals[2],
+            is_indian=signals[3],
+            is_adult=signals[4],
+            is_kyc_verified=signals[5],
+        )
+
+    @property
+    def nullifier_hex(self) -> str:
+        """Nullifier as 32-byte hex string (suitable for Algorand box keys)."""
+        return format(int(self.nullifier), '064x')
+
+
+@dataclass
+class ProofResult:
+    """Result of ZK proof verification."""
+    valid: bool
+    nullifier_hex: Optional[str] = None
+    public_signals: Optional[PublicSignals] = None
+    error: Optional[str] = None
+
+
+@dataclass
+class KYCStatus:
+    """KYC verification status for a wallet address."""
+    is_verified: bool
+    app_id: int
+    total_registered: Optional[int] = None
+    nullifier: Optional[str] = None
+    error: Optional[str] = None

ciphera-0.1.0/ciphera/verifier.py

@@ -0,0 +1,128 @@
+"""
+verifier.py — ZK proof verification for the Ciphera Python SDK.
+
+Verifies Groth16 proofs using snarkjs via Node.js subprocess.
+The issuer backend calls verify_proof() before registering
+a nullifier on-chain.
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import shutil
+import tempfile
+from pathlib import Path
+from typing import Union, List, Dict, Any
+
+from .models import ProofResult, PublicSignals
+from .exceptions import ProofVerificationError
+
+
+def verify_proof(
+    verification_key: Union[Dict[str, Any], str, Path],
+    proof: Dict[str, Any],
+    public_signals: List[str],
+    expected_app_id: Optional[Union[int, str]] = None,
+) -> ProofResult:
+    """
+    Verify a Groth16 ZK proof using snarkjs (via Node.js subprocess).
+
+    Args:
+        verification_key: The Groth16 verification key (dict, JSON string, or file path).
+        proof:            The Groth16 proof object from snarkjs.
+        public_signals:   List of public signal strings from the circuit.
+        expected_app_id:  Optional NullifierRegistry app ID to guard cross-app attacks.
+
+    Returns:
+        ProofResult with .valid, .nullifier_hex, .public_signals, .error
+
+    Example:
+        import json
+        vk = json.load(open("verification_key.json"))
+        result = verify_proof(vk, proof_dict, signal_list, expected_app_id=756272073)
+        if result.valid:
+            print(result.nullifier_hex)
+    """
+    # Normalise verification_key to dict
+    if isinstance(verification_key, (str, Path)):
+        p = Path(verification_key)
+        if p.exists():
+            with open(p) as f:
+                vk_dict = json.load(f)
+        else:
+            vk_dict = json.loads(str(verification_key))
+    else:
+        vk_dict = verification_key
+
+    # Validate public signals length
+    if len(public_signals) < 6:
+        return ProofResult(
+            valid=False,
+            error=f"Expected >= 6 public signals, got {len(public_signals)}"
+        )
+
+    # Quick sanity checks before expensive snarkjs call
+    is_indian, is_adult, is_kyc = public_signals[3], public_signals[4], public_signals[5]
+    if is_indian != "1":
+        return ProofResult(valid=False, error="isIndian must be 1")
+    if is_adult != "1":
+        return ProofResult(valid=False, error="isAdult must be 1")
+    if is_kyc != "1":
+        return ProofResult(valid=False, error="isKYCVerified must be 1")
+
+    app_id_signal = public_signals[2]
+    if expected_app_id is not None and app_id_signal != str(expected_app_id):
+        return ProofResult(
+            valid=False,
+            error=f"appId mismatch: expected {expected_app_id}, got {app_id_signal}"
+        )
+
+    # Run snarkjs verification via Node.js
+    if not shutil.which("node"):
+        raise ProofVerificationError(
+            "Node.js is required for ZK proof verification. "
+            "Install from https://nodejs.org"
+        )
+
+    js_script = """
+const snarkjs = require('snarkjs');
+const input = JSON.parse(process.argv[2]);
+snarkjs.groth16.verify(input.vk, input.publicSignals, input.proof)
+  .then(valid => { process.stdout.write(JSON.stringify({valid})); })
+  .catch(e => { process.stdout.write(JSON.stringify({valid: false, error: e.message})); });
+"""
+    payload = json.dumps({
+        "vk": vk_dict,
+        "proof": proof,
+        "publicSignals": public_signals,
+    })
+
+    with tempfile.NamedTemporaryFile(suffix=".js", mode="w", delete=False) as f:
+        f.write(js_script)
+        script_path = f.name
+
+    try:
+        result = subprocess.run(
+            ["node", script_path, payload],
+            capture_output=True, text=True, timeout=60
+        )
+        output = json.loads(result.stdout)
+    except (subprocess.TimeoutExpired, json.JSONDecodeError, FileNotFoundError) as e:
+        return ProofResult(valid=False, error=f"Verification failed: {e}")
+    finally:
+        Path(script_path).unlink(missing_ok=True)
+
+    if not output.get("valid"):
+        return ProofResult(valid=False, error=output.get("error", "Proof is invalid"))
+
+    signals = PublicSignals.from_list(public_signals)
+    return ProofResult(
+        valid=True,
+        nullifier_hex=signals.nullifier_hex,
+        public_signals=signals,
+    )
+
+
+# Optional type hint (Python 3.9 compat)
+from typing import Optional

ciphera-0.1.0/pyproject.toml

@@ -0,0 +1,59 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "ciphera"
+version = "0.1.0"
+description = "Zero-Knowledge KYC for Algorand — verify KYC status on-chain without exposing personal data"
+readme = "README.md"
+license = { file = "LICENSE" }
+authors = [
+    { name = "Aditya Pandey", email = "adityapandey060806@gmail.com" }
+]
+keywords = [
+    "algorand", "zero-knowledge", "zk-proof", "kyc",
+    "aadhaar", "privacy", "blockchain", "snarkjs", "groth16"
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Security :: Cryptography",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+requires-python = ">=3.9"
+dependencies = [
+    "py-algorand-sdk>=2.6.0",
+]
+
+[project.optional-dependencies]
+algorand = ["py-algorand-sdk>=2.6.0"]
+dev = [
+    "pytest>=7.0",
+    "pytest-asyncio>=0.23",
+    "twine>=5.0",
+    "build>=1.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/Aditya060806/Ciphera"
+Repository = "https://github.com/Aditya060806/Ciphera"
+Issues = "https://github.com/Aditya060806/Ciphera/issues"
+Documentation = "https://github.com/Aditya060806/Ciphera#readme"
+
+[tool.hatch.build.targets.wheel]
+packages = ["ciphera"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "ciphera/",
+    "README.md",
+    "LICENSE",
+    "pyproject.toml",
+]