[DBIP] Make API `historicalData` a validated retention enum

[reprocraftlatam]

Proposal type

Modify column, Other

Affected scope (files/folders/chains)

historicalData in references/offers/apis.csv, listings/all-networks/apis.csv, and listings/specific-networks/*/apis.csv; API schema/validation; the APIs wiki page.

Motivation / problem statement

The APIs column definition gives historicalData one precise job: record whether an API can query a specific historical block. It says the field is non-blank and should be Pruned, Archive, or Partial Archive; if an API is not block-oriented, it says to use Pruned.

The stored vocabulary does not currently follow that definition. At repository commit 1a386f86a416ff6a4678df09dd1c11805eae4ce0, a complete scan found 20 explicit non-empty values outside the documented set:

Value	Rows	Scope	Why it conflicts with the definition
Custom	7	canonical offers (chainbase-*, noves-*)	describes a custom product/API shape, not retention
Trace	5	canonical offers (spectrum-*-trace)	describes a trace capability/node type, not how far back blocks can be queried
Recent-State	8	Solana listings (syndica-*-recent-state)	is an undocumented synonym for the documented Pruned concept

The first two concepts already have better homes in the API model: technology and, where appropriate, apiType/availableApis. Keeping them in historicalData makes the same column alternate between retention, product type, and method capability.

This prevents reliable filtering. A consumer cannot safely answer “which APIs retain archive history?” or distinguish partial retention without treating undocumented strings as special cases. It also leaves contributors unable to follow both the wiki and the existing rows.

The existing DBIP #1058 added historical-data coverage to Analytics; it does not normalize the API field. A search of existing DBIP titles and bodies found no proposal covering these three API values.

Detailed proposal

• Category/table: apis
• Column name: historicalData
• Change type: modify (formalize the documented vocabulary and validate it)
• Updated definition: the API's queryable block-history retention class
• Value type and allowed values: enum Pruned | Archive | Partial Archive
• Examples:
  • Pruned: the API exposes only recent state or is not block-history oriented
  • Archive: the API can query back to genesis/block 0
  • Partial Archive: the API exposes historical blocks but not the complete chain history

Normalization and migration guidance:

1. Map explicit Recent-State values to Pruned; they express the same documented retention class.
2. Do not mechanically map Custom or Trace. Audit the linked official documentation for each affected offer and assign Archive, Partial Archive, or Pruned based only on verified retention behavior.
3. Preserve “custom” and trace capability in technology, apiType, or availableApis where factually supported. Those fields describe API kind/capabilities; historicalData should describe retention only.
4. Validate every explicit non-empty CSV value against the enum. A blank cell in a !offer:<slug> listing may continue to mean “inherit the canonical offer”; after reference resolution, the resulting API record must have one allowed value.
5. Document that Recent-State, Full Archive, Trace, and Custom are not alternate spellings for this field.

Acceptance criteria:

• The schema and CI accept only Pruned, Archive, or Partial Archive for resolved API records.
• Blank listing overrides remain valid only when inheritance resolves to an allowed canonical value.
• The 8 Recent-State overrides are normalized to Pruned.
• The 12 canonical Custom/Trace rows are individually verified and reclassified without inferring retention from their slugs.
• Trace/custom capability remains represented in an appropriate capability/type field where supported.
• A repository-wide scan returns zero explicit historicalData values outside the documented enum.
• Tests cover all three allowed values, an inherited blank listing value, and rejection of Recent-State, Custom, and Trace.

Audit method: every apis.csv in references/ and listings/ was parsed with PowerShell Import-Csv, and each explicit non-empty historicalData value was compared to the three values in the current wiki definition. The scan was repeated after fast-forwarding to the commit above. This proposal was prepared with automated assistance; all counts come directly from the repository and no provider's retention behavior is asserted without source verification.

Contact: GitHub @reprocraftlatam

Contact (optional)

No response

Rewards address (optional)

0x935F9988dD6039548b90841B7776c9F8C4F7757c