khadhroony-bot3/docs/HISTORICAL_DATA_ACQUISITION_PLAN.md

Plan différé — acquisition historique gratuite et worker de campagnes

Statut

Ce document conserve un projet futur volontairement retiré du ROADMAP.md actif.

Aucune version n'est attribuée à ce chantier. Il ne doit pas retarder les décodeurs, matérialisateurs et exécuteurs Solana Core, SPL, AMM, launchpads, orderbooks, routers ou autres surfaces prioritaires.

Le nom W2 est provisoire. Il désigne ici un worker manuel d'acquisition historique, distinct du worker temps réel destiné au trading. Le nom final des crates et binaires sera décidé au moment de l'activation du chantier.

1. Motivation

Le projet aura besoin de deux voies d'acquisition complémentaires :

W1 — temps réel
  -> fournisseurs fiables ou payants
  -> faible latence
  -> détection de créations de tokens, pools et pairs
  -> changements de prix/liquidité
  -> déclencheurs d'achat, vente et gestion du risque

W2 — historique manuel
  -> sources gratuites ou très économiques
  -> campagnes lentes et reprenables
  -> corpus vieux d'un an, deux ans ou davantage
  -> données destinées à l'analyse, aux tests et à la détection de patterns
  -> aucune consommation implicite du budget réservé au trading

W2 ne remplace ni kb_rpc, ni le pipeline canonique, ni les fournisseurs temps réel. Il sert à alimenter progressivement PostgreSQL avec des données historiques dont la latence n'est pas critique.

2. Principes non négociables

• kb_rpc reste la frontière des protocoles Solana : JSON-RPC HTTP/WS standard, extensions fournisseur officiellement prises en charge, Yellowstone/gRPC et transports similaires.
• Une source historique parlant JSON-RPC standard peut réutiliser kb_rpc, mais sa politique de campagne, son coût, sa provenance et ses fallbacks restent hors de kb_rpc.
• Les APIs REST indexées, exports, datasets analytiques, archives CAR ou outils externes appartiennent à des crates de sources historiques séparées.
• W2 fonctionne en free_only par défaut. Aucun fournisseur payant ne doit être interrogé sans autorisation explicite de la campagne.
• Les endpoints et crédits de W1 ne doivent jamais être utilisés comme fallback silencieux de W2.
• Toute donnée destinée au pipeline doit finir par être normalisée dans le contrat canonique existant.
• Une source externe peut découvrir une signature, un slot ou un candidat ; elle ne devient pas pour autant la source canonique de la transaction.
• Les campagnes doivent être bornées, annulables, reprenables, dédupliquées et auditées.
• Une page vide ou une réponse null provenant d'une source best-effort ne prouve pas nécessairement l'absence historique de la donnée.

3. Séparation découverte / hydratation

W2 doit séparer deux responsabilités.

3.1 Découverte

Trouver des candidats à partir de :

• adresses ou Program IDs ;
• signatures explicites ;
• plages de slots ou périodes ;
• pools, vaults ou token accounts ;
• programmes DEX/launchpads ;
• datasets indexés capables de filtrer par comptes, instructions ou timestamps.

3.2 Hydratation

Récupérer la transaction ou le bloc brut correspondant, puis suivre le pipeline existant :

candidate
  -> transaction ou bloc brut
  -> insertion raw canonique
  -> core extraction
  -> decode replay
  -> materialization
  -> agrégations et corpus d'analyse

La source de découverte et la source d'hydratation peuvent être différentes.

Exemple :

BigQuery découvre les signatures d'une période
  -> Old Faithful hydrate les anciennes transactions
  -> un RPC public hydrate les transactions encore disponibles
  -> PostgreSQL ignore les signatures déjà présentes
  -> aucun crédit Helius n'est consommé

4. Architecture candidate

Les noms ci-dessous sont provisoires et ne constituent pas encore des réservations de crates :

kb_historical_api
  -> capacités, campagnes, candidats, provenance, coût et complétude

kb_historical_source_rpc
  -> profils RPC publics/best-effort utilisant les contrats de kb_rpc

kb_historical_source_old_faithful
  -> intégration avec un processus faithful-cli externe ou une archive locale

kb_historical_source_bigquery
  -> découverte indexée par requêtes analytiques bornées

