CycleScan

Data Collection

CycleScan collects cycle balance data hourly using GitHub Actions. Each hour, we query ~2,900 canisters across the Internet Computer to record their current cycle balance. This data is stored in a public JSON file and fetched directly by your browser.

Why hourly? Hourly collection provides enough data points for accurate trend analysis while keeping infrastructure costs minimal. We store 7 days of hourly snapshots (~168 data points per canister).

Burn Rate Calculation

CycleScan uses an interval-based averaging approach to calculate burn rates. We analyze the change in balance between each consecutive snapshot:

  • Burn intervals: When balance decreases between snapshots, this represents actual cycle consumption
  • Top-up intervals: When balance increases, this indicates a cycle top-up occurred

The Algorithm

For each canister within a time window, we:

  1. Calculate the burn rate from all intervals where the balance decreased
  2. Compute the average burn rate per millisecond from these "burn intervals"
  3. For top-up intervals, we infer what the burn would have been based on this average
  4. Sum actual burns + inferred burns to get the total burn over the full time period
Burn Rate = (Actual Burns + Inferred Burns) ÷ Total Duration

This approach gives us accurate burn rates even when top-ups occur, because we estimate the burn that would have happened during those periods.

Time Windows

We calculate burn rates over three time windows:

Window Data Used Best For
Recent Last ~2 hours Detecting sudden changes in activity
Short-term Last ~36 hours Day-over-day trends, primary metric
Long-term Last ~7 days Stable baseline burn rate

Handling Top-Ups

When a canister receives new cycles (a "top-up"), its balance jumps upward. CycleScan detects any balance increase as a top-up and handles it automatically:

  • Detection: Any interval where the ending balance is higher than the starting balance is marked as a top-up interval.
  • Inference: During top-up intervals, we estimate the burn that would have occurred based on the average burn rate from non-top-up intervals.
  • Calculation: The final burn rate includes both actual measured burns and inferred burns, giving you an accurate picture of consumption.
Example: If a canister burns 100B cycles/hour on average, and receives a 1T cycle top-up during a 1-hour interval, we infer that ~100B cycles were also burned during that hour. The displayed burn rate accounts for this.

Project Aggregation

CycleScan groups canisters by project and calculates aggregate statistics. Here's how project-level metrics are computed:

  • Total Balance: Sum of all canister balances in the project
  • Burn Rate: Sum of individual canister burn rates. Each canister's rate is calculated independently using the interval-based algorithm, then summed.
  • Runway: Calculated from the aggregated balance and burn rate, representing the project as a whole
Why sum rates? Since each canister burns cycles independently, the total project burn is simply the sum of all canister burns. This gives you a complete picture of the project's resource consumption.

The "Include Cycle Transfers" Toggle

Some canisters don't actually burn cycles — they transfer them to other canisters. These show up as high "burn" rates but aren't real consumption. CycleScan flags these canisters and the toggle controls how they're handled:

Toggle State What Happens
OFF (default) Flagged canisters are hidden from the expanded project list and excluded from all aggregate calculations (balance, burn rate, runway, trend chart)
ON All canisters are shown and included in aggregate calculations. Projects with cycle-transferring canisters will show inflated burn rates.

Flagged canisters are marked with a flag icon when visible.

Trend Chart

The "Trend" column shows a compact visualization of burn activity over the last 7 days. It's a mini bar chart where each bar represents one hour of data.

How It Works

  • Time range: Last 7 days of hourly data (~168 bars, though only the most recent portion is visible in the compact view)
  • Bar height: Proportional to the burn rate during that hour
  • Colors: Green for actual burns, yellow/amber for intervals with inferred data (top-ups detected)

Logarithmic Scaling

When burn rates are "spiky" (maximum > 10× median), the chart automatically switches to logarithmic scaling. This prevents occasional large spikes from flattening all the other bars into invisibility.

Special Indicators

