Skip to content

Repository files navigation

⚖️ Legal TimeLock Network (LTN)

████████╗██╗███╗   ███╗███████╗██╗      ██████╗  ██████╗██╗  ██╗
╚══██╔══╝██║████╗ ████║██╔════╝██║     ██╔═══██╗██╔════╝██║ ██╔╝
   ██║   ██║██╔████╔██║█████╗  ██║     ██║   ██║██║     █████═╝ 
   ██║   ██║██║╚██╔╝██║██╔══╝  ██║     ██║   ██║██║     ██╔═██╗ 
   ██║   ██║██║ ╚═╝ ██║███████╗███████╗╚██████╔╝╚██████╗██║ ╚██╗
   ╚═╝   ╚═╝╚═╝     ╚═╝╚══════╝╚══════╝ ╚═════╝  ╚═════╝╚═╝  ╚═╝

Decentralized Legal Document Notarization, Autonomous AI Verification & Solana Blockchain Title Registry

CI & Build Verification Solana Devnet Next.js 16 React 19 TypeScript 5.4 NVIDIA Nemotron PostgreSQL & Prisma IPFS / Pinata Tailwind CSS v4 License: MIT

Solana Anchor Program ID: EbKjjyvxck5REvVXTXuAvPDrydzKFniiGgLdKSeyfc3w


⚡ Executive Overview

Legal TimeLock Network (LTN) is an enterprise-grade, decentralized GovTech and LegalTech infrastructure platform engineered to eliminate deed forgery, backdated notarizations, and institutional trust deficits in real-world asset registers.

LTN couples Solana Program Derived Address (PDA) ledger immutability, an orchestrated 31-agent NVIDIA Nemotron AI Intelligence Suite, a deterministic Verification Proof Layer (VPL), and Section 65B Indian Evidence Act (IEA) compliance to deliver mathematical authenticity across the lifecycle of real estate and corporate deeds.

┌─────────────────────────────────────────────────────────────────────────────────────────────┐
│                                   CORE VALUE PROPOSITION                                   │
│  "Transform fragile physical legal deeds into cryptographically anchored, AI-adjudicated,   │
│   and independently verifiable Digital Twins without exposing private PII on the ledger."   │
└─────────────────────────────────────────────────────────────────────────────────────────────┘

🎯 High-Level Feature Grid

🔐 Cryptographic Integrity 🤖 NVIDIA AI Intelligence ⛓️ Solana Blockchain Ledger 📜 Verification Proof Layer
SHA-256 Client-Server Hashing
Deterministic C3 chain-of-custody verification rejects modified buffers before persistence.
31 Orchestrated AI Agents
Powered by nemotron-4-340b-instruct with strict zero-mock error boundaries and circuit breakers.
Zero-Gas Relayer Anchoring
Program Derived Addresses (PDAs) bind document hashes, signatures, and transfers to Solana Devnet.
Dynamic Trust Scoring
Deterministic 0–100 scoring engine with dispute resolution challenges and IPFS evidence binding.
🏛️ Judicial & Notary Suite 🧬 Digital Twin Assets 🌐 Decentralized Direct Verifier 🛡️ ABAC & Security Hardening
Interactive Case Workspaces
Notary verification checklists, simulated Class-3 DSC token approvals, and Judge adjudication tools.
Living Property State
State-synchronized representation of properties, title deeds, encumbrances, and ownership history.
Zero-Backend Verification
Client-side binary deserializer reads Solana ledger accounts directly over standard JSON-RPC.
Enterprise ABAC Policies
74 PostgreSQL models, append-only audit event tables, and request correlation context.

📑 Table of Contents


💡 What is TimeLock?

In One Sentence

TimeLock is a decentralized legal registry that anchors document fingerprints and notary attestations to the Solana blockchain while utilizing an orchestrated suite of NVIDIA AI agents to detect fraud, verify chain of title, and adjudicate property transfers.

Technically

TimeLock implements a dual-layer verification protocol:

  1. Off-Chain Sovereign Storage & Intelligence: Original deed binaries are encrypted with AES-256-CBC, pinned to decentralized IPFS storage, and parsed by NVIDIA Nemotron-4-340B LLM agents to extract legal metadata, identify spatial boundary conflicts, and run cross-examination checks.
  2. On-Chain Deterministic Anchoring: Canonical SHA-256 hashes of the deed and the subsequent Verification Proof Layer (VPL) records are written as deterministic Program Derived Address (PDA) accounts on Solana Devnet via an authority relayer, allowing any court, bank, or citizen to verify authentic title status without third-party gatekeepers.

Why It Matters

In real estate and corporate governance, land registry records are plagued by counterfeit deeds, double mortgages, backdated notarizations, and corrupted registry databases. TimeLock makes backdating mathematically impossible and transforms static paper agreements into auditable, self-verifying digital twins.


🚩 The Problem & The TimeLock Solution

┌────────────────────────────────────────────────────────┬────────────────────────────────────────────────────────┐
│                   THE REAL-WORLD PROBLEM               │                   THE TIMELOCK SOLUTION                │
├────────────────────────────────────────────────────────┼────────────────────────────────────────────────────────┤
│ ❌ Fragile Paper & Database Records                    │ 🔐 Cryptographic SHA-256 Fingerprinting               │
│ Physical deeds can be forged; central SQL registries    │ Every document receives a deterministic SHA-256 hash   │
│ are susceptible to insider modification and tampering. │ verified client-side before submission.                │
├────────────────────────────────────────────────────────┼────────────────────────────────────────────────────────┤
│ ❌ Backdated Notarizations & Fake Stamps               │ ⛓️ Solana Blockchain Slot-Time Anchoring              │
│ Dishonest parties collude with notaries to backdate    │ TimeLock records document hashes into Solana PDAs with │
│ contracts and create counterfeit priority claims.      │ immutable Unix timestamps and cluster slot numbers.    │
├────────────────────────────────────────────────────────┼────────────────────────────────────────────────────────┤
│ ❌ Undetected Double-Registration & Title Conflicts    │ 🤖 Autonomous AI Conflict Investigator                 │
│ The same parcel of land is sold to multiple buyers     │ AI agents scan property IDs, survey numbers, and title │
│ using duplicate registration numbers.                  │ chains across historical deeds to flag overlaps.       │
├────────────────────────────────────────────────────────┼────────────────────────────────────────────────────────┤
│ ❌ Fragmented & Opaque Verification Process            │ 📐 Verification Proof Layer (VPL)                      │
│ Verification relies on subjective paper checks with    │ Structured checklist, evidence IPFS attachments, and   │
│ zero audit trail of what the notary examined.          │ challenge justifications compiled into a signed proof. │
├────────────────────────────────────────────────────────┼────────────────────────────────────────────────────────┤
│ ❌ Inadmissible Digital Evidence in Court              │ 📜 Section 65B Indian Evidence Act Compliance          │
│ Generic blockchain hashes fail court admissibility     │ Generates automated, legally formatted Section 65B     │
│ standards without formal electronic certificates.      │ certificates referencing block slot and relayer PKs.   │
└────────────────────────────────────────────────────────┴────────────────────────────────────────────────────────┘