kb_historical_source_solscan
  -> API officielle optionnelle, avec clé et budget explicites

kb_worker_historical
  -> orchestration manuelle, reprise, quotas, déduplication et import canonique

Une alternative consiste à garder les contrats et l'orchestration dans des modules internes d'une crate plus compacte. Ce choix devra être tranché après les prototypes et mesures, pas avant.

5. Sources candidates

5.1 RPC utilisé par l'Explorer Solana

L'Explorer officiel repose sur des appels JSON-RPC Solana standards. Une source rpc_best_effort peut donc utiliser des endpoints publics ou communautaires pour :

• getSignaturesForAddress ;
• getTransaction ;
• getBlocks ;
• getBlock ;
• réparations ciblées par signature ou slot.

Cette source convient aux campagnes étroites et lentes. Elle n'offre pas de SLA, d'index arbitraire ni de garantie de rétention complète. Le site HTML ne doit pas être scrapé.

Références de recherche :

• https://github.com/solana-foundation/explorer
• https://solana.com/docs/rpc/http/getsignaturesforaddress
• https://solana.com/docs/rpc/http/gettransaction

5.2 Old Faithful

Old Faithful est la piste prioritaire pour l'histoire profonde. L'intégration initiale doit privilégier un processus externe faithful-cli ou un serveur JSON-RPC local, afin d'éviter un couplage prématuré au format CAR, à l'implémentation Go et à sa licence.

Usages visés :

• hydratation de transactions anciennes ;
• scans bornés par époque ou slots ;
• constitution progressive d'un corpus local durable ;
• fallback gratuit lorsque les RPC récents ont purgé les données.

Références de recherche :

• https://github.com/rpcpool/yellowstone-faithful
• https://docs.triton.one/project-yellowstone/old-faithful-historical-archive

5.3 BigQuery ou dataset analytique équivalent

Un dataset indexé peut servir de moteur de découverte et réduire massivement le nombre d'appels RPC. Il doit être évalué pour :

• schéma et fraîcheur ;
• instructions outer/inner disponibles ;
• comptes et balances pré/post ;
• précision des filtres ;
• coût réel des requêtes ;
• capacité à exporter des signatures et slots de manière reprenable.

Il ne remplace pas PostgreSQL ni le pipeline canonique.

Référence de recherche :

• https://cloud.google.com/blockchain-analytics/docs/supported-datasets

5.4 Solscan

Solscan fournit un index fonctionnellement intéressant, mais l'intégration durable doit utiliser uniquement son API officielle et respecter ses quotas et conditions.

Cette source serait :

• optionnelle ;
• désactivée par défaut ;
• configurée par clé ;
• classée free_quota ou paid selon le plan ;
• interdite dans une campagne free_only si elle entraîne un coût.

Les endpoints privés du site, cookies, jetons internes et scraping HTML ne doivent pas être utilisés.

Références de recherche :

• https://solscan.io/apis
• https://pro-api.solscan.io/pro-api-docs/v2.0

5.5 Fournisseurs payants

Helius, Shyft, Chainstack, Triton ou équivalents peuvent être ajoutés ultérieurement comme fallback explicitement autorisé. Ils ne doivent pas être activés dans la politique par défaut de W2 et ne doivent jamais consommer les crédits de W1 à l'insu de l'opérateur.

6. Stablecoins et corpus de marché

Une campagne naïve getSignaturesForAddress(MINT) ne suffit pas à reconstruire toute l'activité d'un stablecoin. Les transferts classiques peuvent référencer les token accounts sans inclure systématiquement le mint dans les comptes de l'instruction.

Pour constituer des séries utiles à un analyseur de patterns, la stratégie prioritaire doit être :

stablecoin
  -> pools et pairs pertinents
  -> vaults et token accounts des pools
  -> Program IDs des AMM/CLMM/DLMM/routers
  -> transactions candidates
  -> décodage des swaps et changements de liquidité
  -> matérialisation trades/pools
  -> bougies et séries temporelles

Les transferts génériques du token restent un corpus séparé, beaucoup plus volumineux et moins directement utile au prix.

7. Contrats fonctionnels candidats

7.1 Capacités

