DatumX

Deterministic release-governance protocol for AI-transformed industrial datasets, with canonical payload enforcement, no-branch lineage, validator consensus, and auditor-controlled finalization on XRPL EVM Testnet.

🔴 Live Demo

Surface	Link
Dashboard	datumx.vercel.app
ValidationModule	0xD60B...2baf
ProjectRouter	0x04dC...1637
Network	XRPL EVM Testnet (1449000)

DatumX is live on XRPL EVM Testnet with a canonical V5 deployment, recorded lineage proofs for 1->2, 3->4, 5->6, and 7->8, and threshold restoration back to 3 / 6667 / 7000 after every fast-path smoke exercise.

---

What This Is

DatumX is a Solidity protocol and inspection console for proving that AI-transformed exploration datasets are decision-grade before they move into technical review, targeting, and resource-definition workflows. It does not treat transformed data as a file-storage problem. It treats each release as a governed analytical unit with a canonical payload, explicit lifecycle, deterministic lineage, validator review state, confidence aggregation, and auditor-controlled closure.

The protocol is built around a strict submission boundary. Project-specific adapters normalize typed payloads into canonical dataset inputs. The router is the single submission entry point. The registry records the release and blocks duplicate hashes. The lineage graph enforces finalized-parent progression with no branching. The validation module accepts validator-only reviews, computes approval/confidence thresholds, and only permits auditor finalization once the dataset is actually eligible.

DatumX is also intentionally honest about trust boundaries. There is no hidden backend adjudicating release legitimacy, no off-chain relay pretending to be canonical truth, and no UI state that outranks the chain. The React/Vite console exists to inspect protocol posture, lineage, validation state, and XRPL evidence, not to invent release status that the contracts did not produce.

Features

Blockchain

• Canonical dataset registration through ProjectRouter.submitDataset(...) and DatasetRegistry.submitCanonicalDataset(...)

• Typed AdapterPayload normalization with project-key binding checks and deterministic content hashing

• Duplicate dataset rejection by canonical content hash

• Finalized-parent lineage enforcement with exact-next-stage progression and explicit no-branch constraints

• Validator-only review submission through ValidationModule.submitReview(...)

• Auditor-only finalization through ValidationModule.finalizeDataset(...)

• Threshold-controlled approval using minValidatorCount, minApprovalRatioBps, and minConfidenceBps

• Full XRPL EVM deployment manifest with contract addresses, deploy tx hashes, post-deploy role grants, and explorer proof links

Dashboard

• Resource Integrity Console built in React/Vite with live MetaMask network detection and XRPL explorer linking

• Lineage-first inspection surfaces that show release progression instead of isolated dataset cards

• Validation views aligned to protocol truth: approvals, rejections, aggregate confidence, thresholds, and finalization posture

• Audit timeline and proof-board presentation tied to recorded XRPL transactions

• Mock-enriched presentation that stays explicitly bounded by live protocol reads and deployment manifests

• Premium technical UI language tuned for industrial review rather than speculative token dashboard aesthetics

War Diary

Date	Intent	Technical Change	Outcome
2026-04-02	Establish first full DatumX deployment on XRPL EVM testnet	V4.5 deploy completed but left the protocol with a weaker adapter boundary and less disciplined lineage semantics	Archived as superseded in deployments/archive/xrpl-testnet-v4.json
2026-04-02	Correct the submission boundary	V5 redeployed the full graph around typed AdapterPayload, cleaner adapter normalization, and stricter release semantics	Canonical deployment recorded in deployments/xrpl-testnet.json
2026-04-03	Prove fast-path lineage on live XRPL	Thresholds lowered to 1 / 6667 / 7000, root 3 and child 4 submitted/finalized, then thresholds restored	First admin fast-path lineage proof completed and restored to 3 / 6667 / 7000
2026-04-04	Re-run against the release-candidate posture	Fresh root 5 and child 6 exercised end to end on the same V5 contracts	Second XRPL lineage proof completed with restored thresholds
2026-04-04	Verify contracts on Blockscout	Standard JSON bundles submitted in bulk, then retried one-by-one for selected contracts	Submissions accepted but verification remained stuck in the explorer queue
2026-04-17	Debug failing submitReview execution	Added simulation, custom-error decoding, and structured preflight checks to reveal ReviewAlreadySubmitted() on finalized DS-006	Review writes now fail loudly before broadcast with the real reason
2026-04-18	Preserve a fresh explorer-backed lineage proof after the review-debug pass	Fast-path smoke run created datasets 7 and 8, verified getParentDatasetId(8) = 7, then restored thresholds	Third recorded fast-path lineage proof completed successfully

