khadhroony-solana-project/docs/architecture/009-ACQUISITION_WORKERS_AND_JOBS.md

Acquisition, workers, jobs et pipelines spécialisés

Objet

Ce document définit le lifecycle opérationnel autour des couches :

RAW -> CORE -> DECODE -> SPECIALIZED

Il conserve la séparation stricte entre :

• pipeline/processor : logique réutilisable d'une transformation ;
• worker : service continu/live ;
• job : traitement borné/historique/replay ;
• application : contrôle/visualisation, sans duplication de la logique métier.

Règle de progression

RAW et CORE sont les deux premières couches horizontales. Elles ne nécessitent aucun decoder Program.

Pour chacune, KSP peut terminer successivement :

persistence
-> backfill/replay
-> worker live si nécessaire
-> application de contrôle/inspection si utile

À partir de DECODE, les processors/jobs/workers/scenarios sont introduits avec le groupe Program concerné, en vertical slice, au lieu de créer à l'avance une grande flotte générique de workers de décodage/materialisation sans programme réel.

RAW

Pipeline RAW ingestion

Concept :

homogeneous transport model
        |
        v
conversion RAW DTO
        |
        v
ksp-store-api
        |
        v
persistence D1 RAW
        |
        v
notification after commit

Une crate spécialisée ksp-pipeline-raw-ingestion-lib peut être introduite lorsque la réutilisation worker + job le justifie réellement.

Elle ne choisit pas le provider réseau et ne pilote pas le range historique.

ksp-job-backfill

Le premier backfill historique appartient à la couche RAW :

range/cursor historique
        |
        v
ksp-onchain-transport-lib
        |
        v
RAW ingestion
        |
        v
D1 RAW

Le job :

• utilise ksp-job-api pour son lifecycle ;
• gère scope/range/pagination/checkpoint ;
• n'effectue aucun décodage Program ;
• n'écrit pas directement des faits CORE/DECODE/SPECIALIZED.

Worker RAW live

Le worker live futur :

subscriptions/fetch live
        |
        v
ksp-onchain-transport-lib
        |
        v
RAW ingestion
        |
        v
D1 RAW

Il ne décode pas et ne matérialise pas.

Sa hot reconfiguration peut concerner selon le transport :

• endpoints/providers ;
• rôles ;
• accounts/program IDs suivis ;
• types de subscriptions ;
• filtres ;
• limites/concurrence.

La configuration desired/effective reste distinguée lorsqu'une reconfiguration est asynchrone.

CORE

Pipeline RAW -> CORE

La normalisation CORE est générique Solana :

D1 RAW
   |
   v
Solana generic normalizer
   |
   v
D2 CORE

Dépendances interdites :

CORE normalizer -X-> ksp-program-api
CORE normalizer -X-> ksp-program-lib
CORE normalizer -X-> ksp-materializer-api

ksp-interface-lib peut fournir les wires Solana génériques nécessaires à la structure blockchain.

Job replay CORE

Un job borné peut rejouer :

RAW persisted range
        |
        v
CORE normalizer
        |
        v
D2 CORE

sans redemander les données au réseau.

Worker CORE

Un worker CORE continu peut consommer le backlog RAW nouvellement persisté et produire CORE.

Le Store reste source de vérité du backlog ; les notifications ne sont qu'un wake-up.

DECODE et SPECIALIZED

Introduction par groupe fonctionnel

KSP ne crée pas d'abord un unique « worker decoder de tout Solana » puis tous les materializers plusieurs séries plus tard.

Chaque groupe prioritaire introduit les capacités nécessaires :

CORE inputs du groupe
      |
      v
Program decoder
      |
      v
decoded facts
      |
      v
generic materialization / DECODE persistence
      |
      v
SPECIALIZED projection si utile

Puis le même groupe avance vers préparation d'exécution, policy, execution et scénarios Devnet.

Les jobs de replay et workers live correspondants réutilisent les mêmes processors du groupe.

