# The Maraventano Index — Methodology

## Observation window
Continuous since 2026-04-01. Daily rebuild at 05:23 UTC.

## Data sources
1. **Application funnel log** (per-interaction events emitted by the merchant itself): BUY_ATTEMPT, 402_ISSUED, PAYMENT_FAILED, PAYMENT_COMPLETED. This is the authoritative source for attempts and settlements.
2. **Nginx access log** (captures requests that never reach a route — this is where the conformance failure taxonomy lives, because malformed requests never reach a route handler).

## Operator classification
A "named operator" is any client whose user-agent self-identifies via a contact URL (+https://..., email, or canonical domain). Anonymous clients (bare SDK fingerprints like "node", "python-httpx", generic curl) are collapsed into an aggregate row because multiple distinct operators share these fingerprints and cannot be resolved individually without on-chain wallet clustering (planned for v2).

Operators are classified into these classes by UA regex matching:
- **monitor**: /prober|probe|monitor|healthcheck|uptime|pulse|trust|oracle|census|audit|verifier|conformance/
- **indexer**: /index|indexer|discovery|bazaar|marketplace|explorer|scanner|crawler|registry|atlas|lens/
- **payer_client**: /wallet|pay|settle|x402|mcp|agentkit/
- **training_crawler**: /claudebot|gptbot|bingbot|amazonbot|googlebot|semrush|dataforseo|ccbot|perplexity/
- **browser_or_spoofed**: /mozilla|chrome|safari/ (likely spoofed; real browsers do not transact x402)

Classification criteria are published above; operators may dispute via the contact address.

## Conformance failure taxonomy
Derived from nginx access log by pattern-matching the request path and method against:
- **literal_path_template**: path contains unsubstituted {braces}
- **method_mismatch**: 405 response to a POST on a GET-only paid route
- **index_substitution**: numeric index passed where slug expected (/buy/1)
- **unresolved_interpolation**: path contains ${} or bare $
- **slug_guessing**: iterated synonyms from app log PAYMENT_FAILED events

Each entry includes request counts and unique-IP spreads.

## Attestation
Every delivery is Ed25519-signed. Key ID: underground-attest-2026-07-18 (shared across all Index endpoints). Public key embedded in every response under verify.public_key_pem. Verification pattern:
1. Canonical-JSON the response payload section (report_card, census, corpus, etc.)
2. SHA-256 it
3. Verify it matches attestation.*_sha256 field
4. Canonical-JSON the attestation
5. Ed25519-verify signature against those bytes

## Known limits (stated honestly)
- Nginx undercounts app-level interactions; the funnel log is authoritative for attempts and settlements.
- Funnel log lines carry no per-line timestamp, so monthly shape is derived from nginx.
- Settlement counts and nginx 200-counts differ slightly; both are reported rather than reconciled.
- Self-reported user-agents are taken at face value and are trivially spoofable.
- Wallet-based lookup (?wallet=) reserved for v2 (requires on-chain correlation).
- Observation is from ONE merchant seat. Operators that never hit this merchant are not counted. v2 may add on-chain Base + Solana wallet clustering for a lower-bound ecosystem-wide count. v3 may add aggregated contributions from other merchants.

## Privacy
Raw client IPs are not published in any Index output. Named operators self-identify with public contact URLs. Anonymous clients appear only in aggregate.

## License
All Index payloads are CC0 — cite freely without attribution requirement.

## Change log
- 2026-10-02: Discovery sweep deployed (.well-known/x402 resources[], agent.json, openapi.json). Broken-client recovery handler for /buy/* catches literal_path_template failures with helpful 400 responses.
- 2026-10-03: Conformance Report Card signature pattern corrected to match other Index endpoints (sign over attestation alone; attestation commits to content via SHA-256). Network-aggregate scope now surfaces actual request counts from corpus.networks. Grading threshold lowered 20 -> 5 requests. Verify recipe added to response.
- 2026-10-03: The Maraventano Index launched at maraventanoindex.com.

## Author
Lisa Maraventano. Contact: research@maraventanoindex.com.