🏛️ System Architecture

flowchart TB
    subgraph Clients["Client Layer"]
        UI_Citizen["Citizen Portal"]
        UI_Notary["Notary Workspace"]
        UI_Judge["Judicial and AVCC Suite"]
        UI_Verify["Decentralized Verifier"]
    end

    subgraph Gateway["Backend Gateway and Middleware"]
        API_GW["REST API Gateway"]
        AUTH_MW["JWT Auth and Context Correlation"]
        RATE_MW["Sliding Window Rate Limiters"]
        CIRCUIT["Circuit Breakers"]
    end

    subgraph Services["Core Domain Services"]
        SVC_DOC["Document Service"]
        SVC_VPL["Verification Proof Layer"]
        SVC_ORCH["AI Orchestrator"]
        SVC_CHAIN["Blockchain Service"]
        SVC_STORE["Storage Service"]
        SVC_TRANSFER["Ownership Transfer Service"]
        SVC_TWIN["Digital Twin Engine"]
        SVC_N8N["Automation Webhook Service"]
    end

    subgraph AISuite["Autonomous AI Intelligence Suite"]
        AI_GATE["Document Legality Gatekeeper"]
        AI_FRAUD["Fraud Risk Classifier"]
        AI_CONFLICT["Conflict Investigator"]
        AI_CROSS["Cross-Examination Engine"]
        AI_DECISION["Judicial Decision Copilot"]
        AI_GRAPH["Trust Graph and Anomaly Agent"]
    end

    subgraph Persistence["Persistence and Storage Layer"]
        DB_PG[("PostgreSQL Database")]
        IPFS_NODE[("Pinata IPFS Storage")]
    end

    subgraph Blockchain["Solana Blockchain Layer"]
        SOL_PROG["Anchor Program"]
        PDA_DOC["DocumentRecord PDA"]
        PDA_SIG["SignatureRecord PDA"]
        PDA_XFER["OwnershipTransferRecord PDA"]
    end

    UI_Citizen --> API_GW
    UI_Notary --> API_GW
    UI_Judge --> API_GW
    UI_Verify --> SOL_PROG

    API_GW --> AUTH_MW
    AUTH_MW --> RATE_MW
    RATE_MW --> CIRCUIT

    CIRCUIT --> SVC_DOC
    CIRCUIT --> SVC_VPL
    CIRCUIT --> SVC_TRANSFER
    CIRCUIT --> SVC_TWIN

    SVC_DOC --> AI_GATE
    SVC_DOC --> SVC_STORE
    SVC_DOC --> SVC_CHAIN
    SVC_DOC --> SVC_ORCH

    SVC_VPL --> SVC_CHAIN
    SVC_VPL --> SVC_N8N
    SVC_TRANSFER --> SVC_CHAIN

    SVC_ORCH --> AI_FRAUD
    SVC_ORCH --> AI_CONFLICT
    SVC_ORCH --> AI_CROSS
    SVC_ORCH --> AI_DECISION
    SVC_ORCH --> AI_GRAPH

    SVC_STORE --> IPFS_NODE
    SVC_DOC --> DB_PG
    SVC_VPL --> DB_PG
    SVC_ORCH --> DB_PG
    SVC_TRANSFER --> DB_PG
    SVC_TWIN --> DB_PG

    SVC_CHAIN --> SOL_PROG
    SOL_PROG --> PDA_DOC
    SOL_PROG --> PDA_SIG
    SOL_PROG --> PDA_XFER
Loading

🔄 End-to-End Document Lifecycle

sequenceDiagram
    autonumber
    actor Citizen as Citizen / Executant
    participant UI as Next.js Frontend
    participant API as Express API Gateway
    participant AI_Gate as NVIDIA Legality Agent
    participant IPFS as Pinata IPFS Storage
    participant DB as PostgreSQL Database
    participant Solana as Solana Anchor Program
    actor Notary as Licensed Notary
    participant VPL as VPL Engine & AI Copilot
    actor Public as Bank / Court / Public Verifier

    Citizen->>UI: Submit PDF Deed and Metadata
    UI->>UI: Calculate SHA-256 Client Fingerprint
    UI->>API: Upload Payload with Integrity Receipt
    
    API->>AI_Gate: Synchronous Legality Audit
    AI_Gate-->>API: Legal Deed Classification Confirmed
    
    API->>API: Validate Client Hash Matches Server Hash
    API->>IPFS: Encrypt AES-256 & Pin Binary
    IPFS-->>API: Return IPFS CID Reference
    API->>DB: Create Document Record (Pending)
    
    API->>Solana: Initialize Document PDA
    Solana-->>API: On-Chain Anchor Confirmed
    API->>DB: Update Document State (On-Chain Confirmed)
    API-->>UI: Return Document Identifier & QR Reference
    
    API-)DB: Trigger AI Intelligence Suite
    
    Notary->>UI: Open Notary Verification Case
    UI->>VPL: Load Checklists and AI Copilot Insights
    Notary->>VPL: Verify Evidence and Resolve Challenges
    Notary->>VPL: Finalize Verification with Digital Signature
    
    VPL->>VPL: Compute Deterministic Trust Score
    VPL->>Solana: Record VPL Attestation Signature
    Solana-->>VPL: Attestation Confirmed On-Chain
    VPL->>DB: Update Case and Document State (Fully Executed)
    
    Public->>UI: Scan QR Code or Open Public Verifier
    UI->>Solana: Direct RPC Query to Document PDA
    Solana-->>UI: Return Account Binary State
    UI->>UI: Deserialize & Match Content Hash
    UI-->>Public: Display Verified Authenticity Certificate
