A picture backed
by an accounting.

One chain. Two views.

A node-local C++ preprocessor reads blocks through Bitcoin Core's REST API and records UTXO creation and spending. The same change stream drives both the film and the historical index used by the explorer.

The renderer produces raw RGB24 frames over TCP. FFmpeg encodes them into HEVC. Separately, utxo_history builds creation/spend records. The cloud publisher packages the video as HLS and the history as row-indexed shards. A Worker serves the UI, video and queries from private R2 storage. Public viewing does not require the rendering Mac or the Bitcoin node to be online.

Sources: preprocessor · renderer · cloud service

Keep what can be verified.

The incremental history updater may place its small index arrays after the enlarged record region. Readers use the header offsets; they must not assume a fixed section order. History records retain amounts and lifecycle heights, not full outpoints. Transaction lookup is a separate, potentially ambiguous operation.

File sizes are measured decimal GB from the September 10 release. Record count means historical outputs, including spent ones, rather than currently unspent outputs. Zero-value outputs are retained by checkpoint accounting but have no positive logarithmic Y coordinate in the plot.

Sources: BLK framing · UTX3 · history layout · shard reader

Position, density, change.

Four choices for the time axis

The published profile uses 105,000-block epochs and a 0.5 current share. Two epochs fit before compression is necessary. At each subsequent boundary, 120 blocks interpolate the old and new maps with smoothstep t²(3−2t). Coordinates are clamped and truncated to integer pixels; the renderer, HUD and explorer inverse mapping must agree.

The Y axis has three zones

Values increase upward. The central 100-satoshi to 10,000-BTC region uses a logarithmic scale. The 1–100 satoshi zone takes one third of its ordinary logarithmic height. The 10,000–100,000 BTC zone takes 15% of a central decade's height. Values at or above 100,000 BTC share the top row. The plot is [0,10,3720,2072] inside a 3840×2160 frame.

Persistent density and exact rebuilding

Persistent weight is max(1, |amount| / 5 BTC) with amount weighting enabled. A 100 BTC output contributes 20; a small output contributes 1. Double-precision pixel densities are updated when outputs appear or are spent. In epoch modes, an alive ledger grouped by creation height and Y row lets the renderer rebuild every surviving contribution at the exact destination pixel. This avoids the old mismatch between spreading density across columns and later removing it from a single column.

Every frame of a smooth transition rebuilds from that ledger. Diagnostics count missing ledger entries and dropped decrements. Successful release runs reported zero for both. This is accounting consistency of the rendered density; it is separate from lossy video compression and transaction-identification ambiguity.

Colour and transients

DensityToImage maps log(density + 30) between density 1 and 500 onto palette indices 0–255. Non-positive density becomes black. The base palette is turbo; rows at or above the 10 BTC threshold use a tail blended toward warm white. Both palettes share their lower entries. The optional amount colour floor is disabled in this edition.

Flash emphasis is based on the actual total BTC changed at a pixel, normalized to 5 BTC, with no minimum per output. This prevents huge numbers of tiny outputs from looking like a high-value transfer. Distant activity uses larger marks and longer fades; amount-weighted old spends can become stars. Near the creation edge, highlights remain small to protect the new-column detail. Flash pixels follow their creation column during a slide.

Orange flow marks summarize a rolling ten-block creation window, separated from the current column by 15 pixels. Large creations receive a square-root value boost when weighting is enabled. These marks are drawn and restored without changing stored density. The HUD stays at the left and synchronizes its axis mapper every frame.

Optional experiments

The denomination filter selects a fixed list of common CoinJoin-like amounts; it is a heuristic, not proof that a transaction is a CoinJoin. Audio synthesis converts spending activity into mono float32 impulses across five age-related frequency bands, with at most 64 concurrent events. Both are disabled in the published film.

Sources: axis mapper · density and ledger · colour transfer · flash history

Keep the small points.

4:4:4 retains a chroma sample at every pixel, which matters for isolated coloured points. It is still lossy HEVC; neither the master nor the preview images are exact RGB data. 4:2:0 is easier to decode on many devices but reduces colour resolution. The guide uses short 1080p H.264/VP9 previews for lighter loading.

Exact-RGB lossless experiments compared decoded frame hashes and pixels but produced a roughly 312 GB full-chain file. That oversized rendition was retired; CRF 21 is the retained delivery choice. Native 8K configurations exist, but this edition is 4K. An 8K RGB24 frame is about 99.5 MB; copies, TCP throughput, encoding and storage all matter. Apple VideoToolbox H.264 could not open the tested 8K session, and HEVC VideoToolbox did not provide the required native 4:4:4 path.