---

⚡ Live Execution

Governance & Threshold Controls

Workflow Design & Research

Overview Dashboard

Validation Queue

ScreenRecorderProject70.mp4

Audit Trail

ScreenRecorderProject71.mp4

Dataset Registry

ScreenRecorderProject68.mp4

Console Walkthrough

ScreenRecorderProject67.mp4

Project Administration

ScreenRecorderProject69.mp4

---

Deployment Ledger

Role	V5 Address / Deploy Tx	Archived V4.5 Address	Recorded Network Deploys
Access control (DrillProofAccess)	0x47AA...c2e5 / 0xfc5f...4924	0x137d...c7af	2
Project registry (ProjectRegistry)	0x238f...6687 / 0x6ffc...bbd3	0x6c11...b1f1	2
Dataset registry (DatasetRegistry)	0x0Fa0...5e0B / 0x80a7...519a	0xeaef...fc98	2
Validation (ValidationModule)	0xD60B...2baf / 0xf09b...d0be	0xc553...722f	2
Submission router (ProjectRouter)	0x04dC...1637 / 0x1ebd...d620	0x7078...a2bb	2
Adapter (DuckCreekAdapter)	0x431B...0254 / 0xf40c...b2ac	0x72b4...f252	2
Adapter (ShirleyCentralAdapter)	0xD54e...6797 / 0x1490...fbca	0x9ec2...ab27	2
Adapter (ShirleyEastAdapter)	0xCB04...b993 / 0xf129...93eb	0xf27f...e580	2

Manifest sources:

• canonical V5: deployments/xrpl-testnet.json
• archived V4.5: deployments/archive/xrpl-testnet-v4.json

Contract / Protocol Section

Current deployment posture

Item	Value
Compiler	Solidity 0.8.24
Foundry profile	via_ir = true, evm_version = "cancun"
Deployment method	forge script script/Deploy.s.sol:DeployScript --broadcast --legacy
Chain	XRPL EVM Testnet
Chain ID	1449000
Deployer	0x31A826bB9D5F6087d94CDA31945C1234d061b788
Validator thresholds	minValidatorCount=3, minApprovalRatioBps=6667, minConfidenceBps=7000

Pipeline stages

ID	Stage	Protocol Product	Capacity / Gate
1	RAW_SCAN_BATCH	Root historical scan package	Requires canonical payload, unique content hash, active project
2	EXTRACTED_TRACES	Digitized trace extraction release	Requires finalized parent and exact-next-stage transition
3	INTERPRETED_INTERVALS	Interpreted mineralized interval package	Same-project, no-branch lineage rule continues
4	COMPOSITE_STATISTICS	Aggregated statistics / release summary	Must remain on the deterministic lineage spine
5	DRILL_TARGET_PACKAGE	Decision-grade targeting package	Terminal analytical output in the current enum set

Core modules

Contract	Responsibility	Why it exists
DrillProofAccess	Centralized role and pause authority	Keeps admin, project, validator, auditor, and pauser separation explicit
ProjectRegistry	Project metadata, adapter binding, active/inactive state	Prevents invalid project/adaptor pairings from reaching the router
ProjectRouter	Single submission entry point	Forces all submissions through adapter normalization before registration
DatasetRegistry	Canonical record storage, duplicate blocking, lineage enforcement	Makes release identity and lifecycle explicit on-chain
ValidationModule	Review intake, aggregation, threshold checks, finalization gate	Separates validator judgment from auditor closure
DuckCreekAdapter, ShirleyCentralAdapter, ShirleyEastAdapter	Project-specific normalization	Keeps local payload rules out of the shared registry core

Primary write surface

