EVID-DGC — Blockchain Evidence & Digital Chain of Custody

📊 Live Repository Statistics

📌 Current Status — August 2026

Component	Status
Core Platform (Phase 1)	✅ Live — demo
Blockchain Integration (Phase 2)	✅ Live on Polygon Amoy testnet
IPFS Storage (Phase 2)	✅ Live via Pinata
Forensic Lab (Phase 3)	🔶 In development — foundation shipped
3D Evidence Viewer (Phase 3)	🔶 Viewer live (STL asset shipped), advanced controls planned
AI-Assisted Analysis (Phase 3)	🔬 Research phase
Mainnet Deployment (Phase 4)	🔴 Planned — currently Amoy only

Important

All blockchain records are on the Polygon Amoy testnet. Production/mainnet anchoring is the Phase 4 target, not yet available.

🚨 The Problem

Broken chain of custody in traditional evidence room handling
No public auditability — evidence integrity only checkable by the court
Missing multi-hash verification (MD5, SHA-1, SHA-256)
No immutability — files can be silently modified

💡 Our Solution

8-role RBAC + ABAC enforcement applies to every action
Blockchain anchoring on Polygon Amoy — write the evidence hash, immutably
IPFS pinning via Pinata — full file, permanent storage
Forensic Lab — generates multiple hashes per evidence, highlights tamper
3D evidence model — an STL digital twin of the evidence document

📦 Core Features

Phase 1 — Core System ✅ Deployed

8 roles: Admin, Officer, Investigator, Analyst, Evidence Manager, Reviewer, Judge, Public
Evidence create → register → store → transfer → verify lifecycle
Audit logging of all custody events
Real-time dashboard via Socket.IO
Subordinate re-upload anti-tamper via multi-hash comparison

Phase 2 — Blockchain & IPFS ✅ Deployed (Amoy)

EVID-DGC.sol — anchorEvidence, verifyEvidence, getEvidenceHistory
Won the chain (deployed address in Deployment section)
Files pinned to Pinata IPFS, hash recorded on-chain

Phase 3 — Forensic Lab & 3D Evidence 🔶 In Progress

Forensic analyzer: MD5 / SHA-1 / SHA-256, entropy, file-type detection
3D Evidence Viewer — STL model rendered in-app (asset: assets/evidence-cube.stl)
Forensic report generator — planned
AI-based evidence triage — research

🧰 Technology Stack

Technology Stack Maturity

Area	Maturity
Frontend / Backend	✅ ✅ Mature — full page toolkit
Blockchain + IPFS	✅ Operational — Amoy testnet
3D evidence & AI	🟡 Prototype / roadmap
Mainnet	❌ Not deployed

🏗️ Architecture

flowchart TD
    subgraph Client
        A[Browser] --> B[Dashboard / Public Pages]
    end
    subgraph Server
        C[Express API] --> D[(PostgreSQL / Supabase)]
        C --> E[Pinata IPFS]
        C --> F[Polygon Amoy node]
    end
    subgraph Contract
        F --> G[EVID-DGC contract]
    end
    B -->|REST + Socket.IO| C
    B -->|3D viewer| H[THREE.js/STL]

🧑‍⚖️ Role-Based Access Control (RBAC)

Role	Permissions
Admin	Full system control, user/role management
Officer	Capture & register new evidence, upload files
Investigator	Access case data, annotate evidence
Analyst	Run forensic analysis on evidence
Evidence Manager	Manage evidence lifecycle & retention
Reviewer	Verify chain of custody, approve evidence
Judge	Review finalized reports, certify for trial
Public	Verify evidence integrity (public dashboard)

ABAC rules enforce context: only the owning investigator/team may transfer evidence; Public role is restricted to verification endpoints.

⛓️ Blockchain & Evidence Integrity

// contracts/EVID_DGC.sol (simplified)
contract EVID_DGC {
    mapping(bytes32 => EvidenceRecord) public records;

    function anchorEvidence(
        string memory evidenceId,
        bytes32 evidenceHash,
        address officer
    ) external returns (bytes32) {
        record.evidenceHash = evidenceHash;  // SHA-256 of file
        emit EvidenceAnchored(evidenceId, evidenceHash, block.timestamp);
        return recordHash;
    }
}

Deployed Address (Polygon Amoy):

EVID-DGC: 0x39453ED8CF79Fe56150fe1E8348e75894e3dD9e3
Explorer : https://amoy.polygonscan.com/address/0x39453ED8CF79Fe56150fe1E8348e75894e3dD9e3

Caution

This is a testnet contract. Do not use for production evidence until Phase 4 mainnet deploy.

On-Chain Evidence Flow

sequenceDiagram
    autonumber
    participant O as Officer
    participant S as Server
    participant C as EVID-DGC (Amoy)
    participant I as Pinata IPFS
    O->>S: Upload file + metadata
    S->>I: Pin file → CID
    S->>C: anchorEvidence(evidenceId, keccak(file))
    C-->>S: emit EvidenceAnchored { block }
    S-->>O: Evidence ID + tx hash

📁 IPFS Storage

Files pinned on Pinata IPFS at upload time — permanent & deduplicated
CID stored in PostgreSQL, hash stored on-chain
Public-dashboard verification compares stored file hash vs. on-chain hash

🗄️ Database Schema (PostgreSQL via Supabase)

erDiagram
    USERS ||--o{ EVIDENCE : submits
    USERS ||--o{ AUDIT_LOG : performs
    EVIDENCE {
        uuid id PK
        string case_number
        string description
        string file_hash "SHA-256"
        string ipfs_cid
        string onchain_tx
        string custody_actor
    }
    AUDIT_LOG {
        uuid id PK
        uuid evidence_id FK
        uuid actor_id FK
        string action
        timestamp time
    }

Full schema: complete-database-setup-fixed.sql (repo root).

🔬 Evidence Workflow — Digital Chain of Custody

flowchart LR
    C[Evidence Capture] --> R[Registration]
    R --> L[Lab Analysis]
    L --> A[Anchoring on Amoy]
    A --> V[Verification by Reviewer]
    V --> T[Transfer / Trial]
    T --> D[Disposal or Archive]

Step	Actor	Output
Capture	Officer	File + metadata
Register	Evidence Manager	Evidence ID
Analyze	Analyst	Forensic report
Anchor	System	Hash 0x + txid
Verify	Reviewer / Public	Certified copy

🧊 3D Evidence Viewer (Phase 3, in progress)

A genuine 3D model asset is included: assets/evidence-cube.stl. The interactive viewer (view-evidence3d.html) renders it with notes/rotation; miniature interactive application elements (e.g., adjustable lighting) are planned.

🧪 Testing

Unit / Integration (Jest, Phase 1-2)

npm test          # unit + integration
npm run test:e2e  # Playwright E2E (planned configuration in progress)

What's covered

Evidence CRUD multi-hash detection
Auth + RBAC role gating
IPFS & chain mocks

🚀 Quick Start

1. Prerequisites

Node.js 18+, npm
Supabase project (or docker run postgres)
(Optional) Pinata account + JWT

2. Clone & install

git clone https://github.com/Gooichand/blockchain-evidence.git
cd blockchain-evidence
npm install

3. Configure environment

cp .env.example .env

Variable	Example
`SUPABASE_URL`	`https://xyz.supabase.co`
`SUPABASE_ANON_KEY`	`eyJ...`
`JWT_SECRET`	any (use pwgen)
`POLYGON_RPC_URL`	`https://rpc-amoy.polygon.technology`
`PRIVATE_KEY`	wallet key (Amoy test faucet)
`CONTRACT_ADDRESS`	`0x39453ED8CF79Fe56150fe1E8348e75894e3dD9e3`
`PINATA_JWT`	your Pinata JWT

4. Run locally

npm run dev
# http://localhost:3000

Seed the DB first with complete-database-setup-fixed.sql (creates 8 roles & demo users).

🌐 Public Evidence Verification (No Login)

Anyone can enter an Evidence ID, SHA-256 hash, or on-chain tx hash on the Public Dashboard and receive VERIFIED ✅ / TAMPERED ❌ instantly — cross-checked against PostgreSQL, the Amoy ledger, and IPFS.

📚 Documentation

docs/API.md – REST endpoints
docs/DEPLOYMENT.md – Render + PostgreSQL setup
docs/SECURITY.md – security model & checklist
PHASES.md – phases, roadmap, status
CONTRIBUTING.md – how to contribute

📄 Deployment — Render One-Click

render.yaml provisions the web service + managed PostgreSQL.

🤝 Contributing

See CONTRIBUTING.md — issues welcomed, PRs reviewed. Help wanted tags: 3d-viewer, ai-analysis, mainnet.

📝 License

🙌 Acknowledgments

Pinata for IPFS pinning
Polygon Amoy testnet
Render hosting
Supabase PostgreSQL + Auth
GitHub Actions for CI status badge

⚖️ EVID-DGC — Immutably anchored. Forever provable.

⭐ If you find this project useful, **give it a star**!

Name		Name	Last commit message	Last commit date
.github		.github
.vscode		.vscode
artifacts		artifacts
assets		assets
build/contracts		build/contracts
cache		cache
config		config
contracts		contracts
controllers		controllers
docs		docs
middleware		middleware
migrations		migrations
public		public
routes		routes
scripts		scripts
services		services
tests		tests
utils		utils
.env.example		.env.example
.gitignore		.gitignore
.prettierignore		.prettierignore
.prettierrc		.prettierrc
CITATION.cff		CITATION.cff
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
PHASES.md		PHASES.md
README.md		README.md
SECURITY.md		SECURITY.md
check-admin.js		check-admin.js
complete-database-setup-fixed.sql		complete-database-setup-fixed.sql
contributor-setup.js		contributor-setup.js
eslint.config.js		eslint.config.js
hardhat.config.js		hardhat.config.js
jest.config.js		jest.config.js
package-lock.json		package-lock.json
package.json		package.json
puppeteer-config.json		puppeteer-config.json
render.yaml		render.yaml
security-hardening.sql		security-hardening.sql
server.err		server.err
server.js		server.js
start-server.ps1		start-server.ps1

Latest commit

History

Folders and files

Repository files navigation