RiJoL95 Explorer

A responsive, production-oriented universal blockchain explorer.
Live blocks, transactions, accounts, token holdings, transfers, market data, and network health across six EVM chains.

Important

RiJoL95 Explorer is English-only and read-only. It never asks for a seed phrase or private key and does not sign or submit transactions.

📸 Screenshots

🟡 BNB Smart Chain transactions	🟣 Polygon blocks

📚 Table of contents

About
Features
Supported networks
Quick start
RPC and environment configuration
Files you will usually edit
Repository structure
Architecture and data integrity
Testing
Deployment and hosting
Domain setup
Windows EXE / desktop app
Coming soon
Security, contributing, and license
Sponsor RiJoL95 Explorer
Crypto donations

🌐 About

RiJoL95 Explorer is a modern multi-chain explorer built with TypeScript, React, vinext, Vite, and the Cloudflare Workers runtime. One normalized adapter layer keeps blockchain-provider details outside the UI, so another provider or blockchain family can be added without rebuilding every page.

The included deployment supports:

Ethereum — chain ID 1
BNB Smart Chain — chain ID 56
Polygon — chain ID 137
Base — chain ID 8453
Arbitrum One — chain ID 42161
Gnosis — chain ID 100

Every chain has its own logo and accent color. The interface includes the Dark and Midnight themes while keeping chain-specific colors readable in both.

✨ Features

📊 Live overview with block height, cadence, gas price, throughput, block load, and recent activity
🧱 Full block list and block details with producer, reviewed builder tag, gas utilization, size, base fee, and exact burnt fees
🔁 Recent bounded transaction list and full transaction details with decoded methods, from/to, native value, available USD estimate, and receipt-derived fee
🔎 Universal search for block height, block hash, transaction hash, and EVM address
👤 Ethereum Accounts directory with 25 addresses per page and live native balances
💼 Address detail tabs for Transactions, Transfers, and Holdings
🪙 Native and ERC-20 holdings with token logos, balances, available live prices, and priced USD totals
📡 Live page-one updates without full-page refresh; age labels continue ticking in real time
📋 Copy controls for block numbers, hashes, transactions, addresses, and token contracts
🏷️ Conservative chain-scoped entity labels and exact reviewed Ethereum builder signatures
🌍 Six-logo accessible network selector that also works with a collapsed sidebar
🎨 Dark + Midnight themes with server-rendered preference and no theme flash
📱 Responsive desktop, tablet, and mobile layouts
🧩 Explicit adapter interfaces for EVM, Bitcoin-like, and Solana-like providers
🛡️ Loading, retry, error, empty, unsupported, reduced-motion, and keyboard-accessible states

⛓️ Supported networks

Network	Chain ID	Native asset	RPC environment variable	Default accent
🔷 Ethereum	`1`	ETH	`ETHEREUM_RPC_URLS`	Ethereum blue
🟡 BNB Smart Chain	`56`	BNB	`BNB_RPC_URLS`	BNB yellow
🟣 Polygon	`137`	POL	`POLYGON_RPC_URLS`	Polygon purple
🔵 Base	`8453`	ETH	`BASE_RPC_URLS`	Base blue
🔹 Arbitrum One	`42161`	ETH	`ARBITRUM_RPC_URLS`	Arbitrum cyan
🟢 Gnosis	`100`	xDAI	`GNOSIS_RPC_URLS`	Gnosis green

The repository keeps the current custom public HTTPS RPC pools supplied for this project. Public endpoints are best-effort and have no uptime or quota guarantee; production operators should replace them with monitored endpoints they control.

🚀 Quick start

Requirements

Node.js 22.13.0 or newer
npm 10 or newer
Git
Outbound HTTPS access to the configured RPC, portfolio, and market providers

Windows — Command Prompt

git clone https://github.com/rijol95-web3/rijol95-explorer.git
cd rijol95-explorer
npm ci
copy /Y .env.example .env.local
npm run dev

Windows — PowerShell

git clone https://github.com/rijol95-web3/rijol95-explorer.git
Set-Location rijol95-explorer
npm ci
Copy-Item .env.example .env.local -Force
npm run dev

Ubuntu / Debian

Install a supported Node.js release first, then run:

