████████╗██╗███╗ ███╗███████╗██╗ ██████╗ ██████╗██╗ ██╗
╚══██╔══╝██║████╗ ████║██╔════╝██║ ██╔═══██╗██╔════╝██║ ██╔╝
██║ ██║██╔████╔██║█████╗ ██║ ██║ ██║██║ █████═╝
██║ ██║██║╚██╔╝██║██╔══╝ ██║ ██║ ██║██║ ██╔═██╗
██║ ██║██║ ╚═╝ ██║███████╗███████╗╚██████╔╝╚██████╗██║ ╚██╗
╚═╝ ╚═╝╚═╝ ╚═╝╚══════╝╚══════╝ ╚═════╝ ╚═════╝╚═╝ ╚═╝
Decentralized Legal Document Notarization, Autonomous AI Verification & Solana Blockchain Title Registry
Solana Anchor Program ID: EbKjjyvxck5REvVXTXuAvPDrydzKFniiGgLdKSeyfc3w
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." │
└─────────────────────────────────────────────────────────────────────────────────────────────┘
| 🔐 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. |
- ⚡ Executive Overview
- 🎯 High-Level Feature Grid
- 💡 What is TimeLock?
- 🚩 The Problem & The TimeLock Solution
- 🏛️ System Architecture
- 🔄 End-to-End Document Lifecycle
- 🤖 Autonomous AI Intelligence Suite
- 📐 Verification Proof Layer (VPL) & Section 65B Compliance
- 🔐 Cryptographic Chain-of-Custody (C3) Model
- ⛓️ Solana Smart Contract & Blockchain Layer
- 🔄 Multi-Signature Title Transfer State Machine
- 🧬 Digital Twin Asset Architecture
- 📊 Autonomous Verification Command Center (AVCC) & Trust Graph
- 🛢️ Database Architecture & Data Domain Map
- 👥 User Roles & Access Control Matrix
- 🖥️ Frontend Architecture & Route Inventory
- ⚙️ Backend API Architecture
- 🛡️ Security Architecture & Reliability Engineering
- 📦 Monorepo Directory Structure
- 💻 Complete Technology Stack
- 🚀 Quickstart & Setup Guide
- ⚙️ Environment Variables Reference
- 🐳 Docker Container Orchestration
- 🧪 Testing & Verification Suite
- 🎬 11-Step Interactive Demo Walkthrough
- 🔍 Direct Public Verification Portal (
/verify) ⚠️ Known Technical Realities & Limitations- 🗺️ Engineering Roadmap
- 📄 License
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.
TimeLock implements a dual-layer verification protocol:
- 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.
- 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.
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 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. │
└────────────────────────────────────────────────────────┴────────────────────────────────────────────────────────┘
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
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
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.
┌─────────────────────────────────────────────────────────────────────────────────────────────┐
│ 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 │ │
│ └─────────────────────────┘ └────────────────────────┘ └────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────────────────────┘
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
| 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 |
The Verification Proof Layer (VPL) (backend/src/services/vpl.service.ts) transforms traditional subjective notary reviews into deterministic, cryptographically signed verification records.
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 ) │
│ )) │
└─────────────────────────────────────────────────────────────────────────────────────────────┘
- 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.
When a notary finalizes verification:
- 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.
- SHA-256 Digest Generation: Computes
vplProofHashrepresenting the tamper-evident proof record. - Solana Anchoring: The relayer executes
record_signatureon the smart contract withsigner_role = 10(VPL Attestation) andoff_chain_cert_ref = vplProofHash. - 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.
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
- 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.
- Program Name:
legal_timelock - Program ID:
EbKjjyvxck5REvVXTXuAvPDrydzKFniiGgLdKSeyfc3w - Framework: Anchor v0.29.0 / Rust 1.75+
- Cluster: Solana Devnet
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"]
| 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 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 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 │
└──────────────────────────────────────┴──────────────────────────────────────┘
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 --> [*]
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
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
- 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
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
📂 View Complete Database Model Inventory (All 74 Models)
- Core Registry (3):
Document,DocumentMetadata,Tenant - Identity & Auth (3):
User,FederatedIdentity,ApiClient - Notary & Signatures (2):
Notary,Signature - Verification & Evidence (3):
VerificationCase,VerificationEvent,Evidence - AI Intelligence (15):
AiAssessment,AiAssessmentHistory,AiConflictAssessment,AiConflictAssessmentHistory,AiApprovalPrediction,AiApprovalPredictionHistory,AiCrossExamination,AiCrossExaminationHistory,AiDecisionRecommendation,AiDecisionRecommendationHistory,EvidenceRecommendation,AiDecisionAudit,AiModelRegistry,ContinuousEvaluationLog,IntelligenceInsight - Trust Graph & AVCC (6):
TrustGraphNode,TrustGraphNodeHistory,TrustGraphEdge,TrustGraphEdgeHistory,NetworkAnomaly,NetworkAnomalyHistory - Title & Ownership (6):
OwnershipTransfer,OwnershipRecord,ChainIntegrityAssessment,ChainIntegrityAssessmentHistory,NationalTrustRating,NationalTrustRatingHistory - Security & ABAC (7):
AuditLog,SecurityIncident,PolicyRule,PolicyDelegation,PolicyEvaluationLog,PolicySimulation,SecretRotationJob - Digital Twins (2):
DigitalTwin,DigitalTwinHistory - GovCloud & Operations (10):
ComplianceRecord,ArchivalLog,VersionGovernanceRegistry,CostMetric,CapacityMetric,AiCostMetric,ExecutiveBriefing,SimulationResult,HitlAction,FeedbackLearningDataset - Integration & Federation (5):
ConnectorConfig,IntegrationAudit,OutboxEvent,SyncCheckpoint,SchemaRegistryEntry - Billing & Utility (12):
Payment,UploadReceipt,FraudScore,IpfsReference,WorkflowExecution,FeatureFlag,ScheduledJob,LineageNode,ConfigKey,DecisionProvenance,EntityRiskAssessment,EntityRiskAssessmentHistory
| 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. |
- 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 | 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). |
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. |
┌─────────────────────────────────────────────────────────────────────────────────────────────┐
│ 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.│
└─────────────────────────────────────────────────────────────────────────────────────────────┘
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
| 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 |
- Node.js:
v20.xor higher - pnpm:
v9.xorv11.x(npm install -g pnpm) - PostgreSQL:
v15.x(Local instance or Neon DB) - Rust & Anchor: (Optional, only needed to re-compile Solana smart contract)
git clone https://github.com/madhavansingh/TimeLock.git
cd TimeLock
pnpm installCreate 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.localPush 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 ..Start both the Express API and Next.js frontend concurrently:
pnpm dev- Frontend Web App: http://localhost:3000
- Backend REST Gateway: http://localhost:5001/v1
| 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 |
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# 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 testFor 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. │
└─────────────────────────────────────────────────────────────────────────────────────────────┘
The public verification tool (/verify) provides a trustless verification mechanism:
- The verifier inputs a
Document ID(or scans the deed's QR code). - The browser calculates the expected PDA address on Solana.
- The browser establishes a direct WebSocket/HTTP connection with the Solana Devnet RPC node.
- The raw account byte buffer is deserialized in the browser, extracting
content_hash,timestamp,signer_count, andstatus. - If the user provides a local PDF file, the browser hashes it using
crypto.subtleand validates thatLocal 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)
================================================================================
To maintain absolute technical transparency:
- Solana Cluster: Currently configured for Solana Devnet (
api.devnet.solana.com). Relayer transactions utilize a devnet fee-payer keypair. - 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.
- NVIDIA API Connectivity: The backend strictly enforces live NVIDIA API keys. If
NVIDIA_API_KEYis missing or starts withmock_, the system throws an explicitAIServiceErrorrather than falling back to fake responses.
- 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.
This project is licensed under the MIT License — see the LICENSE file for details.
Decentralized Infrastructure for Cryptographic Truth & Legal Integrity