# 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 : ```text 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_onchain_transport`, 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_onchain_transport` 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_onchain_transport`, mais sa politique de campagne, son coût, sa provenance et ses fallbacks restent hors de `kb_onchain_transport`. - 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 : ```text 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 : ```text 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 : ```text 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_onchain_transport 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 : - - - ### 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 : - - ### 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 : - ### 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 : - - ### 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 : ```text 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 ```rust 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 ```rust 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 ```rust 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_onchain_transport` 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_onchain_transport`, `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.