Loading

🤖 Autonomous AI Intelligence Suite

TimeLock integrates 31 specialized AI services located in backend/src/services/ai/. The platform connects to the NVIDIA Integrate API using the nvidia/nemotron-4-340b-instruct high-reasoning foundation model.

AI Agent Architecture

┌─────────────────────────────────────────────────────────────────────────────────────────────┐
│                             NEMOTRON SERVICE RESILIENCE ENGINE                              │
│                                                                                             │
│  ┌─────────────────────────┐     ┌────────────────────────┐     ┌────────────────────────┐  │
│  │   STRICT NO-MOCK RULE   │     │    CIRCUIT BREAKER     │     │  DEDUPLICATION CACHE   │  │
│  │ Throws AIServiceError   │ ──► │ Tripped after 3 errors │ ──► │ In-memory SHA-256 hash │  │
│  │ if NVIDIA_API_KEY is    │     │ 45s timeout, 10s cool  │     │ key with 10-minute TTL │  │
│  │ missing or mock_*       │     │ Exponential backoff    │     │ prevents duplicate GPU │  │
│  └─────────────────────────┘     └────────────────────────┘     └────────────────────────┘  │
└─────────────────────────────────────────────────────────────────────────────────────────────┘

Complete AI Services Catalog (31 Agents)

flowchart LR
    subgraph DocDomain["1. Document Intelligence"]
        A1["Document Legality Agent"]
        A2["Registration Predictor Agent"]
    end

    subgraph VerDomain["2. Verification Intelligence"]
        B1["AI Assessment Service"]
        B2["Verification Copilot Service"]
        B3["Cross-Examination Agent"]
        B4["Evidence Recommendation Agent"]
        B5["Playbook Compliance Service"]
    end

    subgraph RiskDomain["3. Risk and Fraud Intelligence"]
        C1["Fraud Risk Agent"]
        C2["National Risk Agent"]
        C3["Conflict Investigator Agent"]
        C4["Graph Anomaly Agent"]
        C5["Chain Integrity Agent"]
    end

    subgraph TrustDomain["4. Trust Graph and AVCC"]
        D1["Trust Graph Service"]
        D2["Graph Intelligence Service"]
        D3["Forecasting Service"]
        D4["Autonomous Verification Engine"]
        D5["Command Center Telemetry"]
    end

    subgraph DecisionDomain["5. Decision Support"]
        E1["Decision Copilot Agent"]
        E2["Executive Briefing Service"]
        E3["Human in the Loop Audit"]
        E4["Dispute Simulation Lab"]
    end

    subgraph GovDomain["6. Governance and Operations"]
        F1["Model Registry Service"]
        F2["Evaluation Engine Service"]
        F3["Policy Analyzer Service"]
        F4["Provenance Service"]
        F5["Platform Learning Service"]
        F6["Cost Intelligence Service"]
        F7["Twin Evolution Service"]
        F8["Dynamic Trust Score Agent"]
        F9["Nemotron Resilience Service"]
        F10["AI Orchestrator Service"]
    end
Loading
Component Name Service Implementation Primary Function Model / Engine Trigger Event Output Destination
Legality Gatekeeper document-legality-agent.service.ts Rejects non-legal documents (invoices, images, garbage) Nemotron-4-340B Synchronous Upload Blocks upload on failure with 422
Fraud Risk Classifier fraud-risk-agent.service.ts Evaluates forgery signals, signature anomalies, risk score Nemotron-4-340B Post-Upload Async aiAssessment.fraudRisk
Conflict Investigator conflict-investigator-agent.service.ts Scans survey numbers & property IDs for double registrations Deterministic + LLM Post-Upload Async aiConflictAssessment
Cross-Examiner cross-examination-agent.service.ts Generates 5 precise forensic questions for the Notary Nemotron-4-340B Notary Review aiCrossExamination
Evidence Suggester evidence-recommendation-agent.service.ts Detects missing encumbrance certs, tax receipts, prior deeds Nemotron-4-340B Case Open evidenceRecommendation
Trust Score Engine trust-score-agent.service.ts Computes composite legal reliability index (0–100) Deterministic Rules Case Update verificationCase.trustScore
Title Chain Analyzer chain-integrity-agent.service.ts Traverses historical deeds to detect unlinked title hops Graph Algorithm + LLM Property Transfer chainIntegrityAssessment
Judicial Copilot decision-copilot-agent.service.ts Drafts legal adjudication orders for contested cases Nemotron-4-340B Judge Dashboard aiDecisionRecommendation
Anomaly Detector anomaly-agent.service.ts Identifies unusual high-frequency transactions by entity Statistical Graph AVCC Recalculate networkAnomaly
National Risk Monitor national-risk-agent.service.ts Computes regional jurisdiction risk percentiles Aggregation Engine Scheduled Job nationalTrustRating
Registration Predictor registration-predictor-agent.service.ts Estimates probability of sub-registrar deed acceptance Nemotron-3-Nano Pre-Submission aiApprovalPrediction
Cost Intelligence cost-intelligence.service.ts Tracks GPU token utilization & inference dollar costs Telemetry Engine Every LLM Call aiCostMetric
Digital Twin Emitter twin-evolution.service.ts Updates property twin state when signatures commit Event Bus On-Chain Events digitalTwinHistory

📐 Verification Proof Layer (VPL) & Section 65B Compliance

The Verification Proof Layer (VPL) (backend/src/services/vpl.service.ts) transforms traditional subjective notary reviews into deterministic, cryptographically signed verification records.

Deterministic Trust Score Calculation

The VPL evaluates verification completeness using an objective mathematical deduction model:

┌─────────────────────────────────────────────────────────────────────────────────────────────┐
│                              VPL TRUST SCORE FORMULA (0 - 100)                              │
│                                                                                             │
│   TrustScore = MAX( 0, MIN( 100,                                                            │
│       100                                                                                   │
│       - ( 4  × UnpassedChecklistItems )                                                     │
│       - ( 25 × UnresolvedTitleConflicts )                                                   │
│       - ( 8  × ResolvedTitleConflicts_AuditPenalty )                                        │
│       - ( 10 × MissingMandatoryEvidenceDocuments )                                          │
│   ))                                                                                        │
└─────────────────────────────────────────────────────────────────────────────────────────────┘

Verification Score Ranges

  • 90 – 100 (Optimal Grade): All checklist items passed, zero conflicts, complete evidence chain.
  • 70 – 89 (Conditional Grade): Minor challenges resolved with notary justification; acceptable for standard escrow.
  • < 70 (Restricted Grade): Unresolved title conflicts or missing identity proofs; Solana signature blocked.

Canonical Proof Record & On-Chain Anchoring

When a notary finalizes verification:

  1. Canonical Proof Compilation: Compiles Case ID, Document ID, Notary ID, Evidence count, Checklist completion %, Conflict resolution justifications, and Final trust score into a sorted canonical representation.
  2. SHA-256 Digest Generation: Computes vplProofHash representing the tamper-evident proof record.
  3. Solana Anchoring: The relayer executes record_signature on the smart contract with signer_role = 10 (VPL Attestation) and off_chain_cert_ref = vplProofHash.
  4. Section 65B Certificate Generation: Compiles a court-admissible PDF certificate containing the document SHA-256 hash, Solana transaction slot, notary Ed25519 public key, and IPFS CIDs.

🔐 Cryptographic Chain-of-Custody (C3) Model

flowchart LR
    subgraph Client["1. Client Browser"]
        RAW["Deed Binary Payload"] --> BROWSER_HASH["Browser SubtleCrypto SHA-256"]
    end

    subgraph Transport["2. Protected Transport"]
        BROWSER_HASH --> PAYLOAD["Multipart Payload and Client Receipt"]
    end

    subgraph Server["3. Backend API Gateway"]
        PAYLOAD --> SRV_HASH["Server Node Crypto SHA-256"]
        SRV_HASH --> CMP{"Client Hash Equals Server Hash"}
        CMP -->|Mismatch| INCIDENT["Log High Severity Security Incident"]
        CMP -->|Match| AES["AES-256-CBC Payload Encryption"]
    end

    subgraph Storage["4. Immutable Anchoring"]
        AES --> IPFS_BLOB["Pinata IPFS Encrypted Storage"]
        SRV_HASH --> SOL_PDA["Solana Document PDA Anchor"]
    end
Loading

What is Cryptographically Guaranteed vs What Depends on Authority

  • Cryptographically Guaranteed: The document was created no later than the Solana block timestamp; the document content has not changed by a single bit since hashing; the notary's public key signed the exact VPL proof record.
  • Authority Dependent: The legal competency of the executant; the physical truth of off-chain claims (e.g., whether the seller is physically alive); registry jurisdiction validity.

⛓️ Solana Smart Contract & Blockchain Layer

  • Program Name: legal_timelock
  • Program ID: EbKjjyvxck5REvVXTXuAvPDrydzKFniiGgLdKSeyfc3w
  • Framework: Anchor v0.29.0 / Rust 1.75+
  • Cluster: Solana Devnet

Blockchain Pipeline Flow

flowchart TB
    DOC["Original Legal Deed"] --> HASH["Cryptographic SHA-256 Fingerprint"]
    HASH --> SVC["Backend Blockchain Relayer Service"]
    SVC --> TX["Signed Solana Transaction"]
    TX --> PROG["Legal TimeLock Anchor Program"]
    PROG --> PDA["Program Derived Address PDA"]
    PDA --> RECORD["Immutable On-Chain Document Account"]
    RECORD --> VERIFY["Zero-Backend Direct RPC Verification"]
Loading

On-Chain Account Structures

Account Structure Allocated Space Core Purpose Stored Account Fields
DocumentRecord 116 Bytes Anchors document state and content fingerprint document_id_hash: [u8; 32]
content_hash: [u8; 32]
timestamp: i64
status: u8 (0: Pending, 1: Active, 2: Transfer, 3: Signed, 5: Disputed, 6: Revoked)
signer_count: u8
required_signers: u8
authority: Pubkey
bump: u8
SignatureRecord 113 Bytes Records notary attestation and stakeholder signatures document_record: Pubkey
signer_role: u8 (1: Notary, 2: Owner, 3: Buyer, 4: Govt, 10: VPL)
signer_pubkey: Pubkey
signed_at: i64
off_chain_cert_ref: [u8; 32] (SHA-256 of VPL proof / DSC cert)
bump: u8
OwnershipTransferRecord 145 Bytes Multi-sig title transfer workflow state machine document_record: Pubkey
transfer_id: [u8; 32]
previous_owner: Pubkey
new_owner: Pubkey
initiated_at: i64
finalized_at: i64
status: u8 (0: Pending, 1: Approved, 2: Finalized)
owner_approved: bool
buyer_approved: bool
notary_approved: bool
government_approved: bool
bump: u8

PDA Seed Derivation Schemes

PDA Account Type Seed Derivation Scheme Rust Anchor Seeds Specification
DocumentRecord ["document", SHA256(document_id)] [b"document", doc_id_hash.as_ref()]
SignatureRecord ["signature", document_pda, signer_role_byte] [b"signature", document_pda.as_ref(), &[signer_role]]
OwnershipTransferRecord ["transfer", document_pda, transfer_id_bytes] [b"transfer", document_pda.as_ref(), transfer_id.as_ref()]

On-Chain vs Off-Chain Data Separation

