feat: add ZKP Consensus Engine architecture

schemas/zk-consensus-block.schema.json

@@ -0,0 +1,111 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://identity.memact.org/schemas/zk-consensus-block.schema.json",
+  "title": "ZKConsensusBlock",
+  "description": "Schema for a consolidated batch block output by the ZK consensus engine containing multi-transaction rollup proofs",
+  "type": "object",
+  "required": [
+    "block_number",
+    "timestamp",
+    "old_state_root",
+    "new_state_root",
+    "batch_proof",
+    "transactions_count",
+    "validator_signatures"
+  ],
+  "properties": {
+    "block_number": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Sequential block number representing height of the context state ledger"
+    },
+    "timestamp": {
+      "type": "integer",
+      "description": "Epoch timestamp when consensus was reached and batch proof was finalized"
+    },
+    "old_state_root": {
+      "type": "string",
+      "pattern": "^0x[a-fA-F0-9]{64}$",
+      "description": "Hex encoded 32-byte root hash of the SMT before state batch updates"
+    },
+    "new_state_root": {
+      "type": "string",
+      "pattern": "^0x[a-fA-F0-9]{64}$",
+      "description": "Hex encoded 32-byte root hash of the SMT after applying state batch updates"
+    },
+    "batch_proof": {
+      "type": "object",
+      "description": "Serialized Groth16 ZK rollup proof demonstrating correct multi-state transition batch logic",
+      "required": [
+        "pi_a",
+        "pi_b",
+        "pi_c"
+      ],
+      "properties": {
+        "pi_a": {
+          "type": "array",
+          "minItems": 2,
+          "maxItems": 2,
+          "items": {
+            "type": "string",
+            "pattern": "^0x[a-fA-F0-9]+$"
+          }
+        },
+        "pi_b": {
+          "type": "array",
+          "minItems": 2,
+          "maxItems": 2,
+          "items": {
+            "type": "array",
+            "minItems": 2,
+            "maxItems": 2,
+            "items": {
+              "type": "string",
+              "pattern": "^0x[a-fA-F0-9]+$"
+            }
+          }
+        },
+        "pi_c": {
+          "type": "array",
+          "minItems": 2,
+          "maxItems": 2,
+          "items": {
+            "type": "string",
+            "pattern": "^0x[a-fA-F0-9]+$"
+          }
+        }
+      },
+      "additionalProperties": false
+    },
+    "transactions_count": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "Number of state transitions reconciled and packed into this batch"
+    },
+    "validator_signatures": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": [
+          "validator_identity",
+          "signature"
+        ],
+        "properties": {
+          "validator_identity": {
+            "type": "string",
+            "description": "Public identifier/address of the signing validator node"
+          },
+          "signature": {
+            "type": "string",
+            "pattern": "^0x[a-fA-F0-9]+$",
+            "description": "ECDSA or EdDSA cryptographic signature over the state roots transition"
+          }
+        },
+        "additionalProperties": false
+      },
+      "description": "Signatures collected from validators confirming verification of the batch proof"
+    }
+  },
+  "additionalProperties": false
+}

schemas/zk-context-transition.schema.json

