☢ U235 Fuel Cycle

On-chain uranium fuel cycle execution system — built on the XRPL EVM Sidechain Testnet.
A fully deployed Solidity contract powering a live pipeline interface — no backend, no server, one HTML file.

🔴 Live Demo

View Dashboard →

Contract on Explorer → 0x2fed3Ced...b11Aab9

Interact with the full pipeline — inject, advance, and observe state transitions in real time.

What This Is

U235 Fuel Cycle is the execution layer for a deterministic, on-chain nuclear fuel pipeline deployed on the XRPL EVM Sidechain.

It is not a passive dashboard — it is a direct interface to a Solidity state machine governing uranium processing from mine to reactor.

The contract (FuelCycle.sol) encodes a 6-stage pipeline:

Mine → Mill → Conversion → Enrichment → Fuel Production → Reactor

Each batch is a first-class on-chain object with:

fixed quantity (oreQty)
enrichment level (enrichmentBps, integer encoded)
current stage (uint8)
lifecycle timestamps (injected / advanced)
terminal completion state

All progression is enforced on-chain — the UI cannot bypass contract rules.

No backend. No API. No middleware.

All execution flows:

UI → ethers.js → XRPL EVM → FuelCycle.sol

This guarantees:

deterministic execution (no hidden logic)
immutable batch provenance
verifiable industrial process constraints
full transparency of state transitions

In practice, this functions as a blockchain-native industrial control system, not a visualization layer.

System Model

The contract implements a discrete, forward-only state machine with enforced capacity constraints.

Each batch:

exists in exactly one stage at any time
can only advance (advanceBatch) — never revert
becomes immutable once complete

Core Invariants

stage progression is strictly monotonic (0 → 5)
completed batches are terminal and cannot be modified
capacity limits constrain throughput per stage
inactive stages reject new batch entry
enrichment is stored as basis points (no precision loss)

Storage Model

mapping(uint256 => Batch) — canonical batch registry
mapping(uint8 => Stage) — stage configuration + capacity
uint256 batchCount — global batch index

This structure ensures:

O(1) batch lookup
deterministic state transitions
minimal gas overhead per operation

ScreenRecorderProject39.mp4

Features

Blockchain

✅ Live contract deployed at 0x2fed3Ced43210a39106f49c7aA349329Fb11Aab9
✅ Full 6-stage state machine: Mine → Mill → Conversion → Enrichment → Fuel Production → Reactor
✅ All write functions with 4-step transaction lifecycle (prepare → broadcast → mine → confirm)
✅ XRPL EVM gas hardcoded — eth_estimateGas and eth_gasPrice bypassed entirely
✅ Auto chain detection — prompts MetaMask to switch to XRPL EVM Testnet if needed
✅ Real-time event feed via ethers.js provider
✅ Live block number monitoring

Dashboard

✅ Three.js animated atomic nucleus with orbiting electrons (WebGL, 60fps)
✅ Canvas 2D pipeline with hex-node stages, comet-trail particles, and flow animations
✅ Criticality monitor — arc gauge tracking reactor thermal output
✅ Live uranium commodity ticker (U3O8, UF6, SWU, UO2, CCJ, NXE)
✅ Per-metric and per-stage Chart.js sparklines updating every 250ms
✅ Radiation + waste metrics panel per stage
✅ Uranium yellow-green cyberpunk theme — scanlines, depth glow, beam animations
✅ Responsive layout (desktop + mobile)

⚡ Live Execution

System Overview — Full Pipeline Interface

On-Chain Execution — Injecting and Advancing Batches

Live Execution — Contract Interaction via MetaMask

ScreenRecorderProject44.mp4

Contract — `FuelCycle.sol`

Deployed: 0x2fed3Ced43210a39106f49c7aA349329Fb11Aab9 Network: XRPL EVM Sidechain Testnet (Chain ID: 1449000) Compiler: Solidity 0.8.24

Pipeline Stages