Function	Purpose	Constraints	Events
ProjectRouter.submitDataset(bytes32,AdapterPayload,string,bytes32)	Routes a project submission into adapter normalization and canonical dataset registration.	Reverts if the protocol is paused, the project is inactive, the adapter is missing, or the adapter response is inconsistent.	DatasetSubmissionRouted, followed by DatasetRecorded if registry insert succeeds.
DatasetRegistry.setRouter(address)	Sets the single authorized router address for canonical submissions.	Admin only, nonzero address, protocol must be active.	RouterConfigured
DatasetRegistry.setValidationModule(address)	Sets the only contract allowed to mutate review state and finalization.	Admin only, nonzero address, protocol must be active.	ValidationModuleConfigured
ProjectRegistry.registerProject(bytes32,ProjectMetadata)	Creates a new project binding and adapter mapping.	Default admin or project admin only, unique key, nonempty name, nonzero adapter, adapter must declare the same expected project key.	ProjectRegistered
ProjectRegistry.updateProject(bytes32,ProjectMetadata)	Updates project metadata while preserving project identity.	Project must already exist, adapter binding must still match the project key.	ProjectUpdated
ProjectRegistry.setProjectActive(bytes32,bool)	Toggles whether a project can accept new submissions.	Project manager only, project must exist.	ProjectUpdated
ValidationModule.submitReview(uint256,bool,uint16,string)	Records a validator decision and updates aggregate approval/confidence state.	Validator role only, confidence must be <= 10000, URI required, one review per validator per dataset, dataset cannot already be approved, rejected, or finalized.	ReviewSubmitted, plus DatasetStatusUpdated via the registry
ValidationModule.finalizeDataset(uint256)	Closes an approved dataset and marks it finalized in the registry.	Auditor role only, dataset must still satisfy threshold math at finalization time.	DatasetStatusUpdated, DatasetFinalized
ValidationModule.setThresholds(ValidationThresholds)	Adjusts validator-count, approval-ratio, and confidence thresholds.	Default admin only, protocol active, values must stay inside 0..10000 bounds and validator count cannot be zero.	ThresholdsUpdated
DrillProofAccess.pause() / unpause()	Suspends or resumes protocol write paths.	PAUSER_ROLE only.	OpenZeppelin Paused / Unpaused events plus downstream write-path rejections

Primary read surface

Function	Return signature	Why it matters
DatasetRegistry.getDataset(uint256)	returns (DatasetRecord memory)	Canonical release state: lifecycle, counts, submitter, timestamps, and parent hash
DatasetRegistry.getDatasetIdByHash(bytes32)	returns (uint256)	Maps canonical content identity back to dataset ID
DatasetRegistry.getProjectDatasetIds(bytes32)	returns (uint256[] memory)	Enumerates all releases recorded under a project key
DatasetRegistry.getParentDatasetId(uint256)	returns (uint256)	Proves finalized-parent lineage on-chain
DatasetRegistry.getChildDatasetIds(uint256)	returns (uint256[] memory)	Proves no-branch child progression and descendant linkage
DatasetRegistry.datasetExists(uint256)	returns (bool)	Fast existence guard for frontend and tooling preflight
ValidationModule.getReview(uint256,address)	returns (Review memory)	Lets the UI preflight duplicate-review and reviewer-state cases
ValidationModule.getReviewers(uint256)	returns (address[] memory)	Exposes who has already participated in consensus
ValidationModule.getThresholds()	returns (ValidationThresholds memory)	Reads the live approval/finalization posture
ValidationModule.isFinalizationEligible(uint256)	returns (bool)	Shows whether a dataset can be closed now, not just whether it is approved
ProjectRegistry.getProject(bytes32)	returns (ProjectMetadata memory)	Reads adapter binding and active state for a project
ProjectRegistry.getProjectKeys()	returns (bytes32[] memory)	Enumerates registered project keys

Solidity patterns

Pattern	Status	DatumX usage
Custom errors	Used	Unauthorized, DuplicateDataset, ReviewAlreadySubmitted, LineageBranchNotAllowed, FinalizationNotReady, and other explicit revert states keep error paths compact and auditable
Indexed events	Used	ProjectRegistered, DatasetRecorded, DatasetStatusUpdated, DatasetFinalized, and ReviewSubmitted all emit protocol evidence for audit and analytics
Basis points	Used	Confidence and threshold math is integer-encoded in basis points (0..10000) to avoid floating-point ambiguity
Role-based access	Used	DEFAULT_ADMIN_ROLE, PROJECT_ADMIN_ROLE, VALIDATOR_ROLE, AUDITOR_ROLE, PAUSER_ROLE
onlyOwner	Not used	DatumX uses OpenZeppelin AccessControl instead of a single-owner pattern
Capacity enforcement	Used	Duplicate hash rejection, one-validator-one-review, finalized-parent requirement, and no-branch lineage all revert at the contract layer
Upgradeability	Not used	The current deployment is direct and immutable; operational changes are made by redeploying versioned contract sets

