WIP chore: add metric definitions by pyropy · Pull Request #92 · FilOzone/filecoin-pay-explorer

pyropy · 2026-01-28T10:03:57Z

Copies METRICS-DEFINITIONS.md from https://github.com/timfong888/filecoin-pay-console

Closes #85

vercel · 2026-01-28T10:04:02Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
filecoin-pay-explorer	Ready	Preview, Comment	Feb 3, 2026 9:53am

pyropy

Hey @davidgasquez let's start a discussion on metrics here 🙌🏻

pyropy · 2026-01-28T10:09:07Z

METRIC-DEFINITIONS.md

+
+#### FIL Burned
+- **Definition:** Total FIL burned from three sources:
+  1. Settling USDFC


Settling USDFC does not inherently burn any FIL, rather the settled USDFC is set for auction and the FIL is burned only after successful bid.

This seems like a good note. Add it inline?

pyropy · 2026-01-28T10:11:26Z

METRIC-DEFINITIONS.md

+- **Formula:** `Σ(account.userTokens.lockupCurrent)` converted from wei (18 decimals) to USDFC
+- **Note:** Same metric as GA Mode. Displayed between Active Payers and USDFC Settled.
+
+#### Total Settled (USDFC)


Are we only interested in displaying USDFC settlement? What about native (FIL) settlements? Do we need separate metric for those?

Is this also a duplicate metric (there is USDFC Settled (Cumulative) above)?

pyropy · 2026-01-28T10:13:37Z

METRIC-DEFINITIONS.md

+- **Source:** Sum of `Rail.totalSettledAmount` across all rails with settlements
+- **Formula:** `Σ(rail.totalSettledAmount)` converted from wei (18 decimals) to USDFC
+
+#### Settled (7d)


Do settlements include one-time payments? These two seem different, although we (FilBeam) are using one-time payments for egress settlements.

Perhaps this could be another metric (i.e. Transfers (7d) ) ?

pyropy · 2026-01-28T10:14:04Z

METRIC-DEFINITIONS.md

+  1. Settling USDFC
+  2. Settling FIL
+  3. Auction


As mentioned in https://github.com/FilOzone/filecoin-pay-explorer/pull/92/changes#r2735886312

pyropy · 2026-01-28T10:16:07Z

METRIC-DEFINITIONS.md

+- **Sortable:** Yes
+
+### Data Size
+- **Definition:** Total data size in GB across all payees' PDP proof sets


Seems like we're expanding functionality of Filecoin Pay explorer here. Maybe it's time to rename the project to Filecoin Services Explorer? :D

+1 to this. The scope here feels broader than “Filecoin Pay Explorer” at this point.
Also, why does data size on payer accounts aggregate payee datasets? If that’s intentional, the column should reflect 'data the payer is paying for,' or be renamed.

Checking my assumption here. Would the event data for this be in pdp contract/ABI?

pyropy · 2026-01-28T10:18:05Z

METRIC-DEFINITIONS.md

+- **Sortable:** Yes
+
+### Proven
+- **Definition:** Proof submission status for the payer's payees


Suggested change

- **Definition:** Proof submission status for the payer's payees

- **Definition:** Proof submission status for the payer's payment rails

Payees might submit proofs for other non-related payment rails (one payee might have multiple payers). I propose only displaying proofs for payers payment rails.

pyropy · 2026-01-28T10:19:29Z

METRIC-DEFINITIONS.md

