Q-Bubbles

A visualization of recorded QORT reward distributions on the Qortal blockchain. QORT reward distributions leave no on-chain record — balances simply increase with no transaction logged. The Qortal balance recorder tracks these changes, and Q-Bubbles visualizes them. Each bubble represents an address that received a reward in a given block range — sized by reward amount and coloured by account tier.

Features

• Bubble visualization — circle size scales with reward amount; role (Dev Admin, Minter Admin, Minter) adds an additional size bonus
• Colour-coded tiers — account level maps to a tier (0–5), each with a distinct colour:

  Tier	Levels	Colour
  5	9–10	Purple
  4	7–8	Green
  3	5–6	Blue
  2	3–4	Yellow
  1	1–2	Red
  0	0	Purple

• Labels — circles show F for founders, DA for Dev Admins, MA for Minter Admins, and Q for legacy QORA addresses (receiving payouts from a pre-Qortal QORA balance)
• Timeline — navigate between recorded block ranges with a slider or left/right arrow keys
• Address drawer — browse the full list of addresses in a range with role and name information
• Node details — click any circle to see balance, reward amount, registered names, and avatar
• Zoom & pan — scroll to zoom, drag the background to pan, drag circles to reposition
• Dark/light mode — toggleable, persisted to local storage

Tech Stack

• React 18 + TypeScript
• D3 v7 — force simulation physics only; React renders all SVG
• MUI v6 — UI components and theming
• TanStack Query v5 — data fetching and caching
• Vite v6 — build tooling

Getting Started

Prerequisites

• Node.js 18+
• Qortal Hub for local testing
• A running Qortal node with balanceRecorderEnabled: true in its settings (required for data to be available)

Build

npm install
npm run build

Output is written to dist/. Zip the contents of dist/ and load it in Qortal Hub's developer preview to test before publishing.

Other scripts

npm run lint         # ESLint
npm run type-check   # TypeScript type check (no emit)

Deployment

Q-Bubbles runs as a Qortal application served through the Qortal gateway. Build the project, zip the dist/ folder contents, and publish it as a QDN resource via Qortal Hub.

The app calls Qortal node API endpoints directly (e.g. /assets/balancedynamicranges, /addresses/:address) — no separate backend is required. Running the dev server outside of the Qortal environment will show a blank screen as the API endpoints will not be available.

Enabling Balance Recording

Balance recording must be enabled on your Qortal node before data will appear. Add the following to your node settings:

"balanceRecorderEnabled": true

Once enabled, your node will automatically record each reward distribution as it occurs (approximately every 1000 blocks). If the recorder was not active during a distribution, that payout will not be available — recordings cannot be retroactively captured. Recordings are stored in memory and will be lost if the node restarts.

The following settings can be adjusted in your node configuration (defaults shown):

Setting	Default	Description
balanceRecorderFrequency	20 (minutes)	How often balances are sampled
balanceRecorderCapacity	1000	Number of ranges held in memory
rewardRecordingOnly	true	Only store ranges that contain a reward distribution block — set to false to record every interval regardless
minimumBalanceRecording	1 QORT	Minimum balance change for an address to appear in a recorded range

License

MIT