Upload folder using huggingface_hub

Dockerfile

@@ -29,6 +29,18 @@ RUN pip install --no-cache-dir \
 COPY requirements.txt .
 RUN pip install --no-cache-dir -r requirements.txt
 
+# ── Layer 3.5: Build VAIKUNTHA Rust Native Extension (Sprint 45) ──────
+# Install Rust toolchain (only needed at build time, not in final image)
+COPY vaikuntha_bn254/ /app/vaikuntha_bn254/
+RUN curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y \
+    && . $HOME/.cargo/env \
+    && cd /app/vaikuntha_bn254 \
+    && maturin build --release \
+    && pip install --no-cache-dir target/wheels/*.whl \
+    && rustup self uninstall -y
+# NOTE: We uninstall the Rust toolchain after building to keep the
+# final image small. The compiled .so remains installed in site-packages.
+
 # ── Layer 4a: Pre-cache Nomic Embedding model ────────────────
 RUN python -c "\
 from sentence_transformers import SentenceTransformer; \

api.py

@@ -73,11 +73,28 @@ groq_client = Groq(api_key=GROQ_API_KEY)
 @asynccontextmanager
 async def lifespan(app: FastAPI):
     logger.info("🚀 Lifespan started (lazy model loading enabled).")
+    try:
+        from verification.groth16_verifier import initialize_verification_engine
+        initialize_verification_engine()
+        logger.info("⚡ VAIKUNTHA verification engine initialized.")
+    except Exception as e:
+        logger.error(f"⚠️ Failed to initialize VAIKUNTHA verification engine: {e}")
     yield
+    # ── Shut down the VAIKUNTHA verification thread pool cleanly (Sprint 45) ──
+    try:
+        from verification.groth16_verifier import _VERIFIER_THREAD_POOL
+        _VERIFIER_THREAD_POOL.shutdown(wait=True)
+        logger.info("🛑 VAIKUNTHA verification thread pool shut down.")
+    except ImportError:
+        pass  # verification module not installed — nothing to shut down
 
 app = FastAPI(lifespan=lifespan)
 app.include_router(whatsapp_router)
 
+# ── PROJECT VAIKUNTHA Phase 4.1 — ZK Verification Endpoint (Sprint 45) ───
+from verification.routes import router as verification_router
+app.include_router(verification_router)
+
 # --- RATE LIMITER CONFIG ---
 limiter = Limiter(key_func=get_remote_address)
 app.state.limiter = limiter

requirements.txt

@@ -46,4 +46,11 @@ numpy>=1.24.0
 openfisca-core>=44.0.0
 
 # --- PDF Processing (Sprint 28) ---
-pymupdf
+pymupdf
+
+# --- ZK-SNARK Verification Engine (Sprint 45 — PROJECT VAIKUNTHA Phase 4.1) ---
+# The vaikuntha_bn254 native extension is installed via:
+#   cd vaikuntha_bn254 && maturin develop --release
+# maturin is a BUILD-TIME dependency, not a runtime one.
+# The compiled .so is dynamically linked at import time.
+maturin>=1.7

tests/test_verification.py

@@ -0,0 +1,246 @@
+"""
+═══════════════════════════════════════════════════════════════════════════════
+GovBridge India — PROJECT VAIKUNTHA Phase 4.1
+Verification Module Test Suite
+═══════════════════════════════════════════════════════════════════════════════
+
+Tests pure deserialization logic and Pydantic validation without requiring
+the Rust native extension. The Rust FFI is mocked in integration tests.
+"""
+
+import pytest
+from unittest.mock import patch, MagicMock
+
+from verification.deserializer import (
+    deserialize_proof,
+    validate_public_input,
+    G1Point,
+    G2Point,
+    DeserializedProof,
+    BN254_P,
+    BN254_R,
+    PROOF_SIZE,
+    COORD_SIZE,
+)
+from verification.groth16_verifier import VerificationResult
+
+
+# ════════════════════════════════════════════════════════════════════════════
+# 1. DESERIALIZER TESTS
+# ════════════════════════════════════════════════════════════════════════════
+
+class TestProofDeserialization:
+    """Test the 256-byte proof payload deserializer."""
+
+    def _make_valid_payload(self) -> bytes:
+        """Create a 256-byte payload with all-zeros (valid field elements)."""
+        # A coordinate of all zeros is technically the additive identity,
+        # but it passes the field membership check (0 < p).
+        return b"\x00" * PROOF_SIZE
+
+    def test_valid_payload_length(self):
+        """256-byte payload should deserialize without error."""
+        payload = self._make_valid_payload()
+        proof = deserialize_proof(payload)
+        assert isinstance(proof, DeserializedProof)
+        assert len(proof.raw_bytes) == PROOF_SIZE
+
+    def test_short_payload_rejected(self):
+        """Payloads shorter than 256 bytes must be rejected."""
+        with pytest.raises(ValueError, match="exactly 256 bytes"):
+            deserialize_proof(b"\x00" * 255)
+
+    def test_long_payload_rejected(self):
+        """Payloads longer than 256 bytes must be rejected."""
+        with pytest.raises(ValueError, match="exactly 256 bytes"):
+            deserialize_proof(b"\x00" * 257)
+
+    def test_empty_payload_rejected(self):
+        """Empty payload must be rejected."""
+        with pytest.raises(ValueError, match="exactly 256 bytes"):
+            deserialize_proof(b"")
+
+    def test_coordinate_extraction_offsets(self):
+        """Verify that coordinates are extracted at the correct byte offsets."""
+        # Build a payload where each 32-byte slot has a unique marker byte
+        payload = bytearray(PROOF_SIZE)
+        for i in range(8):
+            payload[i * 32] = i + 1  # marker in first byte of each slot
+        payload = bytes(payload)
+
+        proof = deserialize_proof(payload)
+
+        # π_A.x starts at offset 0
+        assert proof.pi_a.x[0] == 1
+        # π_A.y starts at offset 32
+        assert proof.pi_a.y[0] == 2
+        # π_B.x.c0 starts at offset 64
+        assert proof.pi_b.x_c0[0] == 3
+        # π_B.x.c1 starts at offset 96
+        assert proof.pi_b.x_c1[0] == 4
+        # π_B.y.c0 starts at offset 128
+        assert proof.pi_b.y_c0[0] == 5
+        # π_B.y.c1 starts at offset 160
+        assert proof.pi_b.y_c1[0] == 6
+        # π_C.x starts at offset 192
+        assert proof.pi_c.x[0] == 7
+        # π_C.y starts at offset 224
+        assert proof.pi_c.y[0] == 8
+
+
+class TestFieldElementValidation:
+    """Test that coordinates >= BN254 base field prime p are rejected."""
+
+    def test_coordinate_at_prime_rejected(self):
+        """A coordinate equal to p must be rejected."""
+        p_bytes = BN254_P.to_bytes(32, byteorder="big")
+        with pytest.raises(ValueError, match="base field prime"):
+            G1Point(x=p_bytes, y=b"\x00" * 32)
+
+    def test_coordinate_above_prime_rejected(self):
+        """A coordinate above p must be rejected."""
+        above_p = (BN254_P + 1).to_bytes(32, byteorder="big")
+        with pytest.raises(ValueError, match="base field prime"):
+            G1Point(x=above_p, y=b"\x00" * 32)
+
+    def test_coordinate_at_max_valid_accepted(self):
+        """A coordinate at p-1 must be accepted."""
+        max_valid = (BN254_P - 1).to_bytes(32, byteorder="big")
+        point = G1Point(x=max_valid, y=b"\x00" * 32)
+        assert point.x == max_valid
+
+    def test_coordinate_zero_accepted(self):
+        """A coordinate of zero must be accepted."""
+        point = G1Point(x=b"\x00" * 32, y=b"\x00" * 32)
+        assert point.x == b"\x00" * 32
+
+
+class TestPublicInputValidation:
+    """Test public input (scalar field element) validation."""
+
+    def test_valid_input_zero(self):
+        """Zero is a valid public input."""
+        validate_public_input(b"\x00" * 32)  # Should not raise
+
+    def test_valid_input_one(self):
+        """One is a valid public input."""
+        one = (1).to_bytes(32, byteorder="big")
+        validate_public_input(one)  # Should not raise
+
+    def test_input_at_order_rejected(self):
+        """A public input equal to r must be rejected."""
+        r_bytes = BN254_R.to_bytes(32, byteorder="big")
+        with pytest.raises(ValueError, match="scalar field order"):
+            validate_public_input(r_bytes)
+
+    def test_input_above_order_rejected(self):
+        """A public input above r must be rejected."""
+        above_r = (BN254_R + 1).to_bytes(32, byteorder="big")
+        with pytest.raises(ValueError, match="scalar field order"):
+            validate_public_input(above_r)
+
+    def test_input_wrong_length_rejected(self):
+        """Public inputs must be exactly 32 bytes."""
+        with pytest.raises(ValueError, match="exactly 32 bytes"):
+            validate_public_input(b"\x00" * 31)
+
+        with pytest.raises(ValueError, match="exactly 32 bytes"):
+            validate_public_input(b"\x00" * 33)
+
+
+# ════════════════════════════════════════════════════════════════════════════
+# 2. VERIFICATION RESULT MODEL TESTS
+# ════════════════════════════════════════════════════════════════════════════
+
+class TestVerificationResult:
+    """Test the VerificationResult Pydantic model."""
+
+    def test_valid_result(self):
+        """A valid verification result should construct properly."""
+        result = VerificationResult(valid=True, verification_time_ms=3.142)
+        assert result.valid is True
+        assert result.verification_time_ms == 3.142
+        assert result.error is None
+
+    def test_invalid_result_with_error(self):
+        """An invalid result with an error message should construct properly."""
+        result = VerificationResult(
+            valid=False,
+            verification_time_ms=0.5,
+            error="π_A: point not on curve"
+        )
+        assert result.valid is False
+        assert "not on curve" in result.error  # type: ignore[operator]
+
+    def test_negative_time_rejected(self):
+        """Negative verification time must be rejected."""
+        with pytest.raises(Exception):
+            VerificationResult(valid=True, verification_time_ms=-1.0)
+
+
+# ════════════════════════════════════════════════════════════════════════════
+# 3. FASTAPI ROUTE TESTS (with mocked Rust extension)
+# ════════════════════════════════════════════════════════════════════════════
+
+class TestVerifyProofEndpoint:
+    """Test the /api/verify-proof endpoint with mocked Rust backend."""
+
+    @pytest.fixture
+    def client(self):
+        """Create a test client with the verification router mounted."""
+        from fastapi import FastAPI
+        from fastapi.testclient import TestClient
+        from verification.routes import router
+
+        test_app = FastAPI()
+        test_app.include_router(router)
+        return TestClient(test_app)
+
+    def _make_valid_request(self) -> dict:
+        """Create a valid verify-proof request body."""
+        return {
+            "proof": "00" * 256,
+            "public_inputs": ["00" * 32],
+        }
+
+    def test_valid_request_format_accepted(self, client):
+        """A well-formed request should not fail at the Pydantic layer."""
+        with patch("verification.groth16_verifier._verify_sync") as mock_verify:
+            mock_verify.return_value = VerificationResult(
+                valid=True, verification_time_ms=3.0
+            )
+            response = client.post("/api/verify-proof", json=self._make_valid_request())
+            assert response.status_code == 200
+            data = response.json()
+            assert data["valid"] is True
+
+    def test_short_proof_rejected(self, client):
+        """A proof shorter than 512 hex chars should be rejected (422)."""
+        body = {"proof": "00" * 255, "public_inputs": ["00" * 32]}
+        response = client.post("/api/verify-proof", json=body)
+        assert response.status_code == 422
+
+    def test_invalid_hex_rejected(self, client):
+        """Non-hex characters in the proof should be rejected."""
+        body = {"proof": "GG" * 256, "public_inputs": ["00" * 32]}
+        response = client.post("/api/verify-proof", json=body)
+        assert response.status_code == 422
+
+    def test_missing_public_inputs_rejected(self, client):
+        """Request without public_inputs should be rejected."""
+        body = {"proof": "00" * 256}
+        response = client.post("/api/verify-proof", json=body)
+        assert response.status_code == 422
+
+    def test_0x_prefix_stripped(self, client):
+        """Proof and inputs with 0x prefix should be accepted."""
+        with patch("verification.groth16_verifier._verify_sync") as mock_verify:
+            mock_verify.return_value = VerificationResult(
+                valid=True, verification_time_ms=2.0
+            )
+            body = {
+                "proof": "0x" + "00" * 256,
+                "public_inputs": ["0x" + "00" * 32],
+            }
+            response = client.post("/api/verify-proof", json=body)
+            assert response.status_code == 200

vaikuntha_bn254/=1.7

@@ -0,0 +1,6 @@
+Collecting maturin
+  Downloading maturin-1.14.1-py3-none-manylinux_2_12_x86_64.manylinux2010_x86_64.musllinux_1_1_x86_64.whl.metadata (16 kB)
+Downloading maturin-1.14.1-py3-none-manylinux_2_12_x86_64.manylinux2010_x86_64.musllinux_1_1_x86_64.whl (10.6 MB)
+   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 10.6/10.6 MB 25.6 MB/s  0:00:00
+Installing collected packages: maturin
+Successfully installed maturin-1.14.1

vaikuntha_bn254/Cargo.lock

@@ -0,0 +1,810 @@
+# This file is automatically @generated by Cargo.
+# It is not intended for manual editing.
+version = 4
+
+[[package]]
+name = "ahash"
+version = "0.8.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5a15f179cd60c4584b8a8c596927aadc462e27f2ca70c04e0071964a73ba7a75"
+dependencies = [
+ "cfg-if",
+ "once_cell",
+ "version_check",
+ "zerocopy",
+]
+
+[[package]]
+name = "allocator-api2"
+version = "0.2.21"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "683d7910e743518b0e34f1186f92494becacb047c7b6bf616c96772180fef923"
+
+[[package]]
+name = "ark-bn254"
+version = "0.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d69eab57e8d2663efa5c63135b2af4f396d66424f88954c21104125ab6b3e6bc"
+dependencies = [
+ "ark-ec",
+ "ark-ff",
+ "ark-std",
+]
+
+[[package]]
+name = "ark-crypto-primitives"
+version = "0.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1e0c292754729c8a190e50414fd1a37093c786c709899f29c9f7daccecfa855e"
+dependencies = [
+ "ahash",
+ "ark-crypto-primitives-macros",
+ "ark-ec",
+ "ark-ff",
+ "ark-relations",
+ "ark-serialize",
+ "ark-snark",
+ "ark-std",
+ "blake2",
+ "derivative",
+ "digest",
+ "fnv",
+ "merlin",
+ "rayon",
+ "sha2",
+]
+
+[[package]]
+name = "ark-crypto-primitives-macros"
+version = "0.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e7e89fe77d1f0f4fe5b96dfc940923d88d17b6a773808124f21e764dfb063c6a"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.118",
+]
+
+[[package]]
+name = "ark-ec"
+version = "0.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "43d68f2d516162846c1238e755a7c4d131b892b70cc70c471a8e3ca3ed818fce"
+dependencies = [
+ "ahash",
+ "ark-ff",
+ "ark-poly",
+ "ark-serialize",
+ "ark-std",
+ "educe",
+ "fnv",
+ "hashbrown",
+ "itertools",
+ "num-bigint",
+ "num-integer",
+ "num-traits",
+ "rayon",
+ "zeroize",
+]
+
+[[package]]
+name = "ark-ff"
+version = "0.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a177aba0ed1e0fbb62aa9f6d0502e9b46dad8c2eab04c14258a1212d2557ea70"
+dependencies = [
+ "ark-ff-asm",
+ "ark-ff-macros",
+ "ark-serialize",
+ "ark-std",
+ "arrayvec",
+ "digest",
+ "educe",
+ "itertools",
+ "num-bigint",
+ "num-traits",
+ "paste",
+ "rayon",
+ "zeroize",
+]
+
+[[package]]
+name = "ark-ff-asm"
+version = "0.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "62945a2f7e6de02a31fe400aa489f0e0f5b2502e69f95f853adb82a96c7a6b60"
+dependencies = [
+ "quote",
+ "syn 2.0.118",
+]
+
+[[package]]
+name = "ark-ff-macros"
+version = "0.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "09be120733ee33f7693ceaa202ca41accd5653b779563608f1234f78ae07c4b3"
+dependencies = [
+ "num-bigint",
+ "num-traits",
+ "proc-macro2",
+ "quote",
+ "syn 2.0.118",
+]
+
+[[package]]
+name = "ark-groth16"
+version = "0.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "88f1d0f3a534bb54188b8dcc104307db6c56cdae574ddc3212aec0625740fc7e"
+dependencies = [
+ "ark-crypto-primitives",
+ "ark-ec",
+ "ark-ff",
+ "ark-poly",
+ "ark-relations",
+ "ark-serialize",
+ "ark-std",
+ "rayon",
+]
+
+[[package]]
+name = "ark-poly"
+version = "0.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "579305839da207f02b89cd1679e50e67b4331e2f9294a57693e5051b7703fe27"
+dependencies = [
+ "ahash",
+ "ark-ff",
+ "ark-serialize",
+ "ark-std",
+ "educe",
+ "fnv",
+ "hashbrown",
+ "rayon",
+]
+
+[[package]]
+name = "ark-relations"
+version = "0.5.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ec46ddc93e7af44bcab5230937635b06fb5744464dd6a7e7b083e80ebd274384"
+dependencies = [
+ "ark-ff",
+ "ark-std",
+ "tracing",
+ "tracing-subscriber",
+]
+
+[[package]]
+name = "ark-serialize"
+version = "0.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3f4d068aaf107ebcd7dfb52bc748f8030e0fc930ac8e360146ca54c1203088f7"
+dependencies = [
+ "ark-serialize-derive",
+ "ark-std",
+ "arrayvec",
+ "digest",
+ "num-bigint",
+ "rayon",
+]
+
+[[package]]
+name = "ark-serialize-derive"
+version = "0.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "213888f660fddcca0d257e88e54ac05bca01885f258ccdf695bafd77031bb69d"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.118",
+]
+
+[[package]]
+name = "ark-snark"
+version = "0.5.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d368e2848c2d4c129ce7679a7d0d2d612b6a274d3ea6a13bad4445d61b381b88"
+dependencies = [
+ "ark-ff",
+ "ark-relations",
+ "ark-serialize",
+ "ark-std",
+]
+
+[[package]]
+name = "ark-std"
+version = "0.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "246a225cc6131e9ee4f24619af0f19d67761fff15d7ccc22e42b80846e69449a"
+dependencies = [
+ "num-traits",
+ "rand",
+ "rayon",
+]
+
+[[package]]
+name = "arrayvec"
+version = "0.7.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f02882884d3e1bc524fb12c79f107f6ad0e1cfd498c536ffb494301740995dfe"
+
+[[package]]
+name = "autocfg"
+version = "1.5.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f2032f911046de80f0a198e0901378627c33f59ea0ac00e363d481118bd70a53"
+
+[[package]]
+name = "blake2"
+version = "0.10.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "46502ad458c9a52b69d4d4d32775c788b7a1b85e8bc9d482d92250fc0e3f8efe"
+dependencies = [
+ "digest",
+]
+
+[[package]]
+name = "block-buffer"
+version = "0.10.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3078c7629b62d3f0439517fa394996acacc5cbc91c5a20d8c658e77abd503a71"
+dependencies = [
+ "generic-array",
+]
+
+[[package]]
+name = "byteorder"
+version = "1.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1fd0f2584146f6f2ef48085050886acf353beff7305ebd1ae69500e27c67f64b"
+
+[[package]]
+name = "cfg-if"
+version = "1.0.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9330f8b2ff13f34540b44e946ef35111825727b38d33286ef986142615121801"
+
+[[package]]
+name = "cpufeatures"
+version = "0.2.17"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "59ed5838eebb26a2bb2e58f6d5b5316989ae9d08bab10e0e6d103e656d1b0280"
+dependencies = [
+ "libc",
+]
+
+[[package]]
+name = "crossbeam-deque"
+version = "0.8.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9dd111b7b7f7d55b72c0a6ae361660ee5853c9af73f70c3c2ef6858b950e2e51"
+dependencies = [
+ "crossbeam-epoch",
+ "crossbeam-utils",
+]
+
+[[package]]
+name = "crossbeam-epoch"
+version = "0.9.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5b82ac4a3c2ca9c3460964f020e1402edd5753411d7737aa39c3714ad1b5420e"
+dependencies = [
+ "crossbeam-utils",
+]
+
+[[package]]
+name = "crossbeam-utils"
+version = "0.8.21"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d0a5c400df2834b80a4c3327b3aad3a4c4cd4de0629063962b03235697506a28"
+
+[[package]]
+name = "crypto-common"
+version = "0.1.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "78c8292055d1c1df0cce5d180393dc8cce0abec0a7102adb6c7b1eef6016d60a"
+dependencies = [
+ "generic-array",
+ "typenum",
+]
+
+[[package]]
+name = "derivative"
+version = "2.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fcc3dd5e9e9c0b295d6e1e4d811fb6f157d5ffd784b8d202fc62eac8035a770b"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 1.0.109",
+]
+
+[[package]]
+name = "digest"
+version = "0.10.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9ed9a281f7bc9b7576e61468ba615a66a5c8cfdff42420a70aa82701a3b1e292"
+dependencies = [
+ "block-buffer",
+ "crypto-common",
+ "subtle",
+]
+
+[[package]]
+name = "educe"
+version = "0.6.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1d7bc049e1bd8cdeb31b68bbd586a9464ecf9f3944af3958a7a9d0f8b9799417"
+dependencies = [
+ "enum-ordinalize",
+ "proc-macro2",
+ "quote",
+ "syn 2.0.118",
+]
+
+[[package]]
+name = "either"
+version = "1.16.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "91622ff5e7162018101f2fea40d6ebf4a78bbe5a49736a2020649edf9693679e"
+
+[[package]]
+name = "enum-ordinalize"
+version = "4.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4a1091a7bb1f8f2c4b28f1fe2cef4980ca2d410a3d727d67ecc3178c9b0800f0"
+dependencies = [
+ "enum-ordinalize-derive",
+]
+
+[[package]]
+name = "enum-ordinalize-derive"
+version = "4.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8ca9601fb2d62598ee17836250842873a413586e5d7ed88b356e38ddbb0ec631"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.118",
+]
+
+[[package]]
+name = "fnv"
+version = "1.0.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3f9eec918d3f24069decb9af1554cad7c880e2da24a9afd88aca000531ab82c1"
+
+[[package]]
+name = "generic-array"
+version = "0.14.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "85649ca51fd72272d7821adaf274ad91c288277713d9c18820d8499a7ff69e9a"
+dependencies = [
+ "typenum",
+ "version_check",
+]
+
+[[package]]
+name = "hashbrown"
+version = "0.15.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9229cfe53dfd69f0609a49f65461bd93001ea1ef889cd5529dd176593f5338a1"
+dependencies = [
+ "allocator-api2",
+]
+
+[[package]]
+name = "heck"
+version = "0.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2304e00983f87ffb38b55b444b5e3b60a884b5d30c0fca7d82fe33449bbe55ea"
+
+[[package]]
+name = "indoc"
+version = "2.0.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "79cf5c93f93228cf8efb3ba362535fb11199ac548a09ce117c9b1adc3030d706"
+dependencies = [
+ "rustversion",
+]
+
+[[package]]
+name = "itertools"
+version = "0.13.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "413ee7dfc52ee1a4949ceeb7dbc8a33f2d6c088194d9f922fb8318faf1f01186"
+dependencies = [
+ "either",
+]
+
+[[package]]
+name = "keccak"
+version = "0.1.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cb26cec98cce3a3d96cbb7bced3c4b16e3d13f27ec56dbd62cbc8f39cfb9d653"
+dependencies = [
+ "cpufeatures",
+]
+
+[[package]]
+name = "libc"
+version = "0.2.186"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "68ab91017fe16c622486840e4c83c9a37afeff978bd239b5293d61ece587de66"
+
+[[package]]
+name = "memoffset"
+version = "0.9.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "488016bfae457b036d996092f6cb448677611ce4449e970ceaf42695203f218a"
+dependencies = [
+ "autocfg",
+]
+
+[[package]]
+name = "merlin"
+version = "3.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "58c38e2799fc0978b65dfff8023ec7843e2330bb462f19198840b34b6582397d"
+dependencies = [
+ "byteorder",
+ "keccak",
+ "rand_core",
+ "zeroize",
+]
+
+[[package]]
+name = "num-bigint"
+version = "0.4.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a5e44f723f1133c9deac646763579fdb3ac745e418f2a7af9cd0c431da1f20b9"
+dependencies = [
+ "num-integer",
+ "num-traits",
+]
+
+[[package]]
+name = "num-integer"
+version = "0.1.46"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7969661fd2958a5cb096e56c8e1ad0444ac2bbcd0061bd28660485a44879858f"
+dependencies = [
+ "num-traits",
+]
+
+[[package]]
+name = "num-traits"
+version = "0.2.19"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "071dfc062690e90b734c0b2273ce72ad0ffa95f0c74596bc250dcfd960262841"
+dependencies = [
+ "autocfg",
+]
+
+[[package]]
+name = "once_cell"
+version = "1.21.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50"
+
+[[package]]
+name = "paste"
+version = "1.0.15"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "57c0d7b74b563b49d38dae00a0c37d4d6de9b432382b2892f0574ddcae73fd0a"
+
+[[package]]
+name = "pin-project-lite"
+version = "0.2.17"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a89322df9ebe1c1578d689c92318e070967d1042b512afbe49518723f4e6d5cd"
+
+[[package]]
+name = "portable-atomic"
+version = "1.13.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c33a9471896f1c69cecef8d20cbe2f7accd12527ce60845ff44c153bb2a21b49"
+
+[[package]]
+name = "ppv-lite86"
+version = "0.2.21"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "85eae3c4ed2f50dcfe72643da4befc30deadb458a9b590d720cde2f2b1e97da9"
+dependencies = [
+ "zerocopy",
+]
+
+[[package]]
+name = "proc-macro2"
+version = "1.0.106"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8fd00f0bb2e90d81d1044c2b32617f68fcb9fa3bb7640c23e9c748e53fb30934"
+dependencies = [
+ "unicode-ident",
+]
+
+[[package]]
+name = "pyo3"
+version = "0.22.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f402062616ab18202ae8319da13fa4279883a2b8a9d9f83f20dbade813ce1884"
+dependencies = [
+ "cfg-if",
+ "indoc",
+ "libc",
+ "memoffset",
+ "once_cell",
+ "portable-atomic",
+ "pyo3-build-config",
+ "pyo3-ffi",
+ "pyo3-macros",
+ "unindent",
+]
+
+[[package]]
+name = "pyo3-build-config"
+version = "0.22.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b14b5775b5ff446dd1056212d778012cbe8a0fbffd368029fd9e25b514479c38"
+dependencies = [
+ "once_cell",
+ "target-lexicon",
+]
+
+[[package]]
+name = "pyo3-ffi"
+version = "0.22.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9ab5bcf04a2cdcbb50c7d6105de943f543f9ed92af55818fd17b660390fc8636"
+dependencies = [
+ "libc",
+ "pyo3-build-config",
+]
+
+[[package]]
+name = "pyo3-macros"
+version = "0.22.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0fd24d897903a9e6d80b968368a34e1525aeb719d568dba8b3d4bfa5dc67d453"
+dependencies = [
+ "proc-macro2",
+ "pyo3-macros-backend",
+ "quote",
+ "syn 2.0.118",
+]
+
+[[package]]
+name = "pyo3-macros-backend"
+version = "0.22.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "36c011a03ba1e50152b4b394b479826cad97e7a21eb52df179cd91ac411cbfbe"
+dependencies = [
+ "heck",
+ "proc-macro2",
+ "pyo3-build-config",
+ "quote",
+ "syn 2.0.118",
+]
+
+[[package]]
+name = "quote"
+version = "1.0.46"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "dfbc457d0c7a0759a614551b11a6409e5951f6c7537be1f1b7682b9ae9230368"
+dependencies = [
+ "proc-macro2",
+]
+
+[[package]]
+name = "rand"
+version = "0.8.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5ca0ecfa931c29007047d1bc58e623ab12e5590e8c7cc53200d5202b69266d8a"
+dependencies = [
+ "rand_chacha",
+ "rand_core",
+]
+
+[[package]]
+name = "rand_chacha"
+version = "0.3.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e6c10a63a0fa32252be49d21e7709d4d4baf8d231c2dbce1eaa8141b9b127d88"
+dependencies = [
+ "ppv-lite86",
+ "rand_core",
+]
+
+[[package]]
+name = "rand_core"
+version = "0.6.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ec0be4795e2f6a28069bec0b5ff3e2ac9bafc99e6a9a7dc3547996c5c816922c"
+
+[[package]]
+name = "rayon"
+version = "1.12.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fb39b166781f92d482534ef4b4b1b2568f42613b53e5b6c160e24cfbfa30926d"
+dependencies = [
+ "either",
+ "rayon-core",
+]
+
+[[package]]
+name = "rayon-core"
+version = "1.13.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "22e18b0f0062d30d4230b2e85ff77fdfe4326feb054b9783a3460d8435c8ab91"
+dependencies = [
+ "crossbeam-deque",
+ "crossbeam-utils",
+]
+
+[[package]]
+name = "rustversion"
+version = "1.0.22"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b39cdef0fa800fc44525c84ccb54a029961a8215f9619753635a9c0d2538d46d"
+
+[[package]]
+name = "sha2"
+version = "0.10.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a7507d819769d01a365ab707794a4084392c824f54a7a6a7862f8c3d0892b283"
+dependencies = [
+ "cfg-if",
+ "cpufeatures",
+ "digest",
+]
+
+[[package]]
+name = "subtle"
+version = "2.6.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "13c2bddecc57b384dee18652358fb23172facb8a2c51ccc10d74c157bdea3292"
+
+[[package]]
+name = "syn"
+version = "1.0.109"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "72b64191b275b66ffe2469e8af2c1cfe3bafa67b529ead792a6d0160888b4237"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-ident",
+]
+
+[[package]]
+name = "syn"
+version = "2.0.118"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1b9ae57f904213ebb649ce6895b8a66c66f0203b9319718f69a5612a065b1422"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-ident",
+]
+
+[[package]]
+name = "target-lexicon"
+version = "0.12.16"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "61c41af27dd6d1e27b1b16b489db798443478cef1f06a660c96db617ba5de3b1"
+
+[[package]]
+name = "tracing"
+version = "0.1.44"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "63e71662fa4b2a2c3a26f570f037eb95bb1f85397f3cd8076caed2f026a6d100"
+dependencies = [
+ "pin-project-lite",
+ "tracing-core",
+]
+
+[[package]]
+name = "tracing-core"
+version = "0.1.36"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "db97caf9d906fbde555dd62fa95ddba9eecfd14cb388e4f491a66d74cd5fb79a"
+dependencies = [
+ "once_cell",
+ "valuable",
+]
+
+[[package]]
+name = "tracing-subscriber"
+version = "0.2.25"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0e0d2eaa99c3c2e41547cfa109e910a68ea03823cccad4a0525dcbc9b01e8c71"
+dependencies = [
+ "tracing-core",
+]
+
+[[package]]
+name = "typenum"
+version = "1.20.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b6f5e870be6c3b371b77fe0ee0bafb859fa4964b4404c27de1d380043c4dda20"
+
+[[package]]
+name = "unicode-ident"
+version = "1.0.24"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e6e4313cd5fcd3dad5cafa179702e2b244f760991f45397d14d4ebf38247da75"
+
+[[package]]
+name = "unindent"
+version = "0.2.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7264e107f553ccae879d21fbea1d6724ac785e8c3bfc762137959b5802826ef3"
+
+[[package]]
+name = "vaikuntha_bn254"
+version = "0.1.0"
+dependencies = [
+ "ark-bn254",
+ "ark-ec",
+ "ark-ff",
+ "ark-groth16",
+ "ark-relations",
+ "ark-serialize",
+ "ark-snark",
+ "ark-std",
+ "num-bigint",
+ "once_cell",
+ "pyo3",
+]
+
+[[package]]
+name = "valuable"
+version = "0.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ba73ea9cf16a25df0c8caa16c51acb937d5712a8429db78a3ee29d5dcacd3a65"
+
+[[package]]
+name = "version_check"
+version = "0.9.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0b928f33d975fc6ad9f86c8f283853ad26bdd5b10b7f1542aa2fa15e2289105a"
+
+[[package]]
+name = "zerocopy"
+version = "0.8.52"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ce1022995ff5ff5d841ad7d994facc23098cd40152f2c1d11cd607c6f530653f"
+dependencies = [
+ "zerocopy-derive",
+]
+
+[[package]]
+name = "zerocopy-derive"
+version = "0.8.52"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1ae7f38b72ec2a254e2b87ef277cf2cd4fb97cbebf944faa6f33354da0867930"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.118",
+]
+
+[[package]]
+name = "zeroize"
+version = "1.9.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e13c156562582aa81c60cb29407084cdb54c4164760106ab78e6c5b0858cf64e"
+dependencies = [
+ "zeroize_derive",
+]
+
+[[package]]
+name = "zeroize_derive"
+version = "1.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3c50655cbb0fe3fc43170059e702f1ce5e19b84cec58dc87b037a09935c2f328"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.118",
+]

vaikuntha_bn254/Cargo.toml

@@ -0,0 +1,28 @@
+[package]
+name = "vaikuntha_bn254"
+version = "0.1.0"
+edition = "2021"
+description = "GovBridge VAIKUNTHA — BN254 Groth16 verifier (PyO3 native extension)"
+
+[lib]
+name = "vaikuntha_bn254"
+crate-type = ["cdylib"]
+
+[dependencies]
+pyo3 = { version = "0.22", features = ["extension-module"] }
+ark-bn254 = "0.5"
+ark-ec = "0.5"
+ark-ff = "0.5"
+ark-groth16 = "0.5"
+ark-serialize = "0.5"
+ark-std = "0.5"
+ark-relations = "0.5"
+ark-snark = "0.5"
+num-bigint = "0.4"
+once_cell = "1.19"
+
+[profile.release]
+opt-level = 3
+lto = "fat"
+codegen-units = 1
+strip = true

vaikuntha_bn254/pyproject.toml

@@ -0,0 +1,11 @@
+[build-system]
+requires = ["maturin>=1.7,<2.0"]
+build-backend = "maturin"
+
+[project]
+name = "vaikuntha_bn254"
+version = "0.1.0"
+requires-python = ">=3.10"
+
+[tool.maturin]
+features = ["pyo3/extension-module"]

vaikuntha_bn254/src/lib.rs

@@ -0,0 +1,382 @@
+//! ═══════════════════════════════════════════════════════════════════════════
+//! GovBridge India — PROJECT VAIKUNTHA Phase 4.1
+//! BN254 Groth16 Verification Engine (Rust/PyO3 Native Extension)
+//! ═══════════════════════════════════════════════════════════════════════════
+//!
+//! This module exposes two functions to Python:
+//!
+//!   1. `validate_point_g1(x: bytes, y: bytes) -> bool`
+//!      Deserializes x, y as Fq elements, checks the affine point is on the
+//!      BN254 G₁ curve (Y² = X³ + 3) AND in the prime-order r subgroup.
+//!
+//!   2. `verify_groth16(proof_bytes: bytes, public_inputs: list[bytes],
+//!                       vkey_bytes: bytes) -> bool`
+//!      Full Groth16 verification: deserializes the proof, accumulates the
+//!      public-input linear combination, evaluates the pairing equation.
+//!      The GIL is RELEASED for the entire pairing computation.
+//!
+//! ARCHITECTURAL LAWS:
+//!   - py.allow_threads() wraps ALL arithmetic heavier than O(1).
+//!   - All coordinate inputs are BIG-ENDIAN 32-byte field elements.
+//!   - Subgroup checks use scalar multiplication by r (not cofactor tricks).
+//!   - Invalid points produce Python ValueError, never panic.
+//! ═══════════════════════════════════════════════════════════════════════════
+
+use pyo3::prelude::*;
+use pyo3::exceptions::PyValueError;
+use pyo3::types::PyBytes;
+
+use ark_bn254::{Bn254, Fq, Fq2, Fr, G1Affine, G2Affine, G1Projective};
+use ark_ec::{AffineRepr, CurveGroup, Group};
+use ark_ff::{BigInteger256, PrimeField, BigInteger};
+use ark_groth16::{Groth16, Proof, VerifyingKey, PreparedVerifyingKey};
+use ark_snark::SNARK;
+use ark_std::Zero;
+use num_bigint::BigUint;
+use std::sync::RwLock;
+
+// Global lock for the PreparedVerifyingKey to prevent cyclotomic CPU burn on every request.
+static GLOBAL_PVK: RwLock<Option<PreparedVerifyingKey<Bn254>>> = RwLock::new(None);
+
+// ═══════════════════════════════════════════════════════════════════════════
+// SECTION 1: Field Element Deserialization (Big-Endian → ark-ff)
+// ═══════════════════════════════════════════════════════════════════════════
+
+/// Converts a 32-byte big-endian slice to an ark-ff Fq element.
+/// Returns Err if the value >= p (the BN254 base field prime).
+fn bytes_to_fq(data: &[u8]) -> Result<Fq, String> {
+    if data.len() != 32 {
+        return Err(format!("Fq: expected 32 bytes, got {}", data.len()));
+    }
+    // ark-ff BigInteger256 expects little-endian u64 limbs
+    let val = BigUint::from_bytes_be(data);
+    let limbs = val.to_u64_digits();
+    let mut arr = [0u64; 4];
+    for (i, &limb) in limbs.iter().enumerate().take(4) {
+        arr[i] = limb;
+    }
+    let big = BigInteger256::new(arr);
+    Fq::from_bigint(big).ok_or_else(|| "Fq: value >= field modulus p".to_string())
+}
+
+/// Converts a 32-byte big-endian slice to an ark-ff Fr element (scalar field).
+fn bytes_to_fr(data: &[u8]) -> Result<Fr, String> {
+    if data.len() != 32 {
+        return Err(format!("Fr: expected 32 bytes, got {}", data.len()));
+    }
+    let val = BigUint::from_bytes_be(data);
+    let limbs = val.to_u64_digits();
+    let mut arr = [0u64; 4];
+    for (i, &limb) in limbs.iter().enumerate().take(4) {
+        arr[i] = limb;
+    }
+    let big = BigInteger256::new(arr);
+    Fr::from_bigint(big).ok_or_else(|| "Fr: value >= scalar field order r".to_string())
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// SECTION 2: Point Deserialization with Subgroup Checks
+// ═══════════════════════════════════════════════════════════════════════════
+
+/// Deserializes a G₁ affine point from two 32-byte big-endian coordinates.
+/// Performs:
+///   1. Field membership check (x, y < p)
+///   2. Curve equation check: y² ≡ x³ + 3 (mod p)
+///   3. Subgroup check: [r]P == O (point at infinity)
+///
+/// The subgroup check prevents twisted-curve / small-subgroup attacks where
+/// an attacker provides a point on a curve with the same equation but wrong
+/// embedding degree, or a point in a low-order subgroup of the trace-zero
+/// subgroup.
+fn deserialize_g1(x_bytes: &[u8], y_bytes: &[u8]) -> Result<G1Affine, String> {
+    let x = bytes_to_fq(x_bytes)?;
+    let y = bytes_to_fq(y_bytes)?;
+
+    // Construct the affine point — ark-ec checks y² = x³ + b automatically
+    let point = G1Affine::new_unchecked(x, y);
+
+    // Explicit curve equation check
+    if !point.is_on_curve() {
+        return Err("G1: point not on curve (y² ≠ x³ + 3 mod p)".to_string());
+    }
+
+    // Subgroup check: [r]P must be the identity
+    if !point.is_in_correct_subgroup_assuming_on_curve() {
+        return Err("G1: point not in prime-order subgroup ([r]P ≠ O)".to_string());
+    }
+
+    Ok(point)
+}
+
+/// Deserializes a G₂ affine point from four 32-byte big-endian coordinates.
+/// G₂ lives over Fq2 = Fq[u] / (u² + 1).
+///
+/// Wire format from ZkProofExporter (see gov_frontend/src/lib/ZkProofExporter.ts):
+///   pi_B.x = (c0, c1) where Fq2 element = c0 + c1·u
+///   pi_B.y = (c0, c1) where Fq2 element = c0 + c1·u
+///
+/// CRITICAL: The ZkProofExporter stores G2 x-coordinate as [x.c0, x.c1] at
+/// byte offsets [64..95, 96..127] and y-coordinate as [y.c0, y.c1] at
+/// [128..159, 160..191]. This is the RAW layout — NOT the snarkjs-swizzled
+/// [c1, c0] order used in toGroth16Json(). We read the raw 256-byte buffer.
+fn deserialize_g2(
+    x_c0_bytes: &[u8],
+    x_c1_bytes: &[u8],
+    y_c0_bytes: &[u8],
+    y_c1_bytes: &[u8],
+) -> Result<G2Affine, String> {
+    let x_c0 = bytes_to_fq(x_c0_bytes)?;
+    let x_c1 = bytes_to_fq(x_c1_bytes)?;
+    let y_c0 = bytes_to_fq(y_c0_bytes)?;
+    let y_c1 = bytes_to_fq(y_c1_bytes)?;
+
+    let x = Fq2::new(x_c0, x_c1);
+    let y = Fq2::new(y_c0, y_c1);
+
+    let point = G2Affine::new_unchecked(x, y);
+
+    if !point.is_on_curve() {
+        return Err("G2: point not on twisted curve".to_string());
+    }
+
+    if !point.is_in_correct_subgroup_assuming_on_curve() {
+        return Err("G2: point not in prime-order subgroup ([r]P ≠ O)".to_string());
+    }
+
+    Ok(point)
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// SECTION 3: Groth16 Verification Core
+// ═══════════════════════════════════════════════════════════════════════════
+
+/// Deserializes the verification key from a packed binary format.
+///
+/// VKey binary layout (big-endian, each coordinate = 32 bytes):
+///   [  0.. 63]  alpha_g1      (G1: x, y)
+///   [ 64..191]  beta_g2       (G2: x.c0, x.c1, y.c0, y.c1)
+///   [192..319]  gamma_g2      (G2: x.c0, x.c1, y.c0, y.c1)
+///   [320..447]  delta_g2      (G2: x.c0, x.c1, y.c0, y.c1)
+///   [448..]     IC points     (G1: x, y) × (num_public_inputs + 1)
+fn deserialize_vkey(data: &[u8], num_public_inputs: usize) -> Result<VerifyingKey<Bn254>, String> {
+    let expected_len = 448 + (num_public_inputs + 1) * 64;
+    if data.len() < expected_len {
+        return Err(format!(
+            "VKey: expected >= {} bytes for {} public inputs, got {}",
+            expected_len, num_public_inputs, data.len()
+        ));
+    }
+
+    let alpha_g1 = deserialize_g1(&data[0..32], &data[32..64])?;
+    let beta_g2 = deserialize_g2(
+        &data[64..96], &data[96..128], &data[128..160], &data[160..192],
+    )?;
+    let gamma_g2 = deserialize_g2(
+        &data[192..224], &data[224..256], &data[256..288], &data[288..320],
+    )?;
+    let delta_g2 = deserialize_g2(
+        &data[320..352], &data[352..384], &data[384..416], &data[416..448],
+    )?;
+
+    let mut gamma_abc_g1 = Vec::with_capacity(num_public_inputs + 1);
+    for i in 0..=num_public_inputs {
+        let offset = 448 + i * 64;
+        let ic_point = deserialize_g1(&data[offset..offset + 32], &data[offset + 32..offset + 64])?;
+        gamma_abc_g1.push(ic_point);
+    }
+
+    Ok(VerifyingKey {
+        alpha_g1,
+        beta_g2,
+        gamma_g2,
+        delta_g2,
+        gamma_abc_g1,
+    })
+}
+
+/// Core Groth16 verification with unrolled pairing.
+///
+/// Computes:
+///   L = IC[0] + Σ (public_inputs[i] × IC[i+1])
+///
+/// Then checks the pairing equation:
+///   e(π_A, π_B) == e(α, β) · e(L, γ) · e(π_C, δ)
+///
+/// Which is equivalent to checking:
+///   e(π_A, π_B) · e(-L, γ) · e(-π_C, δ) == e(α, β)
+fn verify_proof_inner(
+    proof: &Proof<Bn254>,
+    pvk: &PreparedVerifyingKey<Bn254>,
+    public_inputs: &[Fr],
+) -> Result<bool, String> {
+    if public_inputs.len() + 1 != pvk.vk.gamma_abc_g1.len() {
+        return Err("Mismatched number of public inputs".to_string());
+    }
+
+    // 1. Accumulate public signals using strict w=5 MSM
+    let msm_result = strict_w5_msm(&pvk.vk.gamma_abc_g1[1..], public_inputs);
+
+    // 2. Add to IC_0 (base point)
+    let g_ic = pvk.vk.gamma_abc_g1[0].into_group() + msm_result;
+
+    // 3. Evaluate multi-pairing
+    use ark_ec::pairing::Pairing;
+    let a1: <Bn254 as Pairing>::G1Prepared = proof.a.into();
+    let b1: <Bn254 as Pairing>::G2Prepared = proof.b.into();
+    let a2: <Bn254 as Pairing>::G1Prepared = (-g_ic.into_affine()).into();
+    let b2 = pvk.gamma_g2_neg_pc.clone();
+    let a3: <Bn254 as Pairing>::G1Prepared = (-proof.c).into();
+    let b3 = pvk.delta_g2_neg_pc.clone();
+
+    let pairing = Bn254::multi_pairing([a1, a2, a3], [b1, b2, b3]);
+
+    Ok(pairing.0 == pvk.alpha_g1_beta_g2)
+}
+
+/// Manually unrolls a w=5 windowed Pippenger MSM to protect the L1 cache.
+/// Each 254-bit scalar is divided into 5-bit windows, accumulating into 31 buckets.
+fn strict_w5_msm(bases: &[G1Affine], scalars: &[Fr]) -> G1Projective {
+    const W: usize = 5;
+    const NUM_BUCKETS: usize = (1 << W) - 1;
+    let mut res = G1Projective::zero();
+    
+    let num_bits = Fr::MODULUS_BIT_SIZE as usize; // 254
+    let num_windows = (num_bits + W - 1) / W; 
+    
+    for window in (0..num_windows).rev() {
+        if window != num_windows - 1 {
+            for _ in 0..W {
+                res.double_in_place();
+            }
+        }
+        
+        let mut buckets = vec![G1Projective::zero(); NUM_BUCKETS];
+        
+        for (base, scalar) in bases.iter().zip(scalars.iter()) {
+            let bigint = scalar.into_bigint();
+            let mut window_val = 0usize;
+            for b in 0..W {
+                let bit_idx = window * W + b;
+                if bit_idx < num_bits {
+                    if bigint.get_bit(bit_idx) {
+                        window_val |= 1 << b;
+                    }
+                }
+            }
+            if window_val > 0 {
+                buckets[window_val - 1] += base;
+            }
+        }
+        
+        let mut running_sum = G1Projective::zero();
+        for bucket in buckets.iter().rev() {
+            running_sum += bucket;
+            res += running_sum;
+        }
+    }
+    res
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// SECTION 4: PyO3 Python Bindings
+// ═══════════════════════════════════════════════════════════════════════════
+
+/// Validates that a G1 point (given as two 32-byte big-endian coordinates)
+/// is on the BN254 curve and in the correct prime-order subgroup.
+///
+/// Returns True if valid, raises ValueError if invalid.
+#[pyfunction]
+fn validate_point_g1(py: Python<'_>, x: &Bound<'_, PyBytes>, y: &Bound<'_, PyBytes>) -> PyResult<bool> {
+    let x_data = x.as_bytes();
+    let y_data = y.as_bytes();
+
+    py.allow_threads(|| {
+        deserialize_g1(x_data, y_data)
+            .map(|_| true)
+            .map_err(|e| PyValueError::new_err(e))
+    })
+}
+
+/// Initializes the global verification key in host RAM.
+/// Deserializes the bytes and prepares the PVK, locking it in `GLOBAL_PVK`.
+/// This prevents cyclotomic Fp12 operations from burning the CPU per-request.
+#[pyfunction]
+fn initialize_vkey(py: Python<'_>, vkey_bytes: &Bound<'_, PyBytes>, num_public_inputs: usize) -> PyResult<()> {
+    let vkey_data = vkey_bytes.as_bytes().to_vec();
+    py.allow_threads(move || {
+        let vk = deserialize_vkey(&vkey_data, num_public_inputs)
+            .map_err(|e| PyValueError::new_err(format!("VKey: {}", e)))?;
+        let pvk = Groth16::<Bn254>::process_vk(&vk)
+            .map_err(|e| PyValueError::new_err(format!("VKey processing: {}", e)))?;
+        
+        let mut lock = GLOBAL_PVK.write().unwrap();
+        *lock = Some(pvk);
+        Ok(())
+    })
+}
+
+/// Full Groth16 proof verification using the globally locked PVK.
+///
+/// Arguments:
+///   proof_bytes: 256 bytes — the raw proof (π_A, π_B, π_C) in big-endian.
+///   public_inputs: List of 32-byte big-endian scalar field elements.
+///
+/// Returns True if the proof is valid, False if the pairing check fails.
+/// Raises ValueError for deserialization or structural errors.
+///
+/// THE GIL IS RELEASED for the entire function body via py.allow_threads().
+#[pyfunction]
+fn verify_groth16(
+    py: Python<'_>,
+    proof_bytes: &Bound<'_, PyBytes>,
+    public_inputs: Vec<Bound<'_, PyBytes>>,
+) -> PyResult<bool> {
+    let proof_data = proof_bytes.as_bytes().to_vec();
+    let inputs_data: Vec<Vec<u8>> = public_inputs
+        .iter()
+        .map(|b| b.as_bytes().to_vec())
+        .collect();
+
+    py.allow_threads(move || {
+        // ── Acquire global PVK read lock ───────────────────────────────
+        let lock = GLOBAL_PVK.read().unwrap();
+        let pvk = lock.as_ref().ok_or_else(|| PyValueError::new_err("Verification engine not initialized with vkey"))?;
+
+        // ���─ Step 1: Deserialize proof (256 bytes) ──────────────────────
+        if proof_data.len() != 256 {
+            return Err(PyValueError::new_err(format!("Proof must be exactly 256 bytes")));
+        }
+
+        let pi_a = deserialize_g1(&proof_data[0..32], &proof_data[32..64])
+            .map_err(|e| PyValueError::new_err(format!("π_A: {}", e)))?;
+        let pi_b = deserialize_g2(
+            &proof_data[64..96], &proof_data[96..128],
+            &proof_data[128..160], &proof_data[160..192],
+        ).map_err(|e| PyValueError::new_err(format!("π_B: {}", e)))?;
+        let pi_c = deserialize_g1(&proof_data[192..224], &proof_data[224..256])
+            .map_err(|e| PyValueError::new_err(format!("π_C: {}", e)))?;
+
+        let proof = Proof { a: pi_a, b: pi_b, c: pi_c };
+
+        // ── Step 2: Deserialize public inputs ──────────────────────────
+        let mut fr_inputs = Vec::with_capacity(inputs_data.len());
+        for (i, input) in inputs_data.iter().enumerate() {
+            let fr = bytes_to_fr(input)
+                .map_err(|e| PyValueError::new_err(format!("public_input[{}]: {}", i, e)))?;
+            fr_inputs.push(fr);
+        }
+
+        // ── Step 3: Verify the pairing equation ────────────────────────
+        verify_proof_inner(&proof, pvk, &fr_inputs)
+            .map_err(|e| PyValueError::new_err(e))
+    })
+}
+
+/// Python module definition.
+#[pymodule]
+fn vaikuntha_bn254(m: &Bound<'_, PyModule>) -> PyResult<()> {
+    m.add_function(wrap_pyfunction!(validate_point_g1, m)?)?;
+    m.add_function(wrap_pyfunction!(initialize_vkey, m)?)?;
+    m.add_function(wrap_pyfunction!(verify_groth16, m)?)?;
+    Ok(())
+}

verification/__init__.py

@@ -0,0 +1,4 @@
+"""
+GovBridge India — PROJECT VAIKUNTHA Phase 4.1
+Verification Package
+"""

verification/deserializer.py

@@ -0,0 +1,217 @@
+"""
+═══════════════════════════════════════════════════════════════════════════════
+GovBridge India — PROJECT VAIKUNTHA Phase 4.1
+Groth16 Proof Deserializer & Cryptographic Validator
+═══════════════════════════════════════════════════════════════════════════════
+
+Unpacks the 256-byte big-endian proof payload emitted by the frontend
+ZkProofExporter (gov_frontend/src/lib/ZkProofExporter.ts) and validates
+every elliptic curve point for curve membership and subgroup containment.
+
+Wire Format (256 bytes, big-endian):
+  Offset  | Size | Field
+  --------|------|-----------------------------------
+  [0..31] | 32   | π_A.x      (G1, Fq)
+  [32..63]| 32   | π_A.y      (G1, Fq)
+  [64..95]| 32   | π_B.x.c0   (G2, Fq component)
+  [96..127]| 32  | π_B.x.c1   (G2, Fq component)
+  [128..159]| 32 | π_B.y.c0   (G2, Fq component)
+  [160..191]| 32 | π_B.y.c1   (G2, Fq component)
+  [192..223]| 32 | π_C.x      (G1, Fq)
+  [224..255]| 32 | π_C.y      (G1, Fq)
+
+ARCHITECTURAL LAWS:
+  - NO floating-point arithmetic. All values are exact integer field elements.
+  - All Pydantic models use `bytes` fields with strict length validation.
+  - Cryptographic validation is delegated to the Rust extension
+    (vaikuntha_bn254) which releases the GIL during computation.
+═══════════════════════════════════════════════════════════════════════════════
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Final
+
+from pydantic import BaseModel, Field, field_validator, model_validator
+
+logger = logging.getLogger("govbridge.verification.deserializer")
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# SECTION 1: BN254 Curve Constants
+# ═══════════════════════════════════════════════════════════════════════════════
+
+# BN254 base field prime p
+# p = 21888242871839275222246405745257275088696311157297823662689037894645226208583
+BN254_P: Final[int] = 0x30644E72E131A029B85045B68181585D97816A916871CA8D3C208C16D87CFD47
+
+# BN254 scalar field order r  (same value as in vector_prover.cpp P_BYTES)
+# r = 21888242871839275222246405745257275088548364400416034343698204186575808495617
+BN254_R: Final[int] = 0x30644E72E131A029B85045B68181585D2833E84879B9709143E1F593F0000001
+
+# Proof payload size in bytes
+PROOF_SIZE: Final[int] = 256
+
+# Coordinate size in bytes (32 bytes = 256 bits for BN254 field elements)
+COORD_SIZE: Final[int] = 32
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# SECTION 2: Pydantic Type-Safe Models
+# ═══════════════════════════════════════════════════════════════════════════════
+
+class G1Point(BaseModel):
+    """
+    A point on the BN254 G₁ curve in affine coordinates.
+    Both coordinates are 32-byte big-endian field elements.
+    """
+    x: bytes = Field(..., min_length=COORD_SIZE, max_length=COORD_SIZE)
+    y: bytes = Field(..., min_length=COORD_SIZE, max_length=COORD_SIZE)
+
+    @field_validator("x", "y")
+    @classmethod
+    def validate_field_element(cls, v: bytes) -> bytes:
+        """Validate that the coordinate is a valid Fq element (< p)."""
+        val = int.from_bytes(v, byteorder="big")
+        if val >= BN254_P:
+            raise ValueError(
+                f"Coordinate value {val:#066x} >= BN254 base field prime p"
+            )
+        return v
+
+    model_config = {"frozen": True}
+
+
+class G2Point(BaseModel):
+    """
+    A point on the BN254 G₂ twisted curve in affine coordinates.
+    G₂ lives over Fq2 = Fq[u] / (u² + 1).
+    Each Fq2 element has two Fq components (c0, c1).
+    """
+    x_c0: bytes = Field(..., min_length=COORD_SIZE, max_length=COORD_SIZE)
+    x_c1: bytes = Field(..., min_length=COORD_SIZE, max_length=COORD_SIZE)
+    y_c0: bytes = Field(..., min_length=COORD_SIZE, max_length=COORD_SIZE)
+    y_c1: bytes = Field(..., min_length=COORD_SIZE, max_length=COORD_SIZE)
+
+    @field_validator("x_c0", "x_c1", "y_c0", "y_c1")
+    @classmethod
+    def validate_field_element(cls, v: bytes) -> bytes:
+        """Validate that the coordinate is a valid Fq element (< p)."""
+        val = int.from_bytes(v, byteorder="big")
+        if val >= BN254_P:
+            raise ValueError(
+                f"Coordinate value {val:#066x} >= BN254 base field prime p"
+            )
+        return v
+
+    model_config = {"frozen": True}
+
+
+class DeserializedProof(BaseModel):
+    """
+    A fully deserialized and field-validated Groth16 proof.
+    All coordinates have been checked for field membership (< p).
+    Curve and subgroup checks are performed separately by the Rust engine.
+    """
+    pi_a: G1Point
+    pi_b: G2Point
+    pi_c: G1Point
+    raw_bytes: bytes = Field(
+        ..., min_length=PROOF_SIZE, max_length=PROOF_SIZE,
+        description="Original 256-byte proof payload (retained for Rust FFI)"
+    )
+
+    model_config = {"frozen": True}
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# SECTION 3: Deserialization Engine
+# ═══════════════════════════════════════════════════════════════════════════════
+
+def deserialize_proof(payload: bytes) -> DeserializedProof:
+    """
+    Deserialize a 256-byte big-endian Groth16 proof payload.
+
+    Performs:
+      1. Length validation (exactly 256 bytes)
+      2. Field membership checks for all 8 coordinates (< p)
+      3. Structural packing into type-safe Pydantic models
+
+    Does NOT perform curve equation or subgroup checks — those are
+    delegated to the Rust extension (vaikuntha_bn254.verify_groth16)
+    which handles them in constant time with GIL released.
+
+    Args:
+        payload: Exactly 256 bytes of big-endian proof data.
+
+    Returns:
+        DeserializedProof with pi_a (G1), pi_b (G2), pi_c (G1).
+
+    Raises:
+        ValueError: If payload length is wrong or any coordinate >= p.
+    """
+    if len(payload) != PROOF_SIZE:
+        raise ValueError(
+            f"Proof payload must be exactly {PROOF_SIZE} bytes, got {len(payload)}"
+        )
+
+    logger.debug("Deserializing 256-byte Groth16 proof payload")
+
+    # ── Extract G₁ point π_A (offset 0..63) ───────────────────────────────
+    pi_a = G1Point(
+        x=payload[0:32],
+        y=payload[32:64],
+    )
+
+    # ── Extract G₂ point π_B (offset 64..191) ─────────────────────────────
+    pi_b = G2Point(
+        x_c0=payload[64:96],
+        x_c1=payload[96:128],
+        y_c0=payload[128:160],
+        y_c1=payload[160:192],
+    )
+
+    # ── Extract G₁ point π_C (offset 192..255) ────────────────────────────
+    pi_c = G1Point(
+        x=payload[192:224],
+        y=payload[224:256],
+    )
+
+    proof = DeserializedProof(
+        pi_a=pi_a,
+        pi_b=pi_b,
+        pi_c=pi_c,
+        raw_bytes=payload,
+    )
+
+    logger.info(
+        "Proof deserialized: π_A.x=%s... π_B.x.c0=%s... π_C.x=%s...",
+        payload[0:4].hex(),
+        payload[64:68].hex(),
+        payload[192:196].hex(),
+    )
+
+    return proof
+
+
+def validate_public_input(signal: bytes) -> None:
+    """
+    Validate a single public input (32-byte big-endian scalar field element).
+
+    The value must be < r (the BN254 scalar field order).
+
+    Args:
+        signal: 32 bytes, big-endian.
+
+    Raises:
+        ValueError: If length != 32 or value >= r.
+    """
+    if len(signal) != COORD_SIZE:
+        raise ValueError(
+            f"Public input must be exactly {COORD_SIZE} bytes, got {len(signal)}"
+        )
+    val = int.from_bytes(signal, byteorder="big")
+    if val >= BN254_R:
+        raise ValueError(
+            f"Public input {val:#066x} >= BN254 scalar field order r"
+        )

verification/groth16_verifier.py

@@ -0,0 +1,272 @@
+"""
+═══════════════════════════════════════════════════════════════════════════════
+GovBridge India — PROJECT VAIKUNTHA Phase 4.1
+Groth16 Verification Orchestrator
+═══════════════════════════════════════════════════════════════════════════════
+
+Orchestrates the full verification pipeline:
+  1. Accepts deserialized proof + public inputs
+  2. Loads the verification key from disk (cached in-process)
+  3. Delegates the Optimal Ate pairing computation to the Rust native
+     extension (vaikuntha_bn254) via PyO3 FFI
+  4. Returns a typed VerificationResult
+
+The Rust extension releases the Python GIL during the entire pairing
+evaluation (~3ms on x86-64), ensuring the FastAPI event loop and all
+concurrent request handlers remain fully unblocked.
+
+PERFORMANCE CHARACTERISTICS:
+  - Deserialization + field checks:  ~0.05ms  (Python, GIL held)
+  - Subgroup + pairing evaluation:   ~3ms     (Rust, GIL released)
+  - Total end-to-end:                ~3.5ms   per verification
+  - Theoretical ceiling:             ~280 verifications/sec (single core)
+  - With thread pool (4 workers):    ~1,120 verifications/sec
+
+SECURITY MODEL:
+  - All points are validated for curve membership AND subgroup containment
+    inside the Rust boundary BEFORE any pairing computation occurs.
+  - Invalid proofs produce cryptographically precise error messages (no
+    information leakage about the verification key internals).
+  - The verification key is loaded once and cached immutably.
+═══════════════════════════════════════════════════════════════════════════════
+"""
+
+from __future__ import annotations
+
+import asyncio
+import functools
+import hashlib
+import logging
+import time
+from concurrent.futures import ThreadPoolExecutor
+from pathlib import Path
+from typing import Final, Optional
+
+from pydantic import BaseModel, Field
+
+from verification.deserializer import (
+    DeserializedProof,
+    deserialize_proof,
+    validate_public_input,
+    PROOF_SIZE,
+    COORD_SIZE,
+)
+
+logger = logging.getLogger("govbridge.verification.groth16_verifier")
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# SECTION 1: Configuration
+# ═══════════════════════════════════════════════════════════════════════════════
+
+# Path to the serialized verification key (deployed alongside the backend)
+VKEY_PATH: Final[Path] = Path(__file__).parent / "vkey.bin"
+
+# Thread pool for offloading Rust FFI calls (GIL is released inside Rust,
+# but we still need a thread to call into Rust without blocking the event loop)
+_VERIFIER_THREAD_POOL: Final[ThreadPoolExecutor] = ThreadPoolExecutor(
+    max_workers=4,
+    thread_name_prefix="vaikuntha-verifier",
+)
+
+# Cached verification key bytes (loaded once, immutable)
+_vkey_cache: Optional[bytes] = None
+
+# SHA-256 of the trusted verification key. Set this value after the trusted
+# setup ceremony to enable integrity pinning. If None, integrity checking is
+# disabled (development mode only — MUST be set before production deployment).
+VKEY_EXPECTED_SHA256: Final[Optional[str]] = None  # e.g., "a1b2c3d4e5f6..."
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# SECTION 2: Verification Key Management
+# ═══════════════════════════════════════════════════════════════════════════════
+
+def initialize_verification_engine(num_public_inputs: int = 1) -> None:
+    """
+    Initializes the verification engine. Validates the trusted setup vkey,
+    checks its SHA-256 integrity, and locks it into the Rust extension's global memory.
+    MUST be called at FastAPI lifespan boot.
+
+    Raises:
+        FileNotFoundError: If vkey.bin is missing.
+        RuntimeError: If the file is suspiciously small or corrupted.
+    """
+    global _vkey_cache
+    if _vkey_cache is not None:
+        return
+
+    if not VKEY_PATH.exists():
+        raise FileNotFoundError(
+            f"Verification key not found at {VKEY_PATH}. "
+            "Run the trusted setup ceremony first."
+        )
+
+    raw = VKEY_PATH.read_bytes()
+
+    if len(raw) < 512:
+        raise RuntimeError(
+            f"Verification key at {VKEY_PATH} is only {len(raw)} bytes. "
+            "Expected >= 512 bytes (4 curve points + at least 1 IC point)."
+        )
+
+    # ── Integrity check: verify SHA-256 against trusted reference ────────
+    if VKEY_EXPECTED_SHA256 is not None:
+        actual = hashlib.sha256(raw).hexdigest()
+        if actual != VKEY_EXPECTED_SHA256:
+            raise RuntimeError(
+                f"Verification key integrity check FAILED. "
+                f"Expected SHA-256: {VKEY_EXPECTED_SHA256}, got: {actual}. "
+                f"The vkey.bin file may have been tampered with."
+            )
+        logger.info("VKey integrity check passed (SHA-256: %s...)", actual[:16])
+
+    _vkey_cache = raw
+    logger.info("Verification key loaded: %d bytes from %s", len(raw), VKEY_PATH)
+
+    try:
+        import vaikuntha_bn254  # type: ignore[import-not-found]
+        vaikuntha_bn254.initialize_vkey(raw, num_public_inputs)
+        logger.info("PVK successfully locked into Rust global memory.")
+    except ImportError:
+        logger.warning("vaikuntha_bn254 not installed, skipping Rust initialization.")
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# SECTION 3: Result Types
+# ═══════════════════════════════════════════════════════════════════════════════
+
+class VerificationResult(BaseModel):
+    """Typed result of a Groth16 proof verification."""
+    valid: bool = Field(..., description="True if the proof is cryptographically valid")
+    verification_time_ms: float = Field(
+        ..., ge=0, description="Wall-clock time for the verification in milliseconds"
+    )
+    error: Optional[str] = Field(
+        default=None, description="Human-readable error message if verification failed"
+    )
+
+    model_config = {"frozen": True}
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# SECTION 4: Synchronous Verification (runs in thread pool)
+# ═══════════════════════════════════════════════════════════════════════════════
+
+def _verify_sync(proof_bytes: bytes, public_input_bytes: list[bytes]) -> VerificationResult:
+    """
+    Synchronous verification — called from the thread pool.
+
+    This function:
+      1. Calls the Rust extension (GIL released during pairing)
+      2. Returns a typed result
+
+    MUST NOT be called from the async event loop directly.
+    """
+    start = time.perf_counter()
+
+    try:
+        # Import here to allow graceful degradation if wheel not installed
+        import vaikuntha_bn254  # type: ignore[import-not-found]
+
+        result: bool = vaikuntha_bn254.verify_groth16(
+            proof_bytes,
+            public_input_bytes,
+        )
+
+        elapsed_ms = (time.perf_counter() - start) * 1000.0
+        logger.info(
+            "Groth16 verification %s in %.2fms",
+            "PASSED" if result else "FAILED",
+            elapsed_ms,
+        )
+
+        return VerificationResult(
+            valid=result,
+            verification_time_ms=round(elapsed_ms, 3),
+        )
+
+    except ImportError:
+        elapsed_ms = (time.perf_counter() - start) * 1000.0
+        error_msg = (
+            "vaikuntha_bn254 native extension not installed. "
+            "Build with: cd gov_backend/vaikuntha_bn254 && maturin develop --release"
+        )
+        logger.error(error_msg)
+        return VerificationResult(
+            valid=False,
+            verification_time_ms=round(elapsed_ms, 3),
+            error=error_msg,
+        )
+
+    except ValueError as e:
+        # Deserialization or cryptographic validation failure
+        elapsed_ms = (time.perf_counter() - start) * 1000.0
+        logger.warning("Proof rejected: %s (%.2fms)", str(e), elapsed_ms)
+        return VerificationResult(
+            valid=False,
+            verification_time_ms=round(elapsed_ms, 3),
+            error=str(e),
+        )
+
+    except Exception as e:
+        elapsed_ms = (time.perf_counter() - start) * 1000.0
+        logger.exception("Unexpected verification error")
+        return VerificationResult(
+            valid=False,
+            verification_time_ms=round(elapsed_ms, 3),
+            error=f"Internal verification error: {type(e).__name__}: {e}",
+        )
+
+
+# ═══��═══════════════════════════════════════════════════════════════════════════
+# SECTION 5: Async Verification (event-loop safe)
+# ═══════════════════════════════════════════════════════════════════════════════
+
+async def verify_groth16_async(
+    proof_bytes: bytes,
+    public_input_bytes: list[bytes],
+) -> VerificationResult:
+    """
+    Async-safe Groth16 verification.
+
+    Offloads the Rust FFI call to a dedicated thread pool so the uvicorn
+    event loop is NEVER blocked.
+
+    Pipeline:
+      1. [Event Loop] Validate inputs (fast, ~0.05ms)
+      2. [Thread Pool] Rust pairing computation (GIL released, ~3ms)
+      3. [Event Loop] Return result
+
+    Args:
+        proof_bytes: Exactly 256 bytes of raw proof data.
+        public_input_bytes: List of 32-byte big-endian scalar field elements.
+
+    Returns:
+        VerificationResult with valid=True/False and timing data.
+    """
+    # Pre-validate on the event loop (cheap operations, no GIL contention)
+    if len(proof_bytes) != PROOF_SIZE:
+        return VerificationResult(
+            valid=False,
+            verification_time_ms=0.0,
+            error=f"Proof must be exactly {PROOF_SIZE} bytes, got {len(proof_bytes)}",
+        )
+
+    for i, signal in enumerate(public_input_bytes):
+        try:
+            validate_public_input(signal)
+        except ValueError as e:
+            return VerificationResult(
+                valid=False,
+                verification_time_ms=0.0,
+                error=f"public_input[{i}]: {e}",
+            )
+
+    # Offload the heavy Rust computation to the thread pool
+    loop = asyncio.get_running_loop()
+    result = await loop.run_in_executor(
+        _VERIFIER_THREAD_POOL,
+        functools.partial(_verify_sync, proof_bytes, public_input_bytes),
+    )
+
+    return result

verification/routes.py

@@ -0,0 +1,182 @@
+"""
+═══════════════════════════════════════════════════════════════════════════════
+GovBridge India — PROJECT VAIKUNTHA Phase 4.1
+POST /api/verify-proof — Groth16 Zero-Knowledge Proof Verification Endpoint
+═══════════════════════════════════════════════════════════════════════════════
+
+Accepts a raw 256-byte proof + public signals, orchestrates the full
+deserialization → validation → Rust pairing verification pipeline.
+
+Request format:
+  POST /api/verify-proof
+  Content-Type: application/json
+
+  {
+    "proof": "<512-char hex string encoding 256 bytes>",
+    "public_inputs": ["<64-char hex string>", ...]
+  }
+
+Response format:
+  {
+    "valid": true/false,
+    "verification_time_ms": 3.142,
+    "error": null | "human-readable error"
+  }
+
+RATE LIMITING: 20/minute per IP (crypto verification is CPU-intensive).
+═══════════════════════════════════════════════════════════════════════════════
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+from typing import List
+
+from fastapi import APIRouter, Request
+from pydantic import BaseModel, Field, field_validator
+from typing import Any, List
+from slowapi import Limiter
+from slowapi.util import get_remote_address
+
+from verification.groth16_verifier import verify_groth16_async, VerificationResult
+
+# ── Rate Limiter (accesses app.state.limiter configured in api.py) ────────
+limiter = Limiter(key_func=get_remote_address)
+
+logger = logging.getLogger("govbridge.verification.routes")
+
+router = APIRouter(prefix="/api", tags=["verification"])
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# SECTION 1: Request / Response Models
+# ═══════════════════════════════════════════════════════════════════════════════
+
+class VerifyProofRequest(BaseModel):
+    """
+    Incoming proof verification request.
+
+    The proof is transmitted as a hex-encoded string (512 hex chars = 256 bytes).
+    Public inputs are hex-encoded scalar field elements (64 hex chars = 32 bytes each).
+    """
+    proof: str = Field(
+        ...,
+        min_length=512,
+        max_length=512,
+        description="Hex-encoded 256-byte Groth16 proof (π_A || π_B || π_C)"
+    )
+    public_inputs: List[str] = Field(
+        ...,
+        min_length=1,
+        max_length=32,
+        description="Hex-encoded 32-byte public input scalars"
+    )
+
+    @field_validator("proof", mode="before")
+    @classmethod
+    def validate_proof_hex(cls, v: Any) -> Any:
+        """Ensure the proof is a valid hex string of exactly 512 characters."""
+        if not isinstance(v, str): return v
+        v = v.lower().strip()
+        if v.startswith("0x"):
+            v = v[2:]
+        if len(v) != 512:
+            raise ValueError(
+                f"Proof hex must be exactly 512 characters (256 bytes), got {len(v)}"
+            )
+        if not re.fullmatch(r"[0-9a-f]+", v):
+            raise ValueError("Proof hex contains non-hexadecimal characters")
+        return v
+
+    @field_validator("public_inputs", mode="before")
+    @classmethod
+    def validate_public_inputs_hex(cls, v: Any) -> Any:
+        """Validate each public input is a 64-char hex string."""
+        if not isinstance(v, list): return v
+        result = []
+        for i, inp in enumerate(v):
+            if not isinstance(inp, str):
+                result.append(inp)
+                continue
+            inp = inp.lower().strip()
+            if inp.startswith("0x"):
+                inp = inp[2:]
+            if len(inp) != 64:
+                raise ValueError(
+                    f"public_inputs[{i}]: must be exactly 64 hex chars (32 bytes), got {len(inp)}"
+                )
+            if not re.fullmatch(r"[0-9a-f]+", inp):
+                raise ValueError(
+                    f"public_inputs[{i}]: contains non-hexadecimal characters"
+                )
+            result.append(inp)
+        return result
+
+
+class VerifyProofResponse(BaseModel):
+    """Proof verification response."""
+    valid: bool
+    verification_time_ms: float
+    error: str | None = None
+
+
+# ═════════════════════════════════════════════════��═════════════════════════════
+# SECTION 2: Endpoint Definition
+# ═══════════════════════════════════════════════════════════════════════════════
+
+@router.post(
+    "/verify-proof",
+    response_model=VerifyProofResponse,
+    summary="Verify a Groth16 ZK-SNARK proof",
+    description=(
+        "Accepts a 256-byte BN254 Groth16 proof and public inputs. "
+        "Returns whether the proof is cryptographically valid. "
+        "The pairing computation is offloaded to a Rust native extension "
+        "that releases the Python GIL."
+    ),
+)
+@limiter.limit("20/minute")
+async def verify_proof(
+    request: Request,
+    body: VerifyProofRequest,
+) -> VerifyProofResponse:
+    """
+    POST /api/verify-proof
+
+    Pipeline:
+      1. Pydantic validates hex format and lengths
+      2. Convert hex strings to raw bytes
+      3. Delegate to verify_groth16_async (thread-pool → Rust FFI)
+      4. Return typed response
+
+    The entire pipeline is non-blocking. The Rust pairing computation
+    (~3ms) runs in a dedicated thread pool with the GIL released.
+    """
+    logger.info(
+        "Verification request: proof=%s... inputs=%d",
+        body.proof[:16],
+        len(body.public_inputs),
+    )
+
+    # Convert hex to raw bytes
+    proof_bytes = bytes.fromhex(body.proof)
+    public_input_bytes = [bytes.fromhex(inp) for inp in body.public_inputs]
+
+    # Execute async verification (offloaded to Rust thread pool)
+    result: VerificationResult = await verify_groth16_async(
+        proof_bytes=proof_bytes,
+        public_input_bytes=public_input_bytes,
+    )
+
+    # Sanitize error messages for production: expose detail only in debug mode
+    safe_error = (
+        "Proof verification failed" if result.error and not getattr(request.app, 'debug', False)
+        else result.error
+    )
+
+    return VerifyProofResponse(
+        valid=result.valid,
+        verification_time_ms=result.verification_time_ms,
+        error=safe_error,
+    )