+## Data Sources
+
+### Filecoin Pay Subgraph (Goldsky)
+- **Endpoint:** `https://api.goldsky.com/api/public/project_cmj7soo5uf4no01xw0tij21a1/subgraphs/filecoin-pay-mainnet/1.1.0/gn`
+- **Entities Used:** Account, Rail, Settlement, PaymentsMetric, UserToken, Token
+- **Purpose:** Payment rails, settlements, account balances
+
+### PDP Explorer Subgraph (Goldsky)
+- **Endpoint:** `https://api.goldsky.com/api/public/project_cmdfaaxeuz6us01u359yjdctw/subgraphs/pdp-explorer/mainnet311/gn`
+- **Entities Used:** Provider
+- **Purpose:** Storage provider proof status and data sizes
+- **Correlation Key:** `Provider.address` matches `Rail.payee.address`
+
+---
+
+## Constants
+
+| Constant | Value | Description |
+|----------|-------|-------------|
+| `EPOCH_DURATION_SECONDS` | 30 | Duration of one Filecoin epoch |
+| `EPOCHS_PER_DAY` | 2880 | 24 × 60 × 60 / 30 |
+| `EPOCHS_PER_24_HOURS` | 2880 | Used for proof freshness check |
+| `FILECOIN_GENESIS_TIMESTAMP` | 1598306400 | 2020-08-25 00:00:00 UTC |
+| `TOKEN_DECIMALS` | 18 | USDFC decimal places |
+| `BYTES_PER_GB` | 1073741824 | 1024³ |


To other reviewers I propose ignoring this for now until we sort the metric definitions.

pyropy · 2026-01-28T10:20:17Z

METRIC-DEFINITIONS.md

+- **Formula:** `Σ(account.userTokens.lockupCurrent)` converted from wei (18 decimals) to USDFC
+- **Note:** This represents the total amount of USDFC that has been deposited and is locked to secure active payment rails. Displayed between Active Payers and USDFC Settled.
+
+#### USDFC Settled (Cumulative)


Are we interested in native token settlements?

pyropy · 2026-01-28T10:21:57Z

METRIC-DEFINITIONS.md

+- **Display:** Formatted as currency (e.g., "$1.23K", "$456.78")
+- **Sortable:** Yes
+
+### Settled (7d)


Should this be a single number or time series?

pyropy · 2026-01-28T12:30:09Z

@timfong888 I went over your dashboard prototype and reviewed some of the metrics and stuff displayed over there. It's more of a general feedback / questions on what we want to display as that will shape what we put into the METRICS-DEFINITIONS.md file

Main page (Dashboard)

We should either leave total active payers chart or just display the number of total active payers, I don’t see the need for both
Total USDFC settled chart can replace both the “USDFC Settled” and “Settled (7d)” cards by showing last settlement time series data for last 7 days. Based on this chart we can make an estimate of how much USDFC has been settled in the last 7 days (i.e. on Monday total was $1000 and on Sunday it’s $1200 meaning there was $200 worth of settlements in the last 7 days)
“Current Auction Price” can show the current price of USDFC in FIL but cannot show the actual bid. As I understand the current bidding system will swap the FIL -> USDFC if the price matches the current price, hence there is no competing bids.
Definition for “Total Auction Volume” is “The cumulative amount of USDFC bid so far in the auction” but I would change the definition to “Total USDFC Volume auctioned”.
“Total Auction Participants” would show unique number of addresses that performed a successful bid (which is basically a swap, correct me if I’m wrong)
Top 10 Payers sounds like a good section. If people don’t find that valuable we can switch it for last 10 settlements or something like that.

Payer accounts page

Same comments apply related to showing USDFC settlements in multiple ways as above. We should either stick to cards or charts IMO.

Payee accounts page

All looks good here. If we decide to add the PDP data set details to the explorer having “Total Data Stored” card makes sense.

Payer Details

Personally I would remove the “My Data” section or at least the search bar for CID search.
There is a singular “Settle” button (!) where the settlements are actually per rail. Instead I would suggest adding this button to each payment rail in the “Payment rails” section.

Payee details

“Claimable Now” can maybe be renamed to “Available for settlement” or something like that. I think we should stick with one term, that one being settlement.
“Total Received” does this include one-time payments? If not perhaps better name is “Total Settled”
“Monthly Run Rate” I’m not exactly sure about the definition on this one? Maybe someone could explain it briefly?