ID	Stage	Product	Capacity (t/hr)
0	Uranium Mine	Raw Ore (U3O8)	1,200
1	Uranium Mill	Yellow Cake (U3O8)	800
2	Conversion	UF6 (Uranium Hexafluoride)	600
3	Enrichment	Enriched UF6 (SWU)	400
4	Fuel Production	Fuel Assembly (UO2)	300
5	Nuclear Reactor	Electricity (GWe)	—

Write Functions

injectBatch(uint256 oreQty, uint8 startStage, uint256 enrichmentBps)
// Inject a new ore batch into the pipeline at any stage (0–4).
// enrichmentBps in basis points — 350 = 3.50% U-235.
// onlyOwner. Checks capacity, active stage, zero qty.

advanceBatch(uint256 batchId)
// Advance a batch to the next stage.
// onlyOwner. Emits BatchAdvanced + BatchCompleted at final stage.

setStageCapacity(uint8 stageId, uint256 capacityPerHour)
// Update tonnes/hr capacity for a stage.
// onlyOwner. Emits StageCapacitySet with old + new values.

toggleStage(uint8 stageId)
// Toggle a stage active/inactive. Blocks new injections at that stage.
// onlyOwner. Does not affect in-flight batches.

transferOwnership(address newOwner)
// Transfer contract ownership. Reverts on zero address.
// onlyOwner. Emits OwnershipTransferred.

Read Functions

getStage(uint8 stageId)
→ (string name, string product, uint256 capacityPerHour, uint256 totalProcessed, bool active)

getBatch(uint256 batchId)
→ (uint256 oreQty, uint8 currentStage, uint256 enrichmentBps,
   address injectedBy, uint256 injectedAt, uint256 lastAdvancedAt, bool complete)

getBatchStage(uint256 batchId) → uint8
getTotalProcessed() → uint256
batchCount() → uint256
totalOreInjected() → uint256
owner() → address

Solidity Patterns Used

Pattern	Implementation
Custom errors	`NotOwner`, `InvalidStage`, `CapacityExceeded`, `BatchAlreadyComplete` — 3x cheaper than `require` strings
Indexed events	`BatchInjected`, `BatchAdvanced`, `BatchCompleted`, `StageToggled` — 3 indexed params max per event
Basis points	`enrichmentBps` = 350 for 3.50% U-235 — integer encoding avoids EVM floating point
`onlyOwner` modifier	Manual impl — no OpenZeppelin, minimises attack surface
Capacity enforcement	`CapacityExceeded(stageId, requested, capacity)` passes all 3 values for full caller context

Tech Stack

Layer	Technology
Blockchain	XRPL EVM Sidechain Testnet
Smart Contract	Solidity 0.8.24, Foundry
Web3 Provider	Ethers.js v5 (CDN)
3D Visualisation	Three.js r128 (CDN)
Charts	Chart.js 4.4.1 (CDN)
Frontend	Vanilla HTML/CSS/JS — zero build step
Fonts	Orbitron, Rajdhani (Google Fonts)
Hosting	Vercel

Project Structure

u235-fuel-cycle/
├── src/
│   └── FuelCycle.sol          ← Core contract — 6-stage state machine
├── script/
│   └── Deploy.s.sol           ← Foundry deploy script
├── test/
│   └── FuelCycle.t.sol        ← Unit + fuzz test suite (20+ cases)
├── frontend/
│   └── index.html             ← Self-contained pipeline dashboard SPA
├── foundry.toml               ← Hardcoded gas config for XRPL EVM
├── .env.example               ← Environment template
└── README.md

Running Locally

No install required:

git clone https://github.com/yourusername/u235-fuel-cycle
cd u235-fuel-cycle
open frontend/index.html
# or: python3 -m http.server 8080

The simulation runs without a wallet. Connect MetaMask for on-chain interaction.

Build & Test

# Install forge-std (no git init needed)
mkdir -p lib && git clone https://github.com/foundry-rs/forge-std lib/forge-std

# Build
forge build

# Run all tests
forge test -vv

# Fuzz tests
forge test --fuzz-runs 1000 -vv

# Gas snapshot
forge snapshot

Deploy to XRPL EVM Testnet

⚠️ XRPL EVM does not implement eth_estimateGas or eth_gasPrice. Both ethers.js and Foundry call these automatically — the commands below bypass both entirely.