Architecture

flowchart LR
  A["Project adapter<br/>typed AdapterPayload"] --> B["ProjectRouter"]
  B --> C["DatasetRegistry"]
  C --> D["DatasetGraph lineage"]
  C --> E["ValidationModule"]
  E --> F["APPROVED / REJECTED"]
  F --> G["Auditor finalization"]
  G --> H["FINALIZED release"]

Loading

• Adapters normalize project-specific payload rules into canonical dataset inputs.
• The router is the only public dataset submission surface.
• The registry owns release identity, lifecycle state, duplicate blocking, and parent-child discipline.
• The validation module owns review intake, threshold math, and finalization eligibility.
• The console exposes this state without pretending to be the source of truth.

Tech Stack

Layer	Tooling	Why it is here
Chain	XRPL EVM Testnet	Real EVM execution environment with fast iterative deployment and public explorer links
Smart contracts	Solidity 0.8.24	Core protocol, adapters, roles, and validation logic
Contract framework	Foundry	Build, test, deploy, smoke, and verification artifact generation
Access control	OpenZeppelin AccessControl + Pausable	Explicit role separation and protocol-wide emergency stop
Frontend	React 19 + Vite + TypeScript	Resource Integrity Console and wallet UX
Wallet / chain client	viem + MetaMask	Direct browser wallet flow, chain switching, explorer link generation
Styling	Tailwind + app-specific token palette	Consistent DatumX console identity
Documentation export	python-docx	Printable executive brief and case-study outputs

Repository Structure

DatumX/
|-- contracts/ -> protocol core, adapters, interfaces, hashing/events/errors libraries
|-- test/ -> Foundry unit and lifecycle coverage
|-- script/ -> deploy, XRPL smoke, explorer verification, and document export tooling
|-- deployments/ -> canonical manifests, logs, archived versions, verification bundles
|-- src/ -> React console, wallet hooks, protocol client, dashboard surfaces
|-- docs/ -> case study, executive brief source, screenshots, companion narrative artifacts
|-- output/doc/ -> generated DOCX briefing outputs
|-- public/ -> static brand assets and icons

Local Run

npm install
npm run dev

The frontend is fully static. There is no backend service to start for the console itself.

Build, Test, and Verify

npm run lint
npm run test
npm run build
npm run contracts:build
npm run contracts:test
npm run verify
npm run contracts:smoke:xrpl

Deployment Runbook

DatumX uses a multi-contract deployment graph with post-deploy role grants and project registration, so the authoritative path is forge script, not forge create.

Reset stale artifacts

rm -rf out cache broadcast

Export deploy credentials

export RPC_URL=https://rpc.testnet.xrplevm.org/
export PRIVATE_KEY=0xYOUR_TESTNET_PRIVATE_KEY
export VALIDATOR_ADDRESS_1=0x83c4aE468d41aDc1D9E2109ccD4833050Fd19ec0
export VALIDATOR_ADDRESS_2=0xF96125A22C9C4670A166fabfed0c0B12bE73c1B2
export VALIDATOR_ADDRESS_3=0xA34f17AD281bC2F585AB929c8054a789e9B6fBD8

Deploy the full protocol graph

forge script script/Deploy.s.sol:DeployScript \
  --rpc-url $RPC_URL \
  --broadcast \
  --legacy

Frontend wiring

After deployment, update the centralized frontend contract config and manifests:

1. Write the deployed addresses into deployments/xrpl-testnet.json.
2. Mirror any canonical address changes into the frontend config used by the live protocol client.
3. Re-run npm run contracts:smoke:xrpl and npm run verify.
4. Redeploy the frontend once the manifest and proof links are correct.

Vercel deploy

vercel --prod

MetaMask Config