git clone https://github.com/rijol95-web3/rijol95-explorer.git
cd rijol95-explorer
npm ci
cp .env.example .env.local
npm run dev

Open http://localhost:3000.

No hosting file, hosting account, project ID, database, or storage binding is required for local development. The application reads chain data from the server-side RPC settings in .env.local.

Local production-mode check

npm run build
npm run start

npm run start is useful for local acceptance testing. The verified deployment target for this repository is a Cloudflare Worker-compatible runtime.

🔌 RPC and environment configuration

Recommended method: edit `.env.local`

Copy .env.example to .env.local.
Replace one or more comma-separated RPC pools.
Restart the development server.

Example:

ETHEREUM_RPC_URLS=https://your-primary-eth-rpc.example,https://your-backup-eth-rpc.example
BNB_RPC_URLS=https://your-bnb-rpc.example
POLYGON_RPC_URLS=https://your-polygon-rpc.example
BASE_RPC_URLS=https://your-base-rpc.example
ARBITRUM_RPC_URLS=https://your-arbitrum-rpc.example
GNOSIS_RPC_URLS=https://your-gnosis-rpc.example

Each configured value replaces that network's built-in pool; it is not appended. URLs are tried in order. A pool accepts 1–20 unique http:// or https:// endpoints. wss:// endpoints are intentionally unsupported because the server transport uses HTTP fetch.

Before normal requests are sent, every endpoint is checked with eth_chainId. A wrong-chain provider is rejected. Retryable timeout, rate-limit, network, and provider failures rotate to another endpoint.

Caution

Keep paid RPC URLs and API keys server-side. Never use a NEXT_PUBLIC_ prefix, commit .env.local, or put secrets directly in frontend components.

Where the current custom RPCs live

Editable example: .env.example
Local private override: .env.local — recommended for each operator
Built-in fallback source: lib/explorer/networks.ts

For a public fork, prefer changing .env.local or hosting environment variables. Edit lib/explorer/networks.ts only when you intentionally want to change the defaults shipped to every new installation.

Shared RPC controls

Variable	Default	Allowed range	Purpose
`RPC_TIMEOUT_MS`	`8000`	`1000–60000`	Timeout for one endpoint attempt
`RPC_MAX_ATTEMPTS`	`3`	`1–10`	Maximum endpoints tried per retryable call
`RPC_MAX_CONCURRENCY`	`8`	`1–32`	Per-operation concurrency ceiling
`RPC_ACTIVITY_SCAN_BLOCKS`	`32`	`1–256`	Recent address activity range
`RPC_TRANSACTION_SCAN_BLOCKS`	`256`	`1–1024`	Recent transaction scan range
`RPC_OVERVIEW_SAMPLE_BLOCKS`	`8`	`2–32`	Dashboard timing sample

Any shared value can be overridden per network, for example BASE_RPC_TIMEOUT_MS or POLYGON_RPC_MAX_ATTEMPTS.

Indexed holdings and token prices

Purpose	File or environment setting
Ethereum portfolio API	`ETHEREUM_PORTFOLIO_API_URL`
BNB portfolio API/key	`BNB_PORTFOLIO_API_URL`, `BNB_PORTFOLIO_API_KEY`
Polygon portfolio API	`POLYGON_PORTFOLIO_API_URL`
Base portfolio API	`BASE_PORTFOLIO_API_URL`
Arbitrum portfolio API	`ARBITRUM_PORTFOLIO_API_URL`
Gnosis portfolio API	`GNOSIS_PORTFOLIO_API_URL`
Portfolio timeout	`PORTFOLIO_TIMEOUT_MS`
Market-provider timeout	`TOKEN_MARKET_TIMEOUT_MS`
Reviewed visible token catalog	`lib/explorer/curated-token-catalog.ts`
Bundled token logos	`public/token-icons/`

An empty per-network portfolio URL disables indexed holdings for that network. Unknown or unpriced tokens remain visible with Price unavailable; the explorer never invents $0.00 for a missing quote.

Replacing all six networks

Advanced operators can set EXPLORER_NETWORKS_JSON. A non-empty value replaces the entire built-in registry with 1–32 EVM definitions.