Display Meaning
· (dot) All burns are zero — no activity detected
— (dash) Insufficient data (fewer than 3 hours of snapshots)

Project Trends

For projects, the trend chart shows aggregated burn across all canisters in that project. Click on any project's trend chart to open a detailed view with:

  • Full-size aggregate burn chart with 1D/3D/7D time range selector
  • Total balance and canister count
  • Aggregate burn rates (recent, short-term, long-term)
  • The same actual/inferred/top-up breakdown as individual canisters
Tip: Clicking the trend chart opens the project detail modal. Clicking elsewhere on the row expands it to show individual canisters.

Detail Chart

When you click on a canister row or a project's trend chart, a detail modal opens with a full burn rate chart. The bars are color-coded:

Color Meaning
Green Actual burn - Measured cycle consumption from intervals where balance decreased
Orange Inferred burn - Estimated consumption during top-up intervals, based on average burn rate
Red (below zero) Top-up amount - The cycles added during that interval (shown as negative/below the axis)

The orange dashed line shows the average burn rate across all actual burn intervals.

Runway Calculation

Runway estimates how long until a canister runs out of cycles at the current burn rate:

Runway = Current Balance ÷ (Burn Rate per Day)
Display Meaning
< 30d Critical - canister may stop soon
30-90d Warning - consider topping up
90d-1y Okay - healthy runway
> 1y Good - well funded
∞ Infinite - not burning or gaining cycles

Data Sources

  • Canister balances: Queried via the Blackhole canister (for individual canisters) and SNS Root canisters (for SNS projects)
  • Network-wide burn: IC API
  • Project metadata: Curated from public sources

Get Your Project Listed

Missing from CycleScan? Here's how to get your project added.

Eligibility Requirements

Your canister must have a controller that publicly exposes cycle balance information. This means one of the following must be a controller of your canister:

  • Blackhole canister (e3mmv-5qaaa-aaaah-aadma-cai) - A widely-used canister that allows anyone to query canister_status
  • NNS Root canister (r7inp-6aaaa-aaaaa-aaabq-cai) - The NNS root also exposes canister_status publicly
  • SNS Root canister - If your project is an SNS, cycle data is automatically available via get_sns_canisters_summary()

About the Blackhole Canister

The blackhole canister is the recommended option for most projects. It's a simple, trustworthy canister created by ninegua with these properties:

  • Open source - The entire code is ~25 lines of Motoko, just a thin wrapper around the IC management canister
  • Immutable - Its only controller is itself, so it can never be modified
  • Safe - It only exposes canister_status for reading. It cannot upgrade, stop, delete, or modify your canister in any way
  • Verified - Module hash: 0x210cf9...9d7de0

The only "downside" is that anyone can query your canister's cycle balance, memory usage, and module hash. For most projects, this transparency is a feature, not a bug.

Why is this required? Without one of these controllers, there's no way to publicly query a canister's cycle balance. The IC management canister's canister_status method is restricted to controllers, so a public proxy like the blackhole is needed.

How to Get Added

Once your canister meets the eligibility requirements, reach out to us on X (Twitter):

@alexandria_lbry

Include your canister ID(s) and project name, and we'll add you to the leaderboard.

Background: CycleScan was initiated by querying every single canister on the entire ICP network and checking for eligibility. However, we don't continuously scan for newly eligible canisters, so if you've recently added the blackhole as a controller or launched a new project, you'll need to let us know.

Limitations

  • Collection timing: GitHub Actions may have slight variations in when they run, so "hourly" is approximate (±15 minutes typical).
  • Coverage: We track ~2,900 canisters, which is a fraction of all canisters on the IC. Coverage percentage is shown in the header.
  • Inferred burn accuracy: When top-ups occur, the inferred burn is based on the average from other intervals. If burn rates vary significantly, the inference may be less accurate.
  • Cycle transfers: We identify known cycle-transferring canisters, but new ones may not be immediately flagged.