┌──────────────────────────────────────┬──────────────────────────────────────┐
│       ON-CHAIN LEDGER (SOLANA)       │       OFF-CHAIN STORE (POSTGRES)     │
├──────────────────────────────────────┼──────────────────────────────────────┤
│ • Document ID SHA-256 Hash           │ • Full Text Search Index             │
│ • Content SHA-256 Fingerprint        │ • Citizen Names, Emails, Phone #s    │
│ • VPL Attestation Proof Hashes       │ • Survey Numbers & Plot Dimensions   │
│ • Ed25519 Signer Public Keys         │ • IPFS CIDs & Symmetric AES Keys     │
│ • Status Enums & Slot Timestamps     │ • 31-Agent AI Execution Logs         │
│ • Multi-Sig Approval Boolean Flags   │ • Full PDF Section 65B Certificates  │
└──────────────────────────────────────┴──────────────────────────────────────┘

🔄 Multi-Signature Title Transfer State Machine

stateDiagram-v2
    [*] --> PENDING: Initiate Transfer Deed
    
    state PENDING {
        [*] --> AwaitingApprovals
        AwaitingApprovals --> OwnerApproved: Seller Signs
        AwaitingApprovals --> BuyerApproved: Buyer Signs
        AwaitingApprovals --> NotaryVerified: Notary Attests
    }

    PENDING --> APPROVED: Seller, Buyer, and Notary Signatures Recorded
    
    APPROVED --> FINALIZED: Sub-Registrar / Government Finalizes
    
    state FINALIZED {
        [*] --> OwnershipUpdated
        OwnershipUpdated --> DigitalTwinSynchronized: Digital Twin Updated
        DigitalTwinSynchronized --> DocumentExecuted: Status Set to Fully Executed
    }
    
    FINALIZED --> [*]
Loading

🧬 Digital Twin Asset Architecture

TimeLock maintains real-time Digital Twins (backend/src/services/ai/twin-evolution.service.ts) for real-world legal assets (Properties, Citizens, Notaries, Court Jurisdictions).

flowchart TD
    subgraph Physical["Physical Reality"]
        LAND["Property Parcel and Deed"]
        DSC["Digital Signature Credentials"]
    end

    subgraph Events["Event Ingestion Layer"]
        E1["Solana Anchor Event"]
        E2["VPL Notary Signature Event"]
        E3["Title Transfer Event"]
    end

    subgraph TwinCore["Digital Twin State Machine"]
        TWIN["Property Digital Twin Entity"]
        STATE["Living State: Ownership, Encumbrances, Trust Score"]
        HIST[("Append-Only Twin History Ledger")]
    end

    subgraph Consumer["Institutional Interfaces"]
        BANK["Bank Mortgage Review"]
        COURT["Judicial Dispute Portal"]
        REGISTRY["Government Land Registry"]
    end

    Physical --> Events
    Events --> TwinCore
    TWIN --- STATE
    TWIN --> HIST
    TwinCore --> Consumer
Loading

📊 Autonomous Verification Command Center (AVCC) & Trust Graph

flowchart LR
    subgraph GraphModel["AVCC Trust Graph Model"]
        N1(("Citizen Node: Seller")) ---|Owns| N2(("Property Node: Parcel"))
        N2 ---|Verified By| N3(("Notary Node: Notary"))
        N4(("Citizen Node: Buyer")) ---|Purchasing| N2
        N5(("Conflicting Node: Disputed Claim")) -.->|Anomaly Flag| N2
    end

    subgraph Analytics["Graph Intelligence Engine"]
        ALG1["Cluster Density Analysis"]
        ALG2["Spatial Boundary Check"]
        ALG3["Notary Transaction Velocity"]
    end

    subgraph Output["Judicial Operations Dashboard"]
        DASH["Judicial Dashboard: Anomaly Alerts, Recalculations"]
    end

    GraphModel --> Analytics --> Output
Loading

🛢️ Database Architecture & Data Domain Map

  • Database Engine: PostgreSQL 15 (Tested on Neon DB & local Postgres)
  • ORM: Prisma 5.15+
  • Total Models: 74 Models (Verified in backend/prisma/schema.prisma)
  • Total Enums: 10 Enums

Core Entity Relationship Diagram (Key Models)