[
  {
    "id": "my-chain",
    "name": "My Chain",
    "family": "evm",
    "chainId": "12345",
    "rpcUrls": ["https://rpc.my-chain.example"],
    "nativeCurrency": { "name": "My Coin", "symbol": "MYC", "decimals": 18 },
    "blockTimeMs": 2000
  }
]

Custom networks use the EVM adapter, but do not automatically receive built-in portfolio discovery, Accounts data, curated assets, or a custom logo/accent. Add those capabilities explicitly before advertising them.

🛠️ Files you will usually edit

What you want to change	Edit this file
Private/local RPC pools	`.env.local`
Public example RPC pools	`.env.example`
Built-in networks and default RPCs	`lib/explorer/networks.ts`
Reviewed tokens, contracts, decimals, market IDs	`lib/explorer/curated-token-catalog.ts`
Token images	`public/token-icons/`
Main RiJoL95 logo	`public/rijol95-icon.png`
Overview blockchain banner	`public/blockchain-network-banner.png`
Social preview image	`public/og.png`
Chain logos and accent colors	`app/explorer/network-brand.tsx`
Navigation, topbar, sidebar, footer	`app/explorer/shell.tsx`, `app/explorer/info-dock.tsx`
Pages and detail views	`app/explorer/views.tsx`
Block/transaction tables	`app/explorer/tables.tsx`
Themes and global responsive design	`app/globals.css`, `app/explorer/theme.ts`
App title and social metadata	`app/layout.tsx`
EVM RPC normalization	`lib/explorer/evm-adapter.ts`
Provider failover/transport limits	`lib/explorer/json-rpc.ts`
Portfolio-provider parsing	`lib/explorer/portfolio-provider.ts`
Market-provider parsing/cache	`lib/explorer/token-market-provider.ts`
Ordered Ethereum Accounts dataset	`lib/explorer/ethereum-accounts.json`

🗂️ Repository structure

rijol95-explorer/
├── app/
│   ├── api/
│   │   ├── explorer/route.ts        # normalized explorer API
│   │   └── token-assets/route.ts    # reviewed market-data API
│   ├── explorer/
│   │   ├── shell.tsx                # persistent application shell
│   │   ├── views.tsx                # overview/list/detail pages
│   │   ├── tables.tsx               # block/transaction tables
│   │   ├── network-selector.tsx      # accessible chain picker
│   │   ├── network-brand.tsx         # chain logos and colors
│   │   ├── token-assets.tsx          # curated assets view
│   │   ├── accounts.tsx              # Ethereum Accounts view
│   │   └── ...                       # UI helpers, routing, themes, prices
│   ├── ExplorerApp.tsx               # client routing + network state
│   ├── globals.css                   # complete responsive visual system
│   └── layout.tsx                    # metadata + SSR preferences
├── lib/explorer/
│   ├── contracts.ts                  # chain adapter interfaces
│   ├── types.ts                      # provider-independent records
│   ├── networks.ts                   # built-ins + environment parsing
│   ├── evm-adapter.ts                # EVM data normalization
│   ├── json-rpc.ts                   # bounded JSON-RPC + failover
│   ├── portfolio-provider.ts         # indexed holdings providers
│   ├── token-market-provider.ts      # market quotes and caching
│   ├── curated-token-catalog.ts      # reviewed visible token registry
│   └── ethereum-accounts.json        # ordered Accounts dataset
├── public/                            # app icon, banner, OG, token logos
├── docs/screenshots/                  # README product screenshots
├── docs/funding/                      # sanitized donation QR images
├── tests/                             # route, UI, adapter, provider tests
├── worker/index.ts                    # Cloudflare Worker entry
├── .env.example                       # documented server configuration
├── vite.config.ts                     # hosting-neutral vinext + Worker build
├── package.json                       # scripts and dependencies
└── README.md

Generated folders such as node_modules/, dist/, .next/, .vinext/, .wrangler/, work/, and outputs/ are ignored by Git and should not be committed.

🧠 Architecture and data integrity

Responsive UI
   ↓
Normalized server APIs
   ↓
Network registry + ChainAdapter
   ├── EVM JSON-RPC failover pool
   ├── bounded blocks / transactions / logs
   ├── indexed holdings provider
   └── reviewed token catalog → CoinGecko → CoinPaprika fallback