Step 1 — Hard reset (mandatory before every redeploy):

rm -rf out/ cache/ broadcast/
forge clean

Step 2 — Set key and deploy:

export PRIVATE_KEY=your_private_key_here

forge create src/FuelCycle.sol:FuelCycle \
  --rpc-url https://rpc.testnet.xrplevm.org \
  --private-key $PRIVATE_KEY \
  --legacy \
  --broadcast

Step 3 — Get your deployed address:

# Printed directly in forge create output — look for "Deployed to:"

Step 4 — Wire up the frontend:

// frontend/index.html — line 1 of <script>
var CONTRACT = "0xYOUR_DEPLOYED_ADDRESS_HERE";

Step 5 — Deploy frontend:

surge frontend/

Connecting MetaMask

Field	Value
Network Name	XRPL EVM Testnet
RPC URL	`https://rpc.testnet.xrplevm.org`
Chain ID	`1449000`
Symbol	`XRP`
Explorer	`https://explorer.testnet.xrplevm.org`

Get free testnet XRP: https://faucet.testnet.xrplevm.org

XRPL EVM Known Issues

Issue	Cause	Fix
MetaMask Internal JSON-RPC error	`eth_estimateGas` called automatically by ethers.js	Frontend hardcodes `gasLimit: 300000, gasPrice: 100 gwei` on every tx
Forge simulation fails	`eth_gasPrice` unsupported	Use `forge create` not `forge script` — no simulation phase
Tx rejected (wrong type)	EIP-1559 Type 2 not supported	`--legacy` flag required on all forge commands
Wrong bytecode deployed	Stale `out/` cache	Always `rm -rf out/ cache/` before redeploy
Stage 0 / Batch 0 silently rejected	Falsy `0` in JS input validation	Frontend uses `=== ""` check, never `!value`
Insufficient fee error	Minimum global fee = 30,000,000,000,000,000 wei	Gas price must be ≥ 100 gwei

Cast Test Commands

export CONTRACT=0x2fed3Ced43210a39106f49c7aA349329Fb11Aab9
export RPC=https://rpc.testnet.xrplevm.org

# Read stage 0
cast call $CONTRACT "getStage(uint8)" 0 --rpc-url $RPC

# Read batch count
cast call $CONTRACT "batchCount()" --rpc-url $RPC

# Inject a batch (500t ore, stage 0, 350bps = 3.5% U-235)
cast send $CONTRACT "injectBatch(uint256,uint8,uint256)" 500 0 350 \
  --rpc-url $RPC --private-key $PRIVATE_KEY \
  --legacy --gas-limit 300000 --gas-price 100000000000

# Advance batch 0 to next stage
cast send $CONTRACT "advanceBatch(uint256)" 0 \
  --rpc-url $RPC --private-key $PRIVATE_KEY \
  --legacy --gas-limit 300000 --gas-price 100000000000

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

License

MIT — see LICENSE

Name		Name	Last commit message	Last commit date
Latest commit History 11 Commits
.github		.github
script		script
src		src
test		test
.env.example		.env.example
.gitignore		.gitignore
README.md		README.md
U235 Fuel Cycle — Case Study.md		U235 Fuel Cycle — Case Study.md
foundry.toml		foundry.toml
index.html		index.html

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

☢ U235 Fuel Cycle

🔴 Live Demo

What This Is

System Model

Core Invariants

Storage Model

Features

Blockchain

Dashboard

⚡ Live Execution

System Overview — Full Pipeline Interface

On-Chain Execution — Injecting and Advancing Batches

Live Execution — Contract Interaction via MetaMask

Contract — FuelCycle.sol

Pipeline Stages

Write Functions

Read Functions

Solidity Patterns Used

Tech Stack

Project Structure

Running Locally

Build & Test

Deploy to XRPL EVM Testnet

Connecting MetaMask

XRPL EVM Known Issues

Cast Test Commands

On-Chain Systems Portfolio

License

About

Topics

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Sponsor this project

Uh oh!

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Contract — `FuelCycle.sol`

Packages