v0.3.13-pre.005

crates/ksp-worker-raw-transaction-ingest-lib/README.md

@@ -1,5 +1,5 @@
 <!-- file: crates/ksp-worker-raw-transaction-ingest-lib/README.md -->
-<!-- version: 4 -->
+<!-- version: 5 -->
 
 # ksp-worker-raw-transaction-ingest-lib
 
@@ -13,7 +13,7 @@ RawTransactionIngestWorker::start
 
 RawTransactionIngestWorker::start_with_runtime_resources
     -> même runtime + une source productive supervisée
-       Yellowstone, WS standard logsSubscribe ou WS standard blockSubscribe
+       Yellowstone, WS standard logsSubscribe, WS standard blockSubscribe ou Helius transactionSubscribe
        + hydration HTTP getTransaction lorsque la source produit une référence
 ```
 
@@ -39,6 +39,12 @@ Solana standard WS blockSubscribe
     -> qualification explicite Legacy / V0 / V1
     -> matériau Common RAW direct par transaction du bloc
 
+Helius transactionSubscribe
+    -> Full + Base64 + maxSupportedTransactionVersion=1 + showRewards=false
+    -> signature + slot + transactionIndex uniquement dans le signal Worker
+    -> coalescence bornée par (network, signature, commitment)
+    -> HTTP getTransaction observed avant Common RAW
+
 les chemins productifs
     -> ksp-raw-transaction-lib
     -> admission centrale bornée
@@ -70,7 +76,7 @@ La construction est sans I/O et refuse notamment :
 - une provenance provider/endpoint non représentable ;
 - l'absence d'une route HTTP compatible pour `getTransaction` sur le même réseau.
 
-Le runtime-resource aggregate public accepte une collection validée de 1 à 32 sources logiques. `pre.004` sait exécuter une source unique Yellowstone, Standard Logs ou Standard Block ; une activation simultanée de plusieurs sources reste rejetée avant spawn jusqu'au supervisor dédié. La collection interne, les `source_key`, les URLs, les filtres et les clients inférieurs ne sont pas exposés.
+Le runtime-resource aggregate public accepte une collection validée de 1 à 32 sources logiques. `pre.005` sait exécuter une source unique Yellowstone, Standard Logs, Standard Block ou Helius Transaction ; une activation simultanée de plusieurs sources reste rejetée avant spawn jusqu'au supervisor dédié. La collection interne, les `source_key`, les URLs, les filtres et les clients inférieurs ne sont pas exposés.
 
 ## Contrat de source Standard Logs + HTTP
 
@@ -104,6 +110,24 @@ La qualification est fermée : une version omise/nulle ou supérieure à `1`, un
 
 Pour un bloc multi-transaction, le slot n'est projeté settled qu'après l'admission réussie de toutes ses transactions. Cette voie RAW-direct n'incrémente pas `hydration_pending`; un stop ou une erreur au milieu du bloc ne produit aucune progression artificielle. Reconnect, resubscribe et backpressure WebSocket restent possédés par Transport.
 
+## Contrat de source Helius Transaction + HTTP
+
+`RawTransactionIngestHeliusTransactionSource::new` reçoit :
+
+```text
+WsEndpointSettings kind helius_laserstream
+HeliusTransactionSubscribeFilter
+SolanaCommitment Confirmed ou Finalized
+HttpTransportPool
+HttpRoleName d'hydration
+```
+
+La construction est sans I/O. Elle réutilise le contrat Transport existant et impose `Full`, `Base64`, `showRewards = false` et `maxSupportedTransactionVersion = 1`. Le Worker ne lit pas Config, ne lit pas `KSP_SECRET_HELIUS_API_KEY` et ne code aucun tier provider ; l'URL résolue et le credential restent dans l'endpoint Transport fourni par le caller.
+
+Au runtime, `HeliusLaserStreamWsSession::connect` puis `transaction_subscribe` sont utilisés. Seule une notification `Full` conforme au mode demandé est admise ; une forme `Signature`, `Unknown` ou future devient une faute source sûre. Le payload Helius `transaction` n'est jamais copié dans l'état Worker : la projection conserve uniquement signature, slot et transaction index, puis réutilise le coordinateur d'hydration commun `getTransaction observed`.
+
+La clé logique Helius inclut réseau, identités provider/endpoint sûres, commitment et empreinte privée du filtre. Les listes de pubkeys du filtre sont normalisées avant hash afin que leur ordre ne crée pas artificiellement deux sources logiques ; le rôle HTTP d'hydration reste exclu de l'identité live.
+
 ## Runtime et lifecycle
 
 Le Worker s'exécute sur le runtime Tokio courant du caller. Il ne crée pas de runtime global et n'expose aucun `JoinHandle` public.
@@ -121,7 +145,7 @@ Le shutdown est borné par `shutdown_drain_timeout`. Les tâches source, hydrati
 
 La queue centrale est un `tokio::sync::mpsc` privé borné par `admission_queue_capacity`. Les sources internes subissent la backpressure ; aucune queue non bornée ni silent drop n'est autorisé.
 
-Le Worker possède un coordinateur d'hydration source-neutral borné, réutilisé par Yellowstone et Standard Logs. Standard Block n'entre pas dans ce coordinateur lorsqu'une transaction est direct-qualified :
+Le Worker possède un coordinateur d'hydration source-neutral borné, réutilisé par Yellowstone, Standard Logs et Helius Transaction. Standard Block n'entre pas dans ce coordinateur lorsqu'une transaction est direct-qualified :
 
 ```text
 in-flight hydration <= persistence_concurrency
@@ -240,7 +264,7 @@ La crate ne dépend pas de Config, Job, `ksp-store-api` directement, backend Sto
 La verticale actuelle ne possède pas :
 
 - plusieurs sources productives simultanées dans `RawTransactionIngestRuntimeResources` ;
-- source `blockSubscribe`, Helius `transactionSubscribe` ou HTTP polling Worker ;
+- source HTTP live polling Worker ;
 - sélection Config interne au Worker ;
 - checkpoint persistent de processing frontier ;
 - campagne de réparation historique automatique ;