Important behavior:

Integer block heights, balances, gas values, and fees remain precise.
Native USD conversion uses exact base-unit arithmetic rather than floating-point balance conversion.
Transaction fees appear only when receipt data exists.
Unknown entities remain unlabeled; no fake wallet names or builder identities are generated.
Address transactions and transfers are bounded recent views, not a complete historical index.
Public RPC and portfolio providers can rate-limit, omit data, or fail. Failover improves best-effort availability but is not an SLA.
The UI never exposes configured RPC URLs, API keys, or raw provider response shapes.

The current implementation is EVM-ready. lib/explorer/contracts.ts also defines clear extension boundaries for Bitcoin-like and Solana-like adapters, but those families still require real providers, honest pagination, and indexed address-history strategies.

✅ Testing

npm run lint
npm run typecheck
npm test

npm test builds the production application and verifies public routes, normalized API contracts, RPC failover, address transfers, exact monetary arithmetic, two-theme behavior, responsive overview cards, trusted entity enrichment, portfolio providers, token-market providers, and readable transaction methods.

Before a pull request, also inspect changed screens at desktop, tablet, and mobile widths.

☁️ Deployment and hosting

Your hosting

RiJoL95 Explorer does not contain a project-specific hosting ID and does not require a hosting configuration file for local use. Choose a hosting provider that supports the application server/Worker runtime and server-side environment variables.

After deploying, your provider gives you a URL such as:

https://your-hosting.example

Use that URL as your hosting URL. Replace the example address in your desktop wrapper, documentation, social links, or custom-domain configuration.

There is no hosting ID to paste into vite.config.ts. Put deployment-specific values in your provider's private dashboard:

Value	Where it belongs
RPC URLs and provider API keys	Server-side environment variables
Hosting project or Worker name	Hosting provider project settings
Custom domain	Hosting provider's Domains or Routes screen
Access/deploy token	Hosting secret store or CI secret

Keep hosting project IDs, access tokens, account identifiers, RPC credentials, and provider secrets out of this repository. The placeholder https://your-hosting.example means the public URL assigned by your own hosting provider; it is not a required file or dependency.

Recommended: Cloudflare Workers

This repository already uses the Cloudflare Vite plugin and emits a Worker-compatible server bundle.

npm ci
npm run lint
npm run typecheck
npm test
npx wrangler login
npx wrangler deploy --keep-vars

Set RPC URLs and provider keys in the Cloudflare dashboard under your Worker's Settings → Variables and Secrets. Do not commit production secrets. The generated Worker configuration is created during npm run build/npm test and is used by Wrangler deployment. The --keep-vars flag preserves dashboard-managed variables that are not declared in the generated Wrangler configuration.

Official references:

GitHub

GitHub is ideal for source code, issues, releases, and CI. Push the repository with:

git init
git add .
git commit -m "Initial RiJoL95 Explorer release"
git branch -M main
git remote add origin https://github.com/rijol95-web3/rijol95-explorer.git
git push -u origin main

Warning

GitHub Pages alone is not a compatible host for this project because RiJoL95 Explorer requires server API routes and server-side provider configuration. A static-only deployment would break live chain data or expose secrets. Use GitHub for the repository and a Worker/server platform for the running application.

VPS or another host

The host must support a long-running server/Worker-compatible runtime, outbound HTTPS, runtime environment variables, and HTTPS termination. Build and test first:

npm ci
npm run build
npm run start

Treat npm run start as an acceptance server unless your chosen platform has explicitly validated vinext's runtime requirements. Put a production process manager and an HTTPS reverse proxy in front only after load, restart, health-check, and shutdown behavior have been tested. Cloudflare Workers remains the verified target.

🌍 Domain setup

Cloudflare custom domain

Add your domain to an active Cloudflare zone.
Deploy the Worker.
Open Cloudflare Dashboard → Workers & Pages → your Worker.
Open Settings → Domains & Routes.
Select Add → Custom Domain.
Enter a hostname such as explorer.example.com.
Wait for Cloudflare to create DNS and issue the TLS certificate.

