Dealbot Events & Metrics

Data Storage Event Model

Below are the sequence of events for a Data Storage check. The Data Storage flow is used because it encapsulates a Retrieval check as well.

Data Storage Event Timeline

sequenceDiagram
  autonumber
  participant Dealbot
  participant SP as PDP Storage Provider
  participant RPC as Chain RPC Provider
  participant FPNI as filecoinpin.contact IPNI Instance
  participant CPNI as cid.contact IPNI Instance

  rect rgba(120, 120, 200, 0.15)
    %% Data Storage Only
    Dealbot->>SP: uploadToSpStart
    SP-->>Dealbot: uploadToSpEnd (2xx, piece CID)
    Dealbot-->>Dealbot: dealCreated (upload result returned)
    SP-->>Dealbot: pieceAdded (tx hash, async)
    RPC-->>Dealbot: pieceConfirmed (async)
    SP-->>Dealbot: spIndexingComplete
    SP-->>Dealbot: spAnnouncedAdvertisementToIpni
  end

  Dealbot->>FPNI: ipniVerificationStart (filecoinpin.contact)
  FPNI-->>Dealbot: ipniVerificationComplete (filecoinpin.contact)
  opt filecoinpin.contact verified
    Dealbot->>CPNI: ipniVerificationStart (cid.contact)
    CPNI-->>Dealbot: ipniVerificationComplete (cid.contact)
  end
  Dealbot-->>SP: ipfsRetrievalStart
  SP-->>Dealbot: ipfsRetrievalFirstByteReceived
  SP-->>Dealbot: ipfsRetrievalLastByteReceived
  Dealbot-->>Dealbot: ipfsRetrievalIntegrityChecked

Event List

Pull Check Event Model

Below are the events for a Pull Check. Pull checks reverse the data flow of the Data Storage check: instead of dealbot uploading bytes, it asks the SP to pull bytes from a temporary /api/piece/{pieceCid} URL.

Pull Check Event Timeline

sequenceDiagram
  autonumber
  participant Dealbot
  participant SP as PDP Storage Provider
  participant RPC as Chain RPC Provider

  Dealbot->>Dealbot: hostedPieceRegistered
  Dealbot->>SP: pullRequestSubmittedToSp (pullPieces)
  SP-->>Dealbot: pullRequestAcknowledgedBySp
  SP-->>Dealbot: pullRequestStartedBySp
  Dealbot->>SP: pullStatusPolled (waitForPullPieces, repeated)
  SP-->>Dealbot: pullRequestIsTerminal
  Dealbot->>SP: directPieceFetchStarted (/piece/{cid})
  SP-->>Dealbot: directPieceFetchCompleted
  Dealbot-->>Dealbot: pullRequestIntegrityChecked

Pull Check Event List

Sampled Retrieval Check Event Model

Below are the events for an Sampled Retrieval check. Unlike the Data Storage flow, sampled retrieval is a single-shot per-piece flow: select a publicly-discoverable piece from the FWSS subgraph → fetch the piece from the SP → optionally parse the CAR, verify IPNI, and sample block fetches → write one row to ClickHouse. The check emits one row to sampled_retrieval_checks even on abort or unexpected error, so partial timing/byte evidence is never lost.

Sampled Retrieval Check Event Timeline

sequenceDiagram
  autonumber
  participant Dealbot
  participant Subgraph as Subgraph
  participant SP as Storage Provider
  participant IPNI as filecoinpin.contact

  Dealbot->>Subgraph: sampledPieceSelectionStart
  Subgraph-->>Dealbot: sampledPieceSelected
  Dealbot->>SP: sampledPieceFetchStart (GET /piece/{pieceCid})
  SP-->>Dealbot: sampledPieceFetchFirstByteReceived
  SP-->>Dealbot: sampledPieceFetchLastByteReceived
  Dealbot-->>Dealbot: sampledCommPVerified

  opt if piece advertises IPFS indexing
    Dealbot-->>Dealbot: sampledCarParsed
    Dealbot->>IPNI: sampledIpniVerificationStart
    IPNI-->>Dealbot: sampledIpniVerificationComplete
    Dealbot->>SP: sampledBlockFetchStart (GET /ipfs/{cid}?format=raw, sampled)
    SP-->>Dealbot: sampledBlockFetchComplete
  end

  Dealbot-->>Dealbot: sampledRetrievalCheckComplete

Sampled Retrieval Check Event List

Metrics

• Many of the metrics below are derived from the events above.
• They are exported via Prometheus.
• All Prometheus/OpenTelemetry metrics have label/attributes for:
• network=calibration|mainnet
• checkType=dataStorage|retrieval|sampledRetrieval|dataRetention|dataSetCreation|dataSetLifecycleCheck|pullCheck — attribute metrics to a particular check/job
• providerId — attribute metrics to a particular SP
• providerName — human-readable name of the SP (defaults to "unknown" when not available)
• providerStatus=approved|unapproved — attribute metrics to only approved SPs for example

Time Related Metrics

• All time-related metrics are emitted as histograms.
• Histogram buckets are defined in metrics-prometheus.module.ts.

Count Related Metrics

• These count metrics are used to track the occurrence of a particular status for a check.
• All Prometheus/OpenTelemetry status count metrics have additional label/attributes for:
• value - attribute counts to different outcomes.
  • Note: this is an ambiguous and confusing label/tag. It isn't to be confused with the metric counter's value. In retrospect, this should have been called something like status instead to avoid confusion with first class value term for metrics. The presence of this confusing value label causes Clickhouse metric queries to have label('value') and value_avg.
• Most of these count metrics emit a counter value of 1. Exceptions are noted below in the Counter Value column.

Other Gauges

Unlike the count metrics above, gauges below expose a level (for example overdue proving periods right now). They do not use the value outcome label. The scraped sample magnitude is the "Gauge Value" measurement.

ClickHouse Tables

When CLICKHOUSE_URL is configured, dealbot writes one row per check result to ClickHouse for long-term storage and analysis. All tables are partitioned by month with a 1-year TTL.

Source of truth: the DDL and column-level comments in clickhouse.schema.ts are authoritative. The summary below is for orientation only.

• data_storage_checks — one row written each time a deal is saved (on every status transition). Populated by deal.service.ts.
• retrieval_checks — one row per retrieval attempt. Populated by retrieval.service.ts.
• sampled_retrieval_checks — one row per Sampled Retrieval check attempt; emitted even on abort or unexpected error. Populated by sampled-retrieval.service.ts. See Sampled Retrieval § Result Recording for column-level meanings.
• data_retention_challenges — one row per provider per poll cycle. Populated by data-retention.service.ts.

All tables share the primary key (probe_location, sp_address, timestamp):

• probe_location - identifies which dealbot instance produced the row, allowing multiple deployments to be distinguished in queries (set via DEALBOT_PROBE_LOCATION)
• sp_address - the Ethereum/FEVM address of the storage provider under test
• timestamp - when the row was written (milliseconds UTC)