Long renders record into MKV, then remux into MP4 with faststart. A normal MP4 interrupted before its trailer can lack the moov index. MKV reduces that operational risk. Remuxing changes the container without re-encoding the pictures.

Evidence: retained master · measured release report · retired artifacts

The film lives in the cloud.

The production explorer at utxo.aiception.ai reaches a Cloudflare proxy, which forwards to the video Worker. The Worker serves the UI and allowlisted media from the private utxo-video R2 bucket. Viewing does not involve a local tunnel.

The original single 84 GB R2 object was uploaded as a multipart object. Measured ranged reads were too slow for reliable seeking. The production stream instead uses ten-second fragmented MP4 HLS segments, uploaded individually and cached independently at the edge. Segment packaging copies the existing HEVC bytes. This is not a new render or a transcode.

Video, history routing, UI assets and metadata switch together through an immutable release descriptor. Existing HLS segments and base history shards can be shared between releases. The latest stream is /hls/v3/media.m3u8; the legacy /video.mp4 aliases remain compatibility routes. A UI-only release can advance the site namespace without changing video or history.

The Worker validates single HTTP byte ranges, supports GET/HEAD and CORS preflight, adds CSP and content-type protections, and uses versioned cache keys for query results. Its in-memory per-isolate token buckets limit pixel queries (8/s, burst 20), txid resolution (0.5/s, burst 2), and range queries (30/s, burst 60). They are best-effort abuse controls, not globally coordinated quotas. R2 object names stay private behind an allowlist.

The public guide itself is plain static HTML, CSS, JavaScript and curated media served by GitHub Pages. Fonts are self-hosted. It does not fetch the full video or history index. The full explorer targets desktop displays; HEVC 4:4:4 support depends on the browser and platform. A mobile rendition experiment was stopped and is not a supported playback path.

Sources: request handling · release descriptor · public-domain proxy

A pixel is a query.

Coordinates are native image pixels, not scaled screen coordinates. The explorer accounts for letterboxing, inverts the active X/Y maps, and asks for outputs in that creation-height and amount range at the selected block. It can also show previously spent outputs and their later fate.

Paused seeks target the midpoint of a frame to avoid a native-player rounding edge that could display the preceding frame at a near-boundary timestamp. The ending's 300 hold/fade frames do not extend the blockchain's height range.

Sources: queries · txid matching · explorer UI

Keep the past. Append the future.

The September 10 update extended the release from block 964,388 to 966,360: 1,972 new blocks. Encoded frames through 964,379 were preserved. The nine-block incomplete GOP was encoded again with the new tail and a replacement 300-frame ending: 2,281 encoded tail frames in total.

The existing compressed prefix was packet-copied into the new master. HLS reused 1,607 older segments and uploaded only five replacement/new segments. Cloud history reused base shards with spend patches and five full new/replaced shards. Video, history and metadata were checked together before cutover.

These timings are observations from one run, not performance promises; overlapping rows must not be added. The complete report records uploads, rollback, timestamp correction, verification and network failures. Roughly 49 minutes still went into reconstructing renderer state, including 1,080 historical slide rebuilds. Skipping invisible slides or adding a renderer checkpoint could reduce this cost; neither optimization is implemented in this edition.

The append scripts are anchored to that verified run's filenames, ranges and manifest. A future update must prepare fresh values and compute its closed-GOP and HLS boundaries. They are not a general unattended “update to tip” command.

Evidence: complete timed append report · retained source files and next-update procedure

Every choice has a cost.

The settings behind the image.

Every field read by Cfg.cpp is listed below. “Required” means the JSON parser has no fallback, even when a particular task does not use that field. Production values are from the published render profile; omitted values use the parser fallback. File paths are shown as portable roles rather than a maintainer's volume path.

42 settings shown

The explorer uses its own matching profile for historyFile, explorerVideoFile, explicit end block and geometry. skipBlocks=0 and 1 both emit every block; only values greater than 1 reduce frame emission. Optional-field parsing currently catches load/type errors and falls back, so validate edited JSON and test a short range rather than assuming malformed values will always be rejected.

Authoritative: parser · types · published render profile · explorer profile

Reproduce your own edition.

Use a C++17 compiler, CMake ≥3.13, OpenCV and TBB development libraries. Dependencies are pinned Git submodules. FFmpeg is needed for video, Python 3 for the configuration wizard and publishing tools.

git clone --recurse-submodules https://github.com/nostitos/utxo-timelapse.git
cd utxo-timelapse
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --parallel
./build/buv

# Targeted checks that run on the current macOS build too:
./build/buv -ns '-tc=density_palette,epoch_transition_mapping,checkpoint_v3'