pub struct HistoricalSourceCapabilities {
    pub signatures_by_address: bool,
    pub transactions_by_signature: bool,
    pub blocks_by_slot: bool,
    pub slot_ranges: bool,
    pub time_ranges: bool,
    pub program_filter: bool,
    pub token_filter: bool,
    pub instruction_filter: bool,
    pub indexed_results: bool,
    pub full_history: bool,
}

7.2 Budget

pub enum HistoricalSourceCost {
    Free,
    FreeQuota,
    Paid,
}

pub enum HistoricalBudgetPolicy {
    FreeOnly,
    FreeThenPaid,
    ExplicitSourcesOnly,
}

FreeOnly doit être la valeur de départ de toute campagne manuelle.

7.3 Complétude et provenance

pub enum HistoricalCompleteness {
    Complete,
    Partial,
    Unknown,
    Pruned,
}

pub struct HistoricalProvenance {
    pub source_name: String,
    pub source_kind: String,
    pub method: String,
    pub fetched_at_unix_ms: i64,
    pub paid: bool,
}

Les types définitifs devront respecter les conventions du workspace, les bornes PostgreSQL et les règles TS-rs si une UI est ajoutée.

8. Campagnes et observabilité

Une campagne doit conserver au minimum :

• identifiant stable ;
• cible et filtres ;
• source de découverte et source d'hydratation ;
• politique de coût ;
• curseur et checkpoint de reprise ;
• plage temporelle ou de slots ;
• concurrence, rate limit et backoff ;
• candidats découverts ;
• signatures déjà présentes ;
• transactions hydratées, absentes, pruned ou invalides ;
• erreurs et fallbacks ;
• volume réseau et coût estimé ;
• état running, paused, cancelled, completed ou failed.

Les événements tracing doivent être émis par les crates responsables. Les secrets, clés API, payloads complets non bornés et URLs contenant des credentials sont interdits dans les logs.

9. Étude préalable obligatoire

Avant toute activation dans le ROADMAP, exécuter un benchmark reproductible avec :

• une transaction récente ;
• une transaction vieille d'environ un an ;
• une transaction vieille d'environ deux ans ;
• une adresse peu active ;
• un Program ID très actif ;
• un pool stablecoin ;
• une plage de slots bornée.

Mesurer pour chaque source :

• profondeur historique ;
• taux de réponse null ou pruned ;
• cohérence de pagination ;
• latence et débit soutenable ;
• limitations et Retry-After ;
• filtres disponibles ;
• complétude des transactions et métadonnées ;
• coût ;
• conditions d'utilisation ;
• capacité de reprise et stabilité du contrat.

10. Phases futures sans numéro de version

Phase R0 — recherche

• valider les sources, licences, conditions d'utilisation, coûts et corpus ;
• produire une matrice comparative et un prototype jetable ;
• choisir le nom final de W2.

Phase R1 — contrats et ledger de campagne

• définir les capacités, budgets, candidats, provenance et checkpoints ;
• ajouter les migrations PostgreSQL seulement après stabilisation du contrat.

Phase R2 — source RPC gratuite

• réutiliser kb_rpc pour les méthodes standards ;
• ajouter quotas, backoff, déduplication et frontières de complétude.

Phase R3 — archive profonde

• intégrer faithful-cli comme processus externe ou service local ;
• valider les imports par époque/slots et la cohérence avec le canonique.

Phase R4 — découverte indexée

• intégrer BigQuery ou une source analytique équivalente après benchmark ;
• exporter uniquement les candidats nécessaires.

Phase R5 — sources commerciales facultatives et UI

• ajouter Solscan ou d'autres APIs officielles avec budget explicite ;
• ajouter une UI de campagne manuelle seulement lorsque les contrats backend sont stables.

11. Conditions avant retour dans le ROADMAP

Ce chantier ne revient dans le ROADMAP.md que lorsque :

• les décodeurs/matérialisateurs/exécuteurs prioritaires ont suffisamment progressé ;
• au moins deux sources gratuites ont été testées réellement ;
• une stratégie de licence et de conditions d'utilisation est validée ;
• la frontière avec kb_rpc, kb_pipeline et PostgreSQL est décidée ;
• la politique free_only est testable et empêche réellement tout fallback payant ;
• un prompt de session dédié peut être écrit sans hypothèse majeure non vérifiée.