Cloudflare requires that the chosen hostname is not already occupied by a conflicting CNAME. HTTPS certificate management is automatic for a valid Custom Domain.

For another hosting provider, follow that provider's domain screen and add the exact CNAME, A, or validation records it supplies. Do not guess DNS targets.

🖥️ Windows EXE / desktop app

The current repository is a full-stack web application and does not directly generate an .exe. The safest desktop option is a thin Electron wrapper that loads a deployed HTTPS RiJoL95 Explorer. The backend remains hosted, so the desktop app still needs Internet access.

Create a separate Electron wrapper

npm init electron-app@latest rijol95-explorer-desktop
cd rijol95-explorer-desktop

In the wrapper's main process, configure a hardened window and load your deployed explorer:

const { app, BrowserWindow } = require("electron");

function createWindow() {
  const window = new BrowserWindow({
    width: 1440,
    height: 900,
    webPreferences: {
      contextIsolation: true,
      nodeIntegration: false,
      sandbox: true,
    },
  });

  window.loadURL("https://your-explorer-domain.example");
}

app.whenReady().then(createWindow);

Then create the distributable:

npm run make

Electron Forge writes distributables under out/make/. On Windows, configure an appropriate Windows maker and code-sign the installer before public distribution. Unsigned executables can trigger operating-system trust warnings.

Bundling the complete Worker/server backend inside one offline EXE is a separate engineering project. It needs a managed local server lifecycle, port protection, health checks, logs, updates, provider secrets, and platform-specific packaging; it is intentionally not claimed as an existing feature here.

🛣️ Coming soon

These roadmap items are planned, not currently available:

Feature	Planned purpose
🐋 Whale Alert	Track and highlight unusually large native/token movements
🚨 Scam Token Report	Community reporting and reviewed warning signals for suspicious assets
🤖 AI Chat	Natural-language help for understanding blocks, transactions, addresses, and explorer data
👛 Connect Wallet	Optional wallet connection with explicit permissions and safe network awareness

Security-sensitive roadmap features will require separate threat modeling, privacy review, abuse controls, and clear user consent before release.

🔐 Security, contributing, and license

Read SECURITY.md before reporting a vulnerability.
Read CONTRIBUTING.md before opening a large change.
Follow the Code of Conduct.
Released under the MIT License.

Never publish seed phrases, private keys, paid RPC credentials, API keys, personal address datasets, or captured provider responses containing secrets.

💖 Sponsor RiJoL95 Explorer

If RiJoL95 Explorer helps your project, research, or community, you can support continued open-source development through GitHub Sponsors.

💖 Sponsor RiJoL95 on GitHub

Crypto donations

If you prefer an on-chain contribution, scan the QR code for the intended network. Always verify the network and the full address shown in your wallet before sending. Cryptocurrency transfers are irreversible.

Ethereum	BNB Smart Chain	Bitcoin
Solana	Tron	Thank you ❤️ Your support helps maintain RiJoL95 Explorer.

Copyable public donation addresses

Network	Address
Ethereum	`0x8c07b29745c94b6a52F7e8dF0eA3FDDF76591Abc`
BNB Smart Chain	`0x8c07b29745c94b6a52F7e8dF0eA3FDDF76591Abc`
Bitcoin	`bc1qgxlrtr3n7jk05j239ld048fh2le7tyexgkls80`
Solana	`Eu7meF2wTxtgiSaMZFPAFkMEwQSGGAQqAPLuvSpmUeYz`
Tron	`TBVbEJDGZLRAL9WkxXk5Dgo23S7obsYM8W`

Made with RiJoL95 ❤️ for the open source Blockchain comunity and developers

Name		Name	Last commit message	Last commit date
.github		.github
app		app
docs		docs
lib/explorer		lib/explorer
public		public
tests		tests
worker		worker
.env.example		.env.example
.gitattributes		.gitattributes
.gitignore		.gitignore
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
eslint.config.mjs		eslint.config.mjs
next-env.d.ts		next-env.d.ts
next.config.ts		next.config.ts
package-lock.json		package-lock.json
package.json		package.json
proxy.ts		proxy.ts
tsconfig.json		tsconfig.json
vite.config.ts		vite.config.ts

Uh oh!

Latest commit

History

Folders and files

Repository files navigation