cc @geomatrick I know Tim and you have worked on this quite a bit, so maybe you have also some feedback on what metrics we'd like to display?

This reverts commit 54115f3.

silent-cipher · 2026-01-28T15:10:11Z

METRIC-DEFINITIONS.md

+
+#### USDFC Settled (Cumulative)
+- **Definition:** Cumulative sum of all USDFC settled across all payment rails since inception
+- **Source:** Sum of `Rail.totalSettledAmount` across all rails with settlements


Should one-time payments count toward the “settled amount” for a rail?
I think they should. I didn’t treat them as settlements earlier, but if that’s the intended behavior, #86 addresses it. Otherwise, we should be explicit about excluding them.

Judging by the @timfong888 's implementation one-time payments are counted towards total settled amount.

Reason I have asked this same question is that one-time payments are not used only for settlements, but for example one may use it to charge a one-time fee for data set creation to prevent sybil attacks.

Edit: @timfong888 's implementation does not count one-time payments towards settlements which in my mind is a right thing to do.

Yes, that's right we should. I only used the recurring rails. Do we want to differentiate between the sybil fee and one-time payments? We should include that total.

silent-cipher · 2026-01-28T15:10:55Z

METRIC-DEFINITIONS.md

+#### Settled (7d)
+- **Definition:** Total USDFC settled in the last 7 days (rolling window)
+- **Source:** `Settlement` events from Goldsky subgraph filtered by timestamp
+- **Formula:** `Σ(settlement.totalSettledAmount)` where `settlement.settledUpto >= (now - 7 days)`


This formula looks incorrect. Settlements should only include rails using the USDFC token.
Also, we should use settlement.createdAt instead of settlement.settledUpto here.

Suggested change

- **Formula:** `Σ(settlement.totalSettledAmount)` where `settlement.settledUpto >= (now - 7 days)`

- **Formula:** `Σ(settlement.totalSettledAmount)` where `settlement.rail.token == USDFC_TOKEN_ADDRESS AND settlement.blockNumber >= (now - 7 days)`

What are we excluding if not using USDFC token for settlement? I know the definition or objective was USDFC settled, so this is correct; but should we as a fast-follow break out to show other tokens? I think it's a good idea to constrain to the token address as indicated.

There are some rails using the FIL token today, those would be excluded with the current USDFC-only logic.
I agree we should constrain this to USDFC for now, but design it with multi-token support in mind.

I don't have context here but, why constrain to USDFC? Trying to understand if I have to support a multi-token metrics or USDFC is the expected token for the foreseable future.

silent-cipher · 2026-01-28T15:11:48Z

METRIC-DEFINITIONS.md

+- **Sortable:** Yes
+
+### Data Size
+- **Definition:** Total data size in GB across all payees' PDP proof sets


+1 to this. The scope here feels broader than “Filecoin Pay Explorer” at this point.
Also, why does data size on payer accounts aggregate payee datasets? If that’s intentional, the column should reflect 'data the payer is paying for,' or be renamed.

silent-cipher · 2026-01-28T15:13:35Z

METRIC-DEFINITIONS.md

+### Settled (7d)
+- **Definition:** USDFC settled by this payer in the last 7 days
+- **Source:** `Settlement` events filtered by payer address and timestamp
+- **Formula:** `Σ(settlement.totalSettledAmount)` where `settlement.rail.payer.address == payerAddress AND timestamp >= now - 7 days`


Suggested change

- **Formula:** `Σ(settlement.totalSettledAmount)` where `settlement.rail.payer.address == payerAddress AND timestamp >= now - 7 days`

- **Formula:** `Σ(settlement.totalSettledAmount)` where `settlement.rail.payer.address == payerAddress AND settlement.rail.token == USDFC_ADDRESS AND timestamp >= now - 7 days`

silent-cipher · 2026-01-28T15:14:16Z

METRIC-DEFINITIONS.md