Ubuntu/Debian packages: build-essential cmake libopencv-dev libtbb-dev. macOS Homebrew: cmake opencv tbb. Current AppleClang may need the documented warning compatibility flags and the TBB link path in the operations index. On macOS the broad legacy unit suite is omitted by CMake; a bare “SUCCESS” with zero cases is not a regression test. The targeted checks above run explicitly.

1. Extract or update

Use a synchronized Bitcoin Core with rest=1 and txindex=1, preferably on the same node as the preprocessor. Adapt the checked-in paths to your machine. Read the v3 resume requirements before pointing an updater at existing data.

./build/buv -ns -tc=utxo_to_change -cfg=configs/buv_update.json

2. Configure and encode

Start with a copy of configs/buv_render_full_weighted.json for the published look. The wizard explains its supported settings, but newer rendering options are set directly in JSON. Start FFmpeg first; then run the visualizer in another terminal. This sample preserves the source's 4:4:4 colour resolution.

ffmpeg -n -f rawvideo -pixel_format rgb24 \
  -video_size 3840x2160 -framerate 60 \
  -i 'tcp://127.0.0.1:12987?listen' \
  -c:v libx265 -preset superfast -crf 21 -pix_fmt yuv444p output.mkv

./build/buv -ns -tc=visualizer -cfg=configs/my-render.json

ffmpeg -n -i output.mkv -c copy -tag:v hvc1 \
  -movflags +faststart output.mp4

The example assumes my-render.json is your adapted copy with 3840×2160 geometry and valid input/output paths. Set a short meaningful block range before a full run. A later startShowAtBlockHeight still replays earlier changes to reconstruct density; it does not make the historical state free.

3. Build history and inspect locally

./build/buv -ns -tc=utxo_history -cfg=configs/my-explorer.json
./build/buv -ns -tc=utxo_explorer -cfg=configs/my-explorer.json
# Open http://127.0.0.1:12988/

Copy configs/buv_explorer.json and set its BLK, history and MP4 paths plus matching geometry and block range. After a compatible BLK append, utxo_history_update extends an existing index. Cloud publishing is covered in the Worker README. Build Docker from the repository root with docker build -t buv .; the container entry point is already buv.

4. Maintain the guide

Edit site/ directly. No bundler or framework is required. GitHub Actions validates and publishes this directory. scripts/build_site_media.py extracts curated frame/clip previews from an existing master; the full master and history stay outside Git. Media provenance is recorded in the asset manifest.

Evidence before “done.”

1. Extraction: validate the BLK marker, contiguous heights, last record hash and exact EOF against the matching v3 checkpoint and node.
2. Rendering: require renderer/FFmpeg success, the final encoder summary, zero ledger misses and dropped decrements, and the expected frame count.
3. Video: inspect dimensions, fps, codec, chroma and duration with ffprobe; decode meaningful early, boundary and recent frames.
4. Append: verify old-prefix bytes and packet/timestamp samples, matching codec configuration, the full splice decode, and continuous HLS timestamps.
5. History: compare cloud pixel counts and satoshi sums against the local index, including old outputs spent after the previous cutoff.
6. Delivery: verify HTTP Range responses, actual playback and paused seeks in the browser, plus shared pixel links.
7. Guide: check every local asset and link target, responsive layouts, keyboard access, image lightboxes and the time-axis demo against the production mapper.

The release report records eight cloud/local pixel comparisons and multi-era playback checks. The guide's frame captions are tied to the block timestamp table; stills are extracted by an integer-second seek followed by a frame-index selection to avoid fractional timestamp rounding. Preview compression may hide individual points, and neither images nor denomination patterns identify a person or establish transaction intent.

Evidence: September 10 report · transition checks · palette checks

Built on shared work.

Martinus's BitcoinUtxoVisualizer is the original concept and code foundation. UTXO Timelapse is maintained by nostitos, with substantial changes to time mapping, accounting, visual encoding, inspection and delivery. The original MIT copyright and license remain intact.

The native program uses OpenCV, fmt, simdjson, doctest, robin-hood-hashing, cpp-httplib, indicators and Howard Hinnant's date library. FFmpeg performs encoding and packaging. Cloud delivery uses Cloudflare Workers and R2; the explorer vendors hls.js 1.7.2 with its license. The site uses Instrument Serif and IBM Plex Sans/Mono under the SIL Open Font License, with fonts hosted here.

Frames, clips and screenshots in this guide come from this project's render and interface. The explicitly labelled original comparison image and animation come from Martinus's repository. The palette comparisons are labelled development experiments. No generated illustration is presented as blockchain evidence.

MIT license · native dependency sources · hls.js license · GitHub Pages deployment reference