khadhroony-bot3/docs/CORE_STORE.md

Store core Solana

Évolution 0.3.4

Le store core historique devient alimenté par un extracteur transactionnel à partir de kb_sol_raw_transactions.canonical_json.

Table	Rôle
kb_sol_core_transactions	Transaction normalisée, statut et lien vers la ligne raw.
kb_sol_core_account_keys	Espace résolu statique + ALT avec flags Solana.
kb_sol_core_instructions	Instructions top-level et payload canonique hashé.
kb_sol_core_inner_instructions	Inner instructions rattachées à un chemin parent.
kb_sol_core_logs	Logs ordonnés, texte hashé et lien d’invocation optionnel.
kb_sol_core_balance_changes	Deltas natifs, SPL Token et Token-2022.
kb_sol_ops_processing_ledger	Version, hash, statut et tentatives du processor.

Écriture atomique

Une extraction réussie exécute dans la même transaction PostgreSQL :

1. validation du bundle ;
2. recherche d’un graphe core existant ;
3. suppression en cascade de ce graphe pour la signature ;
4. insertion de la transaction et de toutes ses lignes filles ;
5. passage de la ligne raw à core_extracted ;
6. upsert du ledger en succeeded ;
7. commit.

Une erreur déclenche le rollback implicite de la transaction. L’enregistrement terminal d’un échec utilise une transaction dédiée et marque la ligne raw failed avec un diagnostic rejouable.

Clés d’idempotence

Les contraintes actives restent :

core transaction        : signature
account key              : signature + account_index
instruction top-level    : signature + instruction_path
inner instruction        : signature + instruction_path
log                      : signature + log_index
balance change           : signature + balance_change_index
ledger                   : stage + processor_name + processor_version + input_key

Le ledger ajoute input_hash à la décision de skip sans l’ajouter à la clé unique. Un nouvel hash met à jour la même identité de processor et augmente attempt_count.

Sélection raw

Le contrat CoreExtractionSelectionFilter permet :

• une liste de signatures ;
• une plage inclusive de slots ;
• un état raw ;
• un program id déjà indexé dans les instructions core ;
• une limite stricte.

Le filtre par program id est un mode de replay. Il ne peut pas découvrir un programme dans une transaction qui n’a jamais encore été extraite.

Repositories

CoreExtractionStore isole le pipeline du backend :

list_raw_transactions_for_core_extraction
is_core_extraction_current
persist_core_extraction
mark_core_extraction_failed

Les repositories historiques d’insertion unitaire restent disponibles, mais le worker 0.3.4 utilise exclusivement l’écriture atomique du bundle.