+- **Purpose:** Payment rails, settlements, account balances
+
+### PDP Explorer Subgraph (Goldsky)
+- **Endpoint:** `https://api.goldsky.com/api/public/project_cmdfaaxeuz6us01u359yjdctw/subgraphs/pdp-explorer/mainnet311/gn`


Who’s maintaining this going forward?
Also, if the scope is expanding beyond just Filecoin Pay contract (toward full FOC), should we consider indexing PDPVerifier alongside the Filecoin Pay contract in a single subgraph?

Who’s maintaining this going forward?

Are you referring to subgraph or the project as a whole? Response we got from @jennijuju is that the pod is responsible for the explorer.

Also, if the scope is expanding beyond just Filecoin Pay contract (toward full FOC), should we consider indexing PDPVerifier alongside the Filecoin Pay contract in a single subgraph?

That's also question I had. Looks like we're transitioning to a Filecoin Services explorer.

I was referring to PDP Explorer Subgraph - Looks like pod is responsible for that too.

@silent-cipher : to make sure we aren't losing track of it operationally, where does this subgraph definition live in code? Acutally, if you don't mind, it would be good to get a full list of our subgraphs and their source code links added to https://www.notion.so/filecoindev/FOC-Operational-Excellence-2b7dc41950c1802aa432fff8ecb801cc?source=copy_link#2e1dc41950c18031a285cf6f826a4c28

BigLep

I'm not a blocking approver here. I wanted to read it to be more aware of how things worked, but please feel free to proceed without further review from me.

BigLep · 2026-01-29T06:44:27Z

METRIC-DEFINITIONS.md

+- **Definition:** Total USDFC currently locked across all accounts for future payments
+- **Source:** Sum of `Account.userTokens.lockupCurrent` from Goldsky subgraph
+- **Formula:** `Σ(account.userTokens.lockupCurrent)` converted from wei (18 decimals) to USDFC
+- **Note:** This represents the total amount of USDFC that has been deposited and is locked to secure active payment rails. Displayed between Active Payers and USDFC Settled.


I don't know what "Displayed between Active Payers and USDFC Settled" menas.

BigLep · 2026-01-29T06:46:11Z

METRIC-DEFINITIONS.md

+
+#### FIL Burned
+- **Definition:** Total FIL burned from three sources:
+  1. Settling USDFC


This seems like a good note. Add it inline?

BigLep · 2026-01-29T06:46:29Z

METRIC-DEFINITIONS.md

+  1. Settling USDFC
+  2. Settling FIL
+  3. Auction
+- **Status:** Coming soon (placeholder metric)


Link to tracking issue (and then update the tracking issue to have a note to update this doc)?

BigLep · 2026-01-29T06:47:59Z

METRIC-DEFINITIONS.md

+- **Definition:** Total USDFC currently locked across all accounts for future payments
+- **Source:** Sum of `Account.userTokens.lockupCurrent` from Goldsky subgraph
+- **Formula:** `Σ(account.userTokens.lockupCurrent)` converted from wei (18 decimals) to USDFC
+- **Note:** Same metric as GA Mode. Displayed between Active Payers and USDFC Settled.


If this is a duplicate metric in a prototype, why even document it?

Yeah, I think this is the same as the one on top!

BigLep · 2026-01-29T06:49:16Z

METRIC-DEFINITIONS.md

+- **Source:** Engineering will drive implementation
+- **Note:** Non-functional in current release - displays placeholder value
+
+### Prototype Mode Metrics


If we're going to document "prototype mode" metrics (I'm not even sure that's important), do we document where someone goes to see these "prototype mode" metrics?