Ordre fonctionnel

Direction actuelle :

Solana Core Programs
-> SPL token/trading
-> token metadata
-> Anchor
-> Meteora
-> Raydium
-> Pump
-> Orca
-> Market Desk V1
-> Jupiter / OKX routing
-> Market Desk V2
-> trading-adjacent
-> general decoding

Un satellite protocolaire reste avec son groupe : Meteora vaults avec Meteora, Pump fee avec Pump, etc.

Worker API

ksp-worker-api reste une lifecycle API générique pour services continus.

Concepts candidats :

WorkerId
WorkerDescriptor
WorkerState
WorkerHealth
WorkerCapabilities

Opérations minimales candidates :

start
stop
status
health

Une capability comme reconfigure n'est pas imposée à tous les workers.

Job API

ksp-job-api reste distinct de Worker API.

Concepts candidats :

JobId
JobDescriptor
JobState
JobProgress
JobOutcome
JobCapabilities

Un job est borné/terminable et peut exposer selon besoin :

start
pause
resume
cancel
status
progress

Les types exacts sont décidés à 0.3.3 avec le premier vrai backfill.

Aucune ksp-job-control-lib n'est créée sans duplication concrète.

Backlog, claim et idempotence

Pour les processors asynchrones :

notification wake-up
      +
periodic polling
      |
      v
Store backlog query
      |
      v
claim/lease bounded batch
      |
      v
processor
      |
      v
output + durable outcome

Les notifications ne remplacent jamais le Store.

La sémantique cible reste at-least-once avec idempotence durable, plutôt qu'un faux exactly-once.

Processing outcomes

Les états exacts seront définis avec le premier processor durable, mais doivent distinguer au minimum les familles conceptuelles :

• success ;
• transient failure ;
• deterministic failure ;
• not applicable ;
• unsupported ;
• superseded/replayed lorsque pertinent.

Reprise après crash

Un worker/job doit reconstruire son état depuis :

• inputs persistés ;
• claims/leases ;
• outcomes ;
• cursors/checkpoints ;
• versions de processor.

La mémoire du processus ne constitue jamais l'unique source de reprise.

Logging

Tous les pipelines/workers/jobs runtime utilisent ksp-logging-lib.

Les événements utiles comprennent notamment :

• start/stop ;
• batch/range ;
• progression ;
• retries ;
• claim/lease ;
• rate-limit/backpressure ;
• processing outcome ;
• checkpoint ;
• reconfiguration desired/effective ;
• erreurs redacted.

Dépendances de composition

RAW backfill

ksp-job-backfill
    -> ksp-job-api
    -> ksp-onchain-transport-lib
    -> ksp-store-api / backend injecté
    -> ksp-config-lib       # orchestration/config, pas ownership transport
    -> ksp-logging-lib

RAW worker

ksp-worker-raw-retriever
    -> ksp-worker-api
    -> ksp-onchain-transport-lib
    -> ksp-store-api / backend injecté
    -> ksp-config-lib
    -> ksp-logging-lib

CORE replay/worker

CORE processor
    -> ksp-interface-lib si wires génériques nécessaires
    -> ksp-store-api
    -> ksp-core-lib
    -> ksp-logging-lib

Pas de Program API.

Groupes DECODE/SPECIALIZED

Le composant de composition du groupe peut utiliser :

ksp-program-api
ksp-program-lib ou extension compatible
ksp-materializer-api
ksp-materializer-lib ou implementation compatible
ksp-store-api

selon les capacités réellement introduites.

Questions laissées ouvertes

• nom final de la crate pipeline RAW si la réutilisation justifie une crate dédiée ;
• nom final du worker RAW ;
• contrat exact de ksp-job-api ;
• modèle de claim/lease PostgreSQL ;
• taille de batch et stratégie backpressure ;
• découpage des workers DECODE/SPECIALIZED par groupe lorsque les premiers groupes existent ;
• mécanisme IPC des applications de contrôle futures.