Skip to Content
Metrics

Metrics

A metric is one number about your protocol, kept over time and shown as a chart: a treasury’s balance, a vault’s share price, swap fees per hour.

Two kinds of metric

Every metric is either a state metric or an activity metric. The Metrics page marks each one.

KindWhat it measuresExampleChart
StateHow something stands at a momentTreasury ETH balance, stETH total supply, a vault’s share priceA line
ActivityWhat happened over a windowSwaps per hour, fees earned per day, deposits per dayBars per period

A state metric answers “what is it now?”. An activity metric answers “how much happened?”.

State metrics

A state metric is a point-in-time reading: a balance, a supply, a rate, a price or a function’s result. It is read every minute, and its chart shows the value at each point in time. It can be:

  • A function result — What a view function returns, such as totalAssets() or utilisation().
  • A token balance — The ERC-20 balance a contract or wallet holds.
  • A native balance — ETH, or the chain’s own coin.
  • A formula — Several reads at the same block and an expression over them, such as pooled / shares.
  • A group total — The same read on every member of a group, added up, such as available liquidity across every market. Each member can also be kept as its own line.
  • A table total — A state table’s column added up across its active rows, or its active rows counted.

When a state metric is created, contract.dev reads back its earlier values where history is available. The metric’s page shows how far back it reaches.

Activity metrics

An activity metric is built from events. Each window’s figure is the count, sum, average, lowest or highest of the events in it.

  • Counts — Swaps per hour, loans opened per day.
  • Sums — Fees in USD, volume in tokens. Dollar values are priced on the day each event happened, where a price for the token is available.
  • Splits — The same figure broken down by contract or by an event field, such as by pool, each split its own series.
  • Conditions — Only the events you want, such as swaps over $10,000.

An activity metric reads its history first, then stays current as new events arrive.

Activity metrics count events, not distinct values: unique active wallets are a report line, not a metric. Each watched contract’s page shows its transactions, events, transfers and wallets without any setup.

Metrics from tables

FigureMetric
Total outstanding debt across open loansState: the Loans table’s Owed column, added up
Number of currently open loansState: the Loans table’s active rows, counted
Loans opened per dayActivity: LoanOpened events, counted
Big swaps per dayActivity: the Big swaps table’s rows, counted per day

See Tables.

The Metrics page

The Metrics page lists every metric in your workspace with its kind and type, what it is on, its chain, its current value, its change over the last 24 hours and its 24-hour trend.

In place of the change, a metric can show:

StatusMeaning
Indexing…Its history is still being read.
PausedIt is not being read.
StaleIts events have stopped arriving when they usually would. Shows the time of its last record.
FailedIts definition no longer works, such as one over a deleted table. Shows the reason.

Select a metric to open its page.

  • A state metric shows its value over time as a line, over 24 hours, 7 days, 30 days or 90 days, with pan and zoom. Its readings list each change in value, with its block and time.
  • An activity metric shows bars per hour or per day, its splits, and the events behind each figure, each linked to its transaction on the chain’s explorer.

Periods not yet read are shown as missing, never as 0.

A metric made for one report or alert stays off the Metrics page and is deleted with it.

Use metrics elsewhere

  • Condition alerts — Alert when a metric crosses a line, falls against a day ago or runs above its usual level. See Condition alerts.
  • Activity alerts — Send a message each time a metric changes. See Activity alerts.
  • Reports — Include any metric in a scheduled report. See Reports.
  • Questions — Ask your agent about a metric’s value, its trend or what changed.

Create a metric

Metrics are created and changed by your coding agent or the CLI, with metric define. The app shows them, and deletes them.

A state metric names what it is on and what to read:

contract-dev metric define "stETH supply" --on steth --call "totalSupply()"

A formula over several reads:

contract-dev metric define "stETH per share" --on steth \ --call "pooled=getTotalPooledEther() decimals 18" --call "shares=getTotalShares() decimals 18" \ --value "pooled / shares"

An activity metric names the event and what to add up:

contract-dev metric define "Swap fees" --on tag:pools --each Swap \ --read "fee=fee()" --read "t0=token0()" \ --value "usd(abs(amount0) * fee / 1000000, t0)" --split contract

A table total:

contract-dev metric define "Outstanding" --on table:"Withdrawal requests" --column Outstanding

See the CLI reference for every flag.

Inspect a metric from the terminal

contract-dev metrics contract-dev metric show "Swap fees" --days 7 contract-dev metric show "stETH supply" --range 30d

Ask your agent

Describe the figure you want. Your agent finds the contracts and data, defines the metric and links to it in the app. See Agent Integration.

Track our vault's totalAssets() and show its history.
Create a metric for swap fees earned in USD, broken down by pool.

The metric appears on the Metrics page in the contract.dev app.

Last updated on