(But again I'm wondering if we even want to document these in our public docs unless we expect others to access "prototype mode".)

BigLep · 2026-01-29T06:54:59Z

METRIC-DEFINITIONS.md

+
+### Address
+- **Definition:** The wallet address of the payer account
+- **Display:** Truncated address (`0x1234...abcd`) or ENS name if resolved


Link/describe how ENS name is resolved?

BigLep · 2026-01-29T06:59:08Z

METRIC-DEFINITIONS.md

+- **Purpose:** Payment rails, settlements, account balances
+
+### PDP Explorer Subgraph (Goldsky)
+- **Endpoint:** `https://api.goldsky.com/api/public/project_cmdfaaxeuz6us01u359yjdctw/subgraphs/pdp-explorer/mainnet311/gn`


@silent-cipher : to make sure we aren't losing track of it operationally, where does this subgraph definition live in code? Acutally, if you don't mind, it would be good to get a full list of our subgraphs and their source code links added to https://www.notion.so/filecoindev/FOC-Operational-Excellence-2b7dc41950c1802aa432fff8ecb801cc?source=copy_link#2e1dc41950c18031a285cf6f826a4c28

BigLep · 2026-01-29T06:59:55Z

METRIC-DEFINITIONS.md

+---
+
+## Removed Metrics
+
+### Monthly Run Rate (MRR)
+- **Status:** Removed as of v0.11.0
+- **Reason:** Replaced with actual settlement data (Settled 7d) for more accurate activity representation
+- **Previous Definition:** Projected monthly payment volume based on active rail payment rates
+- **Previous Formula:** `Σ(activeRail.paymentRate) × EPOCHS_PER_MONTH (86,400)`


Given we haven't hit GA yet or had a v1 of this document before, maybe not even worry about this?

BigLep · 2026-01-29T07:00:46Z

METRIC-DEFINITIONS.md

Consider putting a "changelog" at the top of the file that gets short updates when changes are made after v1?

## Status * 2026-01-28 - Initial GA metric set definitions.

davidgasquez

Left a couple of questions. Thanks for opening starting the discussion @pyropy, it's been helpful

We should either leave total active payers chart or just display the number of total active payers, I don’t see the need for both

I think the chart might be "incorrect" as it is looking at the current state so historical values will change. It'll be always growing and monotonic even if from one day to another it goes down by 10 active payers.

davidgasquez · 2026-01-29T09:19:09Z

METRIC-DEFINITIONS.md

+- **Definition:** Total USDFC currently locked across all accounts for future payments
+- **Source:** Sum of `Account.userTokens.lockupCurrent` from Goldsky subgraph
+- **Formula:** `Σ(account.userTokens.lockupCurrent)` converted from wei (18 decimals) to USDFC
+- **Note:** Same metric as GA Mode. Displayed between Active Payers and USDFC Settled.


Yeah, I think this is the same as the one on top!

davidgasquez · 2026-01-29T09:20:43Z

METRIC-DEFINITIONS.md

+- **Formula:** `Σ(account.userTokens.lockupCurrent)` converted from wei (18 decimals) to USDFC
+- **Note:** Same metric as GA Mode. Displayed between Active Payers and USDFC Settled.
+
+#### Total Settled (USDFC)


Is this also a duplicate metric (there is USDFC Settled (Cumulative) above)?

davidgasquez · 2026-01-29T09:22:16Z

METRIC-DEFINITIONS.md

+#### Settled (7d)
+- **Definition:** Total USDFC settled in the last 7 days (rolling window)
+- **Source:** `Settlement` events from Goldsky subgraph filtered by timestamp
+- **Formula:** `Σ(settlement.totalSettledAmount)` where `settlement.settledUpto >= (now - 7 days)`


I don't have context here but, why constrain to USDFC? Trying to understand if I have to support a multi-token metrics or USDFC is the expected token for the foreseable future.

davidgasquez · 2026-01-29T09:26:39Z

METRIC-DEFINITIONS.md

+- **Sortable:** Yes
+
+### Data Size
+- **Definition:** Total data size in GB across all payees' PDP proof sets


Checking my assumption here. Would the event data for this be in pdp contract/ABI?

davidgasquez · 2026-01-29T10:37:04Z

In case it is helpful, I'm working on the same metrics using the existing definition but deriving everyghing from the FEVM logs.

pyropy · 2026-01-29T13:58:06Z

Linking this comment here.

We might want to wait with metric definitions until we have subgraph ready. Depending on the subgraph formulas to get the metrics might change.

As for definitions, we'd only need three:

Total USDFC & FIL locked in payment rails
Total USDFC & FIL transacted (cumulative)
Total FIL burned from Filecoin Pay (cumulative)

timfong888 · 2026-01-29T17:39:29Z

@davidgasquez for myself to understand the stack, what is pipeline you have set up to use EVM Logs?

REgarding the other questions, I belive the PDP verifier contract was where I found data size. It is not in the pay contract.

davidgasquez · 2026-01-30T09:12:07Z

what is pipeline you have set up to use EVM Logs?

I'm working on the pipeline but for now, Riba has published the result of the eth_getLogs call for all heights since October (e.g. https://ribrpc.fil.st/archive/fil/mainnet/2026/01/21/eth_getLogs.v1.r1.flattened.ndjson.zst).

I'm ingesting these and then decoding all the events from any contract ABI I can get my hands into.

That gives me all the events with their args as JSON that I have to parse into entities (accounts) and metrics.

With this pipeline, I just need to tweak the SQL transformations and rerun it (1 second) to tweak the metrics.

chore: copy METRIC-DEFINITIONS.md from timfong888/filecoin-pay-console

b2c8119

FilOzzy added this to FOC Jan 28, 2026

github-project-automation bot moved this to 📌 Triage in FOC Jan 28, 2026

vercel bot deployed to Preview January 28, 2026 10:04 View deployment

pyropy commented Jan 28, 2026

View reviewed changes

pyropy mentioned this pull request Jan 28, 2026

Integrate numbers across public-facing dashboards #64

Closed

pyropy requested review from BigLep, geomatrick, jennijuju, silent-cipher and timfong888 January 28, 2026 13:05

pyropy moved this from 📌 Triage to ⌨️ In Progress in FOC Jan 28, 2026

pyropy self-assigned this Jan 28, 2026

chore: default to client over server components

54115f3

vercel bot deployed to Preview January 28, 2026 14:34 View deployment

Revert "chore: default to client over server components"

32701e7

This reverts commit 54115f3.

vercel bot deployed to Preview January 28, 2026 14:37 View deployment

silent-cipher reviewed Jan 28, 2026

View reviewed changes

rjan90 added this to the M4.0: mainnet staged milestone Jan 28, 2026

rjan90 linked an issue Jan 28, 2026 that may be closed by this pull request

metrics criteria has been reviewed and accepted by engineering #85

Open

BigLep reviewed Jan 29, 2026

View reviewed changes

davidgasquez reviewed Jan 29, 2026

View reviewed changes

rjan90 modified the milestones: M4.0: mainnet staged, M4.1: mainnet ready Jan 30, 2026

chore: leave only GA metric definitions

7b6b6de

vercel bot deployed to Preview February 3, 2026 09:53 View deployment

	- Definition: Proof submission status for the payer's payees
	- Definition: Proof submission status for the payer's payment rails

	- Formula: `Σ(settlement.totalSettledAmount)` where `settlement.settledUpto >= (now - 7 days)`
	- Formula: `Σ(settlement.totalSettledAmount)` where `settlement.rail.token == USDFC_TOKEN_ADDRESS AND settlement.blockNumber >= (now - 7 days)`

Conversation

pyropy commented Jan 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

vercel bot commented Jan 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

pyropy left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

pyropy commented Jan 28, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

pyropy Jan 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

BigLep left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

pyropy commented Jan 28, 2026 •

edited

Loading

vercel bot commented Jan 28, 2026 •

edited

Loading

pyropy Jan 28, 2026 •

edited

Loading

davidgasquez left a comment •

edited

Loading