@@ -0,0 +1,111 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://identity.memact.org/schemas/zk-context-transition.schema.json",
+  "title": "ZKContextTransitionTransaction",
+  "description": "Schema for a single Zero Knowledge context state update transition transaction (CTT)",
+  "type": "object",
+  "required": [
+    "sender_identity",
+    "old_state_root",
+    "new_state_root",
+    "claim_key",
+    "proof",
+    "public_inputs"
+  ],
+  "properties": {
+    "sender_identity": {
+      "type": "string",
+      "description": "Identifier of the client application making the contribution"
+    },
+    "old_state_root": {
+      "type": "string",
+      "pattern": "^0x[a-fA-F0-9]{64}$",
+      "description": "Hex encoded 32-byte hash of the previous Context State Root (CSR)"
+    },
+    "new_state_root": {
+      "type": "string",
+      "pattern": "^0x[a-fA-F0-9]{64}$",
+      "description": "Hex encoded 32-byte hash of the proposed Context State Root (CSR)"
+    },
+    "claim_key": {
+      "type": "string",
+      "pattern": "^0x[a-fA-F0-9]{64}$",
+      "description": "The Poseidon hash representing the claim path index inside the Sparse Merkle Tree"
+    },
+    "proof": {
+      "type": "object",
+      "description": "The serialized groth16 ZK proof elements validating this transaction transition",
+      "required": [
+        "pi_a",
+        "pi_b",
+        "pi_c"
+      ],
+      "properties": {
+        "pi_a": {
+          "type": "array",
+          "minItems": 2,
+          "maxItems": 2,
+          "items": {
+            "type": "string",
+            "pattern": "^0x[a-fA-F0-9]+$"
+          }
+        },
+        "pi_b": {
+          "type": "array",
+          "minItems": 2,
+          "maxItems": 2,
+          "items": {
+            "type": "array",
+            "minItems": 2,
+            "maxItems": 2,
+            "items": {
+              "type": "string",
+              "pattern": "^0x[a-fA-F0-9]+$"
+            }
+          }
+        },
+        "pi_c": {
+          "type": "array",
+          "minItems": 2,
+          "maxItems": 2,
+          "items": {
+            "type": "string",
+            "pattern": "^0x[a-fA-F0-9]+$"
+          }
+        }
+      },
+      "additionalProperties": false
+    },
+    "public_inputs": {
+      "type": "object",
+      "description": "Public variables that are input directly to the state transition circuit validator",
+      "required": [
+        "old_state_root",
+        "new_state_root",
+        "claim_key_hash",
+        "contributor_authority_hash"
+      ],
+      "properties": {
+        "old_state_root": {
+          "type": "string",
+          "pattern": "^0x[a-fA-F0-9]{64}$"
+        },
+        "new_state_root": {
+          "type": "string",
+          "pattern": "^0x[a-fA-F0-9]{64}$"
+        },
+        "claim_key_hash": {
+          "type": "string",
+          "pattern": "^0x[a-fA-F0-9]{64}$"
+        },
+        "contributor_authority_hash": {
+          "type": "string",
+          "pattern": "^0x[a-fA-F0-9]{64}$",
+          "description": "Hash linking the client identity with the authorized public key stored in the SMT"
+        }
+      },
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": false
+}

specs/EPIC-ZKP-Consensus-Engine-Issues.md

@@ -0,0 +1,101 @@
+# Epic: ZKP Consensus Engine (Zero Knowledge Proofs)
+## Repository: Protocol
+## Epic Mapping Document
+
+This document outlines the detailed issues to be created in the issue trackers of the four repositories of the Memact family: `Protocol`, `Contracts`, `Access` (Identity Provider), and `SDK`.
+
+---
+
+## 1. Protocol Repository (`Protocol`)
+
+### Issue PROTOCOL-201: Draft RFC-005: ZKP-Enabled Context Consensus Engine
+* **Type**: Feature / Specification
+* **Priority**: High
+* **Description**:
+  Create the formal protocol specification (RFC-005) detailing the Sparse Merkle Tree (SMT) architecture, Context Transition Transaction (CTT) structures, ZK-Rollup batch proving pipelines, and Conflict Resolution rules (CRP).
+* **Acceptance Criteria**:
+  * RFC-005 markdown document is merged in `specs/`.
+  * Fully specifies SMT leaf constructions using Poseidon hashing.
+  * Specifies sequential transitions and signature-based authority controls inside circuits.
+
+### Issue PROTOCOL-202: Define JSON Schemas for Transaction and Consensus Block
+* **Type**: Feature / Schema Definition
+* **Priority**: High
+* **Description**:
+  Create JSON schemas for `zk-context-transition.schema.json` and `zk-consensus-block.schema.json` to enable automated structural validation.
+* **Acceptance Criteria**:
+  * JSON schema files created in `schemas/`.
+  * Validate that root properties like `block_number`, `proof`, `public_inputs` (with proper pattern matches for 32-byte hex hashes), and signature fields match expectations.
+
+---
+
+## 2. Contracts Repository (`Contracts`)
+
+### Issue CONTRACTS-301: Implement Sparse Merkle Tree (SMT) Poseidon Circuits
+* **Type**: Feature
+* **Priority**: Critical (Blocker for proving)
+* **Description**:
+  Write the core circuit logic (e.g. in Circom or Halo2) validating Sparse Merkle Tree membership. The circuit should verify Poseidon hashing over a path of depth 256.
+* **Acceptance Criteria**:
+  * Provide compilation artifacts for SMT inclusion verification.
+  * Include tests verifying path generation and checking incorrect path rejection.
+
+### Issue CONTRACTS-302: Implement Batch Rollup Prover Circuit
+* **Type**: Feature
+* **Priority**: High
+* **Description**:
+  Write a rollup/batch circuit that takes $N$ state transition witness elements, verifies authority signatures, checks trust weights (CRP conflict resolution rules), and outputs a combined state root update proof.
+* **Acceptance Criteria**:
+  * Proves transition logic mathematically inside a unified Groth16/PLONK circuit.
+  * Correctly rejects updates signed by unauthorized accounts.
+
+---
+
+## 3. Access Repository (Reference IdP / Validator Node: `Access`)
+
+### Issue ACCESS-401: Implement Transaction Mempool
+* **Type**: Feature
+* **Priority**: High
+* **Description**:
+  Add an incoming transaction mempool endpoint `/contribute/zkp` that receives `zk-context-transition` payloads, validates their individual structural properties, and queues them for reconciliation.
+* **Acceptance Criteria**:
+  * CTTs are successfully stored in a temporary buffer.
+  * Validate sender signature and basic schema conformance prior to queuing.
+
+### Issue ACCESS-402: Implement Batch Prover and Dispute Resolution Manager
+* **Type**: Feature
+* **Priority**: High
+* **Description**:
+  Build the consensus batch compiler. It must aggregate queued CTTs, run conflict resolution heuristics based on registered weight limits, generate the batch witness inputs, and run the rollup prover to produce the block's `batch_proof`.
+* **Acceptance Criteria**:
+  * Periodic block execution engine successfully executes.
+  * Valid consensus block payloads are generated according to `zk-consensus-block.schema.json`.
+
+### Issue ACCESS-403: Implement Validator Consensus Signer
+* **Type**: Feature
+* **Priority**: Medium
+* **Description**:
+  Implement block verification and signature collection. Validators must verify incoming block proofs off-chain and sign the block header upon successful validation.
+* **Acceptance Criteria**:
+  * Nodes broadcast signatures when proof validates.
+  * State root is canonicalized once signatures meet quorum threshold.
+
+---
+
+## 4. Client SDK Repository (`SDK`)
+
+### Issue SDK-501: Implement SMT Local Leaf Hash Builder
+* **Type**: Feature
+* **Priority**: High
+* **Description**:
+  Add local client utilities to construct and salt claim leaf values matching Poseidon hash criteria.
+* **Acceptance Criteria**:
+  * Expose function `buildLeafHash(key, value, salt)` returning corresponding Poseidon output.
+
+### Issue SDK-502: CTT Submission Client
+* **Type**: Feature
+* **Priority**: Medium
+* **Description**:
+  Build client transaction wrapper and signer. Enables authorized SDK instances to sign updates, generate inclusion paths, and post CTT objects directly to validator mempools.
+* **Acceptance Criteria**:
+  * SDK exposes `.submitContextContribution(claimKey, newValue, provingWitness)`.