CritMinChain

Solana-based Critical Minerals Traceability Platform — mine to cell pack, tamper-evident, DoD/IRA-compliant.

---

Overview

CritMinChain is an open-source traceability platform that records every custody transfer, processing step, and compliance attestation for critical minerals — from extraction at the mine face through concentration, refining, cathode production, cell manufacturing, and final pack assembly — as tamper-evident, on-chain events on the Solana blockchain. By anchoring provenance records to immutable ledger state and computing "US-origin / allied-origin content" fractions against codified policy profiles, CritMinChain gives DoD procurement officers, IRA tax-credit auditors, OEM sustainability teams, and independent verifiers a single, cryptographically verifiable source of truth for mineral supply chains.

---

Why CritMinChain?

• Critical mineral traceability is broken. The dominant record-keeping system for lithium, cobalt, nickel, manganese, and rare earth elements today is a patchwork of spreadsheets, PDF certificates, and unverifiable supplier declarations. There is no tamper-evident audit trail and no common data model across the supply chain.
• DoD needs verifiable domestic content. Defense procurement directives and the National Defense Authorization Act increasingly require proof that battery and electronics materials do not originate from Foreign Entities of Concern (FEOCs). Self-attested paperwork does not meet that bar.
• IRA Sections 45X and 30D require mineral provenance. The Inflation Reduction Act ties manufacturing tax credits and EV credits directly to the percentage of critical minerals extracted or processed in the US or in qualifying Free-Trade-Agreement countries. Without a cryptographically verifiable chain of custody, claiming these credits carries significant legal and audit risk.
• Current systems cannot be composed or automated. PDF-based certificates of analysis cannot be queried, aggregated, or fed into automated compliance engines. Every audit is a manual, months-long reconciliation exercise. CritMinChain replaces that with on-chain events that are queryable, composable, and attestable in real time.

---

Architecture

┌──────────────────────────────────────────────────────────────────────┐
│                        Data Producers                                │
│          Mines · Refiners · Cathode OEMs · Cell Manufacturers        │
└───────────────────────────────┬──────────────────────────────────────┘
                                │  signed structured data
                                ▼
┌──────────────────────────────────────────────────────────────────────┐
│               Verifiable Data Ingestion Service (VDIS)               │
│        Validates, normalizes, hashes, and submits transactions       │
└───────────────────────────────┬──────────────────────────────────────┘
                                │  Anchor instructions
                                ▼
┌──────────────────────────────────────────────────────────────────────┐
│                        Solana Programs (Anchor/Rust)                 │
│  ┌──────────────────┐  ┌───────────────────────┐  ┌───────────────┐ │
│  │  Asset Graph &   │  │  Compliance &         │  │    Entity     │ │
│  │  Provenance      │  │  Attestation Program  │  │    Registry   │ │
│  │  Program         │  │                       │  │    Program    │ │
│  └──────────────────┘  └───────────────────────┘  └───────────────┘ │
└──────────────┬──────────────────────────────┬────────────────────────┘
               │  on-chain state reads        │  attestation queries
               ▼                              ▼
┌─────────────────────────┐    ┌──────────────────────────────────────┐
│   Compliance Rules      │    │         Helius Enhanced APIs         │
│   Engine (off-chain)    │    │    Parse Tx · Tx History · Webhooks  │
└────────────┬────────────┘    └──────────────────────────────────────┘
             │
             ▼
┌──────────────────────────────────────────────────────────────────────┐
│                          Consumer Portals                            │
│   OEM Portal  ·  Auditor / Government Portal  ·  Verifier Widget    │
└──────────────────────────────────────────────────────────────────────┘

---

What's Live

The React/TypeScript frontend is deployed and connected to Solana mainnet via Helius RPC. The following portal pages and integrations are fully functional against mock domain data while Solana programs are under development:

Page	Route	Description
Command Center	/	Real-time dashboard: live Solana slot/epoch, summary metrics, supply chain flow visualization
Assets	/assets	Searchable, filterable asset tracking table with lifecycle stage and compliance status
Compliance	/compliance	Attestation records with policy profile linkage and status badges
Entities	/entities	Registry of mines, refiners, and manufacturers with on-chain identifiers
Events	/events	Chronological timeline of supply chain custody and processing events
Verifier	/verifier	Live Solana address lookup using Helius Enhanced Transaction API

Helius Integration:

• Live RPC status indicator (cluster, slot, block height, epoch) via @solana/web3.js
• Enhanced transaction parsing via Helius parseTransactions API
• Transaction history retrieval via Helius getTransactionHistory API

---

What's Planned

The following components are designed and roadmapped but not yet implemented. See ROADMAP.md for the full phased delivery plan.

Solana Programs (Anchor/Rust):

• Asset Graph & Provenance Program — PDA-based asset accounts, custody transfer instructions, provenance DAG
• Compliance & Attestation Program — policy profile validation, on-chain attestation records, content-fraction computation
• Entity Registry Program — verified entity onboarding, role assignment, stake-based reputation

Off-Chain Services:

• Verifiable Data Ingestion Service (VDIS) — ingests structured data from mines/OEMs, validates schemas, submits transactions
• Compliance Rules Engine — applies FEOC/IRA/DoD policy profiles against provenance graphs
• Oracle / Data Attestation Service — bridges third-party assay and certification data on-chain

Persistence & Infrastructure:

• PostgreSQL read model for historical queries and reporting
• IPFS metadata storage for supporting documents (certificates of analysis, assay reports)
• Redis-based event queue for ingestion pipeline

Security & Access Control:

• Role-Based Access Control (RBAC) with DoD CAC/PIV compatibility
• Multi-sig governance for Solana program upgrades
• CMMC Level 2+ compliance posture

---

Tech Stack

Layer	Technology
Blockchain	Solana (mainnet / devnet)
RPC & Enhanced APIs	Helius
Smart Contracts	Anchor / Rust (planned)
Frontend Framework	React 18 + TypeScript 5
UI Components	shadcn/ui
Styling	Tailwind CSS
Build Tool	Vite
Web3	@solana/web3.js

---

Quick Start

Prerequisites

• Node.js 18+
• npm 9+ or pnpm 8+
• A Helius API key (free tier is sufficient for development)

Installation

git clone https://github.com/zan-maker/helius-pulse-forge.git
cd helius-pulse-forge
npm install

Environment Variables

Create a .env file in the project root:

# Required — Helius API key for RPC and Enhanced API calls
VITE_HELIUS_API_KEY=your_helius_api_key_here

# Optional — override the default Solana cluster (mainnet-beta | devnet | testnet)
VITE_SOLANA_CLUSTER=mainnet-beta

Note: Never commit your .env file. It is listed in .gitignore by default.

Run the Development Server

npm run dev

The portal will be available at http://localhost:5173.

Build for Production

npm run build
npm run preview

---

Documentation

Document	Description
ROADMAP.md	Phased delivery plan with milestones and current status
ARCHITECTURE.md	Detailed system architecture and component design
SOLANA-PROGRAMS.md	Solana program specifications and instruction reference
docs/POLICY_PROFILES.md (planned)	FEOC, IRA, and DoD policy profile definitions
DATA-MODEL.md	Canonical asset, event, and entity data schemas
CONTRIBUTING.md	Contribution guidelines, development setup, and PR process

---

License

This project is licensed under the Apache License, Version 2.0. See the LICENSE file for the full text.

---

Contact

Sam D · sam@cubiczan.com

For security disclosures, please email directly rather than opening a public issue.

---

CHP Governance

This repository is hardened with the Consensus Hardening Protocol (CHP), Cubiczan's decision-governance layer for multi-agent AI systems.

Protocol Layers

• R0 Gate: All decisions must pass Solvable, Scoped, Valid, Worth_it checks
• Foundation Disclosure: 1-3 weakest assumptions, 1-2 invalidation conditions, 1 key vulnerability
• Adversarial Layer: Mandatory devil's advocate at Phase 0 and Round 3
• State Machine: EXPLORING → PROVISIONAL → PROVISIONAL_LOCK → LOCKED
• Third-Party Validation: Independent CONFIRM/REJECT before lock

Domain Configuration

• Category: Blockchain / Mining
• Foundation Threshold: 85
• CFO Accuracy Guard: Disabled

Compliance Artifacts

File	Purpose
.chp/STATE_MACHINE.md	Decision state transitions
.chp/R0_CONFIG.yaml	Domain-calibrated thresholds
.chp/ADVERSARIAL_PROMPTS.md	Standardized challenge templates
.chp/CHP_COMPLIANCE.md	Compliance tracking & audit trail

CHP Version

cognitive-mesh-orchestrator 0.1.0 | Protocol Docs

Demo