Field	Value	Notes
Network name	XRPL EVM Testnet	Matches the console's expected network label
RPC URL	https://rpc.testnet.xrplevm.org/	Same RPC used by deployment and smoke tooling
Chain ID	1449000	Hard requirement
Currency symbol	XRP	Native gas token
Explorer URL	https://explorer.testnet.xrplevm.org	Used for tx and address proof links
Transaction mode	Legacy	DatumX XRPL flows use --legacy for deploy/smoke compatibility

XRPL EVM Known Issues

• eth_estimateGas is not a safe assumption for DatumX's XRPL flows, so the smoke runner uses fixed gas and does not depend on estimation.
• eth_gasPrice can be inconsistent enough that fee headroom should be explicit rather than inferred.
• --legacy is required for the deployment and smoke path documented in this repo.
• Stale out/, cache/, or broadcast/ artifacts can pollute deployment truth and verification bundles if not cleaned before a fresh deploy.
• Frontend truth alignment matters: JavaScript falsy handling must not silently collapse 0, empty strings, and missing chain state into the same branch.
• Underpriced transactions can fail; the repo's XRPL operational notes assume meaningful headroom rather than minimum-fee optimism.
• Blockscout verification acceptance does not imply completed verification; the queue can accept submissions and still fail to mark the contracts verified in a useful window.

XRPL Proof Links

Live lineage proofs

• 1->2 canonical V5 proof: root submit 0xc38e...a6e8, root finalize 0x57fd...6705, child submit 0x8a8a...8bdd, child finalize 0x5777...5c0f
• 3->4 admin fast-path: lower 0x56b7...433f, root finalize 0xbc66...d20d, child finalize 0x1360...be85, restore 0x99a6...48fa
• 5->6 release-candidate run: lower 0x319f...2744, root finalize 0xcada...9796, child finalize 0x47b2...742b, restore 0xa8bd...3d5d
• 7->8 follow-up proof run: lower 0x588b...b6b7, root submit 0xbb55...560d, root finalize 0x230f...83ad, child submit 0xb291...d3a6, child finalize 0xaac1...8db8, restore 0x81b0...8d88

Proof artifacts

• deployment manifest: deployments/xrpl-testnet.json
• deployment log: deployments/xrpl-testnet.md
• verification notes: deployments/xrpl-testnet-verification.md
• proof board: docs/screenshots/xrpl-followup-proof-board.png
• proof board source: docs/screenshots/xrpl-followup-proof.html

Documentation Set

• executive brief source: docs/datumx-executive-technical-brief.md
• long-form protocol case study: docs/datumx-case-study.md
• generated DOCX exports:
  • output/doc/DatumX-Executive-Technical-Brief.docx
  • output/doc/DatumX-Case-Study.docx

Noble Pains Uranium Alignment

The protocol is well suited to uranium exploration programs where digitization quality is no longer the only gating issue. In that operating environment, the real risk is not whether AI can extract signal from historical logs, but whether the transformed release that reaches technical review can still be defended. DatumX answers that risk with typed payload normalization, deterministic lineage, validator consensus, explicit thresholds, and auditor-only closure. That is a governance layer for decision-grade exploration data, not a generic blockchain wrapper around files.

On-Chain Systems Portfolio

Project	Description	Status
ZUC Mine Command Center	On-chain uranium mining operations dashboard — real-time reserve tracking, miner registry, and contract interaction via a fully frontend-driven command interface	✅ Live
U235 Fuel Cycle	Nuclear fuel cycle pipeline — uranium ore to enriched fuel rod, deterministic multi-stage processing with full on-chain traceability	✅ Live
ISR Network	Intelligence surveillance reconnaissance system — on-chain asset tracking, mission lifecycle state machine, and role-based operator control	✅ Live
Dark Matter Farm	DeFi yield protocol — experimental high-convexity farming system with custom reward mechanics and on-chain state-driven emissions	✅ Live
COHR LAB	Semiconductor fabrication lifecycle system — deterministic on-chain state machine tracking irreversible production stages from crystal growth to final pigtail with full auditability	✅ Live

---

Author's Note

DatumX Protocol is built by ZRT. The point of the system is not to sound protocol-native. The point is to make transformed industrial data defensible under scrutiny. That is why the core decisions are conservative and explicit: typed adapter payloads, no-branch lineage, finalized-parent requirements, validator-only reviews, auditor-only finalization, and XRPL-aware operational tooling that assumes legacy gas and imperfect RPC behavior instead of wishing those constraints away.

License

MIT - see LICENSE