erDiagram
    User ||--o{ Document : submits
    User ||--o{ AuditLog : generates
    Notary ||--o{ Signature : creates
    Notary ||--o{ VerificationCase : reviews
    
    Document ||--|| DocumentMetadata : contains
    Document ||--|| IpfsReference : stored_at
    Document ||--|| VerificationCase : verified_by
    Document ||--o{ Signature : signed_with
    Document ||--o{ VerificationEvent : logs
    Document ||--o{ OwnershipTransfer : transferred_via
    Document ||--|| AiAssessment : evaluated_by
    
    VerificationCase ||--o{ Evidence : includes
Loading
📂 View Complete Database Model Inventory (All 74 Models)
  1. Core Registry (3): Document, DocumentMetadata, Tenant
  2. Identity & Auth (3): User, FederatedIdentity, ApiClient
  3. Notary & Signatures (2): Notary, Signature
  4. Verification & Evidence (3): VerificationCase, VerificationEvent, Evidence
  5. AI Intelligence (15): AiAssessment, AiAssessmentHistory, AiConflictAssessment, AiConflictAssessmentHistory, AiApprovalPrediction, AiApprovalPredictionHistory, AiCrossExamination, AiCrossExaminationHistory, AiDecisionRecommendation, AiDecisionRecommendationHistory, EvidenceRecommendation, AiDecisionAudit, AiModelRegistry, ContinuousEvaluationLog, IntelligenceInsight
  6. Trust Graph & AVCC (6): TrustGraphNode, TrustGraphNodeHistory, TrustGraphEdge, TrustGraphEdgeHistory, NetworkAnomaly, NetworkAnomalyHistory
  7. Title & Ownership (6): OwnershipTransfer, OwnershipRecord, ChainIntegrityAssessment, ChainIntegrityAssessmentHistory, NationalTrustRating, NationalTrustRatingHistory
  8. Security & ABAC (7): AuditLog, SecurityIncident, PolicyRule, PolicyDelegation, PolicyEvaluationLog, PolicySimulation, SecretRotationJob
  9. Digital Twins (2): DigitalTwin, DigitalTwinHistory
  10. GovCloud & Operations (10): ComplianceRecord, ArchivalLog, VersionGovernanceRegistry, CostMetric, CapacityMetric, AiCostMetric, ExecutiveBriefing, SimulationResult, HitlAction, FeedbackLearningDataset
  11. Integration & Federation (5): ConnectorConfig, IntegrationAudit, OutboxEvent, SyncCheckpoint, SchemaRegistryEntry
  12. Billing & Utility (12): Payment, UploadReceipt, FraudScore, IpfsReference, WorkflowExecution, FeatureFlag, ScheduledJob, LineageNode, ConfigKey, DecisionProvenance, EntityRiskAssessment, EntityRiskAssessmentHistory

👥 User Roles & Access Control Matrix

User Role Target Interface Core Responsibilities & Permitted Capabilities
CITIZEN /dashboard
/register
Upload deeds, calculate browser hashes, track on-chain status, download Section 65B certificates, initiate ownership transfers.
NOTARY /notary
/notary/case/:id
Review assigned verification cases, complete VPL checklists, resolve title conflict challenges, verify evidence, sign on-chain using DSC.
JUDGE /judge AVCC judicial oversight, resolve spatial title anomalies, adjudicate contested deeds, run interactive trial simulations.
BANK_OFFICER /search
/document/:id
Review title chain integrity, verify unencumbered property status before mortgage issuance.
COURT_CLERK /document/:id Retrieve authenticated chain of custody for evidentiary submission in civil property disputes.
ADMIN /admin/*
/operations
Manage accredited notaries, monitor Solana RPC health, review audit trails, inspect GPU AI cost metrics.

🖥️ Frontend Architecture & Route Inventory

  • Framework: Next.js 16.0.10 (App Router)
  • Core: React 19.2.0, TypeScript 5.4
  • Design System: Tailwind CSS v4, shadcn/ui (New York style), Radix UI primitives
  • Visualizations & 3D: Recharts 2.12+, Three.js, @react-three/fiber
  • Form Engine: react-hook-form + zod

Route Inventory

Route Access Guard Primary Capabilities
/ Public High-impact landing page with 3D canvas animations, architecture breakdown, live statistics.
/login Public Multi-role authentication entry point.
/register CITIZEN / NOTARY Document registration wizard with client hashing and QR code issuance.
/dashboard CITIZEN Document vault, transfer initiation, status tracking.
/notary NOTARY Notary case queue, pending verifications, accreditation status.
/notary/case/[id] NOTARY Deep VPL workspace: interactive checklists, AI copilot, evidence upload, DSC token sign.
/notary/transfer/[id] NOTARY Ownership transfer deed review and multi-sig authorization.
/judge JUDGE Judicial dashboard, AVCC anomaly resolution, 11-step interactive trial demo.
/verify Public Zero-backend on-chain verifier querying Solana Devnet directly.
/document/[id] Authenticated Complete document timeline, fraud scores, digital twin status, transfer history.
/admin/system-health ADMIN Real-time health probes: Postgres, Solana RPC latency, NVIDIA AI latency, IPFS.
/admin/audit ADMIN Immutable system audit log browser with actor, IP, and entity filters.
/admin/authorities ADMIN Accredited authority registry management (Notaries, Registrars, Banks).
/admin/executive ADMIN Executive analytics, trust score distribution charts, AI assessment volumes.
/operations ADMIN / Ops Blockchain telemetry, relayer wallet balance, slot heights, twin sync metrics.
/search Institutional Multi-filter property registry search (Survey #, Owner, Document ID).

⚙️ Backend API Architecture

The backend exposes a modular REST API configured under /v1 across 16 Express routers:

Base Route Router File Primary Controller Responsibilities
/v1/auth auth.routes.ts Login, token refresh, current user profile session.
/v1/documents document.routes.ts Upload, C3 hash check, IPFS pinning, Solana anchoring, status, Section 65B PDF.
/v1/notaries notary.routes.ts Verification queue retrieval, VPL attestation submissions.
/v1/transfers transfer.routes.ts Initiate, approve (4-party multi-sig), and finalize property title transfers.
/v1/judge judge.routes.ts Case retrieval, review, 11-step interactive automated trial demo setup/execution.
/v1/ai ai.routes.ts Copilot suggestions, AI assessment regeneration, model performance telemetry.
/v1/avcc avcc.routes.ts Trust graph queries, anomaly resolution, national risk score recalculation.
/v1/authorities authority.routes.ts Register, verify, and revoke accredited institutional authorities.
/v1/payments payment.routes.ts Razorpay order creation and webhook signature validation.
/v1/system system.routes.ts Health probes (Database, Blockchain, AI, Storage), metrics, version registry.
/v1/admin admin.routes.ts Executive statistics, system health, immutable audit logs.
/v1/operations operations.routes.ts Solana node metrics, relayer balance, digital twin sync states.
/v1/governance governance.routes.ts ABAC policy management, rule simulation, policy evaluation logs.
/v1/twins twin-evolution.routes.ts Asset digital twin queries and manual state evolution triggers.
/v1/users user.routes.ts User profile retrieval and management.
/v1/interop interop-sandbox.routes.ts Legacy land registry connector and migration sandbox.

🛡️ Security Architecture & Reliability Engineering

┌─────────────────────────────────────────────────────────────────────────────────────────────┐
│                              PRODUCTION RELIABILITY CONTROLS                                │
│                                                                                             │
│  1. Request-Id Correlation: AsyncLocalStorage propagates X-Request-Id across all logs.       │
│  2. Strict Error Boundaries: BlockchainError, StorageError, and AIServiceError throw typed   │
│     exceptions with zero silent mock fallbacks.                                             │
│  3. Sliding-Window Rate Limiters:                                                            │
│     • Auth Login: 10 requests / 15 minutes                                                  │
│     • Public Verify: 20 requests / 1 minute                                                 │
│     • AI Copilot: 5 requests / 1 minute                                                     │
│  4. In-Memory Circuit Breakers: Automatic 10s cooldown and trip after 3 downstream failures.│
│  5. Client-Server Hash Comparison (C3): Halts uploads and logs SecurityIncident on mismatch.│
└─────────────────────────────────────────────────────────────────────────────────────────────┘

📦 Monorepo Directory Structure

TimeLock/
├── backend/                        # Express.js REST API & Business Logic
│   ├── prisma/
│   │   ├── schema.prisma           # 74 Database models, 10 enums
│   │   ├── seed.ts                 # Database seeder with Ed25519 notary keypairs
│   │   └── migrations/             # Historical SQL migration logs
│   ├── src/
│   │   ├── config/                 # Database, Logger, Env, Context, Error handlers
│   │   ├── controllers/            # 16 Express route controllers
│   │   ├── middleware/             # JWT Auth, Role Guard, Rate Limiter, Error handling
│   │   ├── routes/                 # 16 Express route definitions
│   │   ├── services/               # Core business services (Document, VPL, Storage, etc.)
│   │   │   ├── ai/                 # 31 Autonomous AI Agent Services (Nemotron)
│   │   │   ├── integration/        # External connector bridges
│   │   │   ├── notification/       # SMS & Email dispatchers
│   │   │   └── solana/             # TypeScript Anchor Solana Client SDK
│   │   └── validation/             # Zod input validation schemas
│   ├── tests/                      # Integration and test suites
│   ├── Dockerfile                  # Production multi-stage Docker build
│   └── package.json
├── frontend/                       # Next.js 16 App Router UI
│   ├── app/                        # App Router pages (admin, dashboard, judge, notary, verify)
│   ├── components/                 # UI components (shadcn/ui, Radix, 3D Canvas)
│   ├── context/                    # AuthContext with token persistence
│   ├── hooks/                      # Custom React hooks (useAuth, useToast)
│   ├── lib/
│   │   ├── api.ts                  # Typed API Client with Bearer token interceptor
│   │   ├── crypto.ts               # Browser SHA-256 hashing utilities
│   │   └── solana-verifier.ts      # Zero-backend direct Solana RPC deserializer
│   ├── Dockerfile                  # Next.js standalone container build
│   └── package.json
├── blockchain/                     # Solana Anchor Smart Contract & SDK
│   ├── programs/legal_timelock/    # Rust Anchor Smart Contract source code
│   │   ├── Cargo.toml
│   │   └── src/lib.rs              # Document, Signature, & Transfer instructions
│   ├── src/                        # Standalone TypeScript Blockchain Client SDK
│   ├── tests/                      # Anchor Mocha integration tests
│   ├── Anchor.toml                 # Anchor deployment configuration
│   └── Cargo.toml
├── shared/                         # Cross-monorepo TypeScript types & Zod schemas
│   ├── api-contracts.ts            # REST request & response interfaces
│   ├── enums.ts                    # Shared enums (DbDocumentStatus, DbUserRole)
│   └── validation.ts               # Shared Zod validation rules
├── deployment/
│   └── PRODUCTION_READINESS.md     # Production operations & hardening playbook
├── docker-compose.yml              # Multi-container orchestration (DB, API, Frontend)
├── .github/workflows/ci.yml        # CI/CD typechecking, linting, & build pipeline
└── README.md                       # Master technical documentation

💻 Complete Technology Stack

Layer Technologies
Frontend UI Next.js 16.0.10 (App Router), React 19.2.0, Tailwind CSS v4, Radix UI, shadcn/ui, Recharts 2.12+, Three.js, @react-three/fiber, Lucide Icons
Backend API Node.js 20+, Express.js 4.19+, TypeScript 5.4, Zod 3.23+, pdfkit, qrcode, AsyncLocalStorage
AI Intelligence NVIDIA Nemotron-4-340B-Instruct, NVIDIA Nemotron-3-Nano-30B, NVIDIA Integrate Cloud API, 31 Custom Agent Services
Blockchain Solana Devnet, Anchor Framework 0.29.0, Rust 1.75+, @solana/web3.js 1.91+, tweetnacl, bs58
Database & ORM PostgreSQL 15, Prisma ORM 5.15+ (74 Models, 10 Enums, Multi-Tenancy, ABAC)
Storage & Media Pinata IPFS Cloud Gateway, AES-256-CBC Symmetric Encryption
Payments & Integrations Razorpay Node.js SDK, n8n Automation Webhooks
DevOps & Containers Docker, Docker Compose, GitHub Actions CI/CD, pnpm 11 Workspace

🚀 Quickstart & Setup Guide

Prerequisites

  • Node.js: v20.x or higher
  • pnpm: v9.x or v11.x (npm install -g pnpm)
  • PostgreSQL: v15.x (Local instance or Neon DB)
  • Rust & Anchor: (Optional, only needed to re-compile Solana smart contract)

1. Clone & Install Dependencies

git clone https://github.com/madhavansingh/TimeLock.git
cd TimeLock
pnpm install

2. Environment Configuration

Create the environment files from the provided templates:

# Root environment file
cp .env.example .env

# Backend environment file
cp backend/.env.example backend/.env

# Frontend environment file
cp frontend/.env.example frontend/.env.local

3. Database Schema Synchronization & Seeding

Push the 74-model Prisma schema to your PostgreSQL database and seed initial test accounts:

cd backend
pnpm exec prisma db push
pnpm exec prisma db seed
cd ..

4. Launch the Development Stack

Start both the Express API and Next.js frontend concurrently:

pnpm dev

⚙️ Environment Variables Reference

Variable Name Service Purpose Required Example Default
DATABASE_URL Backend PostgreSQL connection string Yes postgresql://postgres:postgres@localhost:5432/timelock?schema=public
PORT Backend Express HTTP server port Yes 5001
JWT_SECRET Backend Secret key for signing session tokens (min 32 chars) Yes your_jwt_secret_key_minimum_32_characters_long
SOLANA_RPC_URL Backend Solana cluster RPC endpoint Yes https://api.devnet.solana.com
SOLANA_RELAYER_PRIVATE_KEY Backend Private key bytes array for authority relayer gas payments Yes [23, 142, 91, ...]
NVIDIA_API_KEY Backend NVIDIA Integrate API key for Nemotron LLM inference Yes nvapi-xxxxxxxxxxxxxxxxxxxxxxxx
NVIDIA_MODEL Backend Target foundation model name No nvidia/nemotron-4-340b-instruct
PINATA_API_KEY Backend Pinata IPFS API Key Yes your_pinata_api_key
PINATA_SECRET Backend Pinata IPFS API Secret Yes your_pinata_secret
PINATA_JWT Backend Pinata IPFS JWT Bearer Token Yes eyJhbGciOiJIUzI1Ni...
PINATA_GATEWAY Backend Dedicated IPFS gateway domain Yes silver-acceptable-bandicoot-606.mypinata.cloud
RAZORPAY_KEY_ID Backend Razorpay test key ID No rzp_test_your_key_id
RAZORPAY_KEY_SECRET Backend Razorpay test key secret No your_razorpay_secret
NEXT_PUBLIC_API_URL Frontend Base URL of the backend API Yes http://localhost:5001/v1
NEXT_PUBLIC_SOLANA_RPC_URL Frontend Solana RPC for client-side direct verifier Yes https://api.devnet.solana.com

🐳 Docker Container Orchestration

Run the entire multi-tier system stack locally using Docker Compose:

# Build and start PostgreSQL, Backend API, and Next.js Frontend
docker-compose up --build -d

# Verify all service containers are healthy
docker-compose ps

# View real-time log streams
docker-compose logs -f

# Teardown the stack
docker-compose down

🧪 Testing & Verification Suite

# 1. Typecheck the entire monorepo
pnpm typecheck

# 2. Run ESLint code quality suite
pnpm lint

# 3. Build all workspace packages (@timelock/shared, backend, frontend)
pnpm build

# 4. Run Solana SDK tests & cryptographic signature checks
cd blockchain
pnpm test

🎬 11-Step Interactive Demo Walkthrough

For evaluators and hackathon judges, TimeLock provides an automated 11-step interactive trial simulation accessible from the /judge dashboard:

┌─────────────────────────────────────────────────────────────────────────────────────────────┐
│                            11-STEP INTERACTIVE TRIAL WORKFLOW                               │
│                                                                                             │
│  Step 1: Citizen logs in and uploads Sale Deed PDF with Survey #104/A.                      │
│  Step 2: Dual-Gate check: NVIDIA Nemotron verifies legal deed classification.               │
│  Step 3: Document encrypted with AES-256 and pinned to Pinata IPFS.                         │
│  Step 4: Relayer anchors DocumentRecord PDA on Solana Devnet.                               │
│  Step 5: Verification Case & VPL workspace initialized for assigned Notary.                 │
│  Step 6: AI Conflict Investigator runs background scan; flags zero boundary conflicts.     │
│  Step 7: Notary uploads Tax Receipt & Encumbrance Certificate evidence.                     │
│  Step 8: Notary resolves cross-examination challenges; Trust Score hits 96/100.             │
│  Step 9: Notary finalizes attestation; VPL Proof Hash anchored to Solana (roleByte = 10).   │
│  Step 10: Section 65B Indian Evidence Act Certificate compiled with block slot & QR code.   │
│  Step 11: Public Verifier queries Solana Devnet directly to confirm 100% authenticity.     │
└─────────────────────────────────────────────────────────────────────────────────────────────┘

🔍 Direct Public Verification Portal (/verify)

The public verification tool (/verify) provides a trustless verification mechanism:

  1. The verifier inputs a Document ID (or scans the deed's QR code).
  2. The browser calculates the expected PDA address on Solana.
  3. The browser establishes a direct WebSocket/HTTP connection with the Solana Devnet RPC node.
  4. The raw account byte buffer is deserialized in the browser, extracting content_hash, timestamp, signer_count, and status.
  5. If the user provides a local PDF file, the browser hashes it using crypto.subtle and validates that Local SHA-256 === On-Chain content_hash.
================================================================================
✅ VERIFICATION RESULT: AUTHENTIC & IMMUTABLY ANCHORED
--------------------------------------------------------------------------------
Solana Program ID:     EbKjjyvxck5REvVXTXuAvPDrydzKFniiGgLdKSeyfc3w
Document Record PDA:   8kLw...9xQr
Solana Cluster Slot:   294810239
On-Chain Status:       FULLY_EXECUTED (Status Byte: 3)
On-Chain Content Hash: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
VPL Attestation:       VERIFIED (Notary Signatures: 1/1, Trust Score: 96/100)
================================================================================

⚠️ Known Technical Realities & Limitations

To maintain absolute technical transparency:

  1. Solana Cluster: Currently configured for Solana Devnet (api.devnet.solana.com). Relayer transactions utilize a devnet fee-payer keypair.
  2. Digital Signature Certificate (DSC) Hardware Tokens: Notary signing simulates Class-3 DSC USB token PIN authorization via cryptographic Ed25519 signing keys derived from seeded notary profiles.
  3. NVIDIA API Connectivity: The backend strictly enforces live NVIDIA API keys. If NVIDIA_API_KEY is missing or starts with mock_, the system throws an explicit AIServiceError rather than falling back to fake responses.

🗺️ Engineering Roadmap

  • v1.0 (Current Production Baseline):
    • Anchor Solana Smart Contract for Document, Signature, and Ownership Transfer PDAs.
    • 31-Service Autonomous NVIDIA Nemotron AI Intelligence Suite.
    • 74-Model PostgreSQL Database Schema with multi-tenancy & ABAC.
    • Verification Proof Layer (VPL) with dynamic mathematical trust scoring.
    • Section 65B Indian Evidence Act compliant PDF generator.
    • Client-side zero-backend Solana account deserializer.
  • v1.5 (Near-Term Infrastructure):
    • Solana Mainnet-Beta deployment with multi-region RPC failover.
    • Integration with Aadhaar eSign & National Land Records Modernization Programme (NLRMP) APIs.
    • Hardware PKCS#11 driver integration for physical DSC cryptographic USB tokens.
  • v2.0 (Long-Term Scalability):
    • Zero-Knowledge proofs (zk-SNARKs) for selective redaction of confidential commercial deed clauses.
    • Cross-chain state bridging to Ethereum and Polygon for cross-border asset recognition.

📄 License

This project is licensed under the MIT License — see the LICENSE file for details.


TimeLock / Legal TimeLock Network (LTN)
Decentralized Infrastructure for Cryptographic Truth & Legal Integrity

About

Decentralized legal document integrity network powered by Solana, cryptographic verification, and immutable audit trails.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages