19 KiB
Graphe de dépendances KSP
Objet
Ce document décrit les directions de dépendances retenues. Il complète les règles de naming/API et le plan de progression fonctionnelle.
Principes structurants
APIs sous les implémentations
ksp-program-api <- ksp-program-lib / external program libs
ksp-materializer-api <- ksp-materializer-lib / external materializers
ksp-store-api <- ksp-store-lib / alternative backends
ksp-worker-api <- concrete workers / control adapters
ksp-job-api <- concrete jobs
Une crate *-api est créée uniquement lorsqu'un vrai besoin d'extension/backend/lifecycle le justifie.
Transformations séparées de l'I/O
Transport, persistence, Program decoding, materialization et execution restent séparés.
Composition supérieure
Les applications/jobs/workers/scenarios composent les implementations concrètes. Les couches basses ne dépendent pas de leurs consommateurs.
Workers et jobs distincts
Workers continus et jobs bornés gardent des lifecycle APIs séparées.
Fondations N1
ksp-core-lib
ksp-logging-lib
-> ksp-core-lib
ksp-config-lib
-> ksp-core-lib
-> ksp-logging-lib
ksp-logging-lib est la façade unique de tracing KSP.
ksp-config-lib est l'unique propriétaire des documents Config, .env et variables KSP/KSPB.
Transport on-chain
ksp-onchain-transport-lib
-> ksp-core-lib
-> ksp-logging-lib
-> external HTTP/WS/gRPC crates réellement nécessaires
Interdictions :
ksp-onchain-transport-lib -X-> ksp-config-lib
ksp-onchain-transport-lib -X-> ksp-store-api
ksp-onchain-transport-lib -X-> ksp-store-lib
ksp-onchain-transport-lib -X-> ksp-program-api
ksp-onchain-transport-lib -X-> ksp-program-lib
Le transport possède ses settings publics runtime.
Lorsque Config fournit un document standard Transport :
ksp-config-lib
-> ksp-onchain-transport-lib # adapter vers les contrats publics Transport
ksp-onchain-transport-lib
-X-> ksp-config-lib
Cette direction est analogue à Config -> Logging : Config exprime/adapte la configuration, le composant reste propriétaire de ses contrats runtime.
HTTP
HttpEndpointConfig
HttpRoleConfig
HttpEndpointPool
|
v
JSON-RPC read/write methods
Le pool HTTP sélectionne des endpoints/clients logiques selon rôles/capabilities/priorités/limites.
WebSocket
WsEndpoint
1 -> N WsSession
WsSession
1 -> N WsSubscription
Plusieurs sessions sur une même URL sont autorisées. Un scheduler/pool automatique de sessions n'est pas imposé tant qu'un besoin réel ne le justifie pas.
Helius LaserStream WebSocket étend le même moteur/session ; il ne duplique pas le client standard.
Yellowstone
Yellowstone gRPC est un backend standard/provider-neutral. Les adapters/capabilities Helius/Triton/ERPC/Chainstack/Shyft peuvent venir plus tard sans redéfinir le contrat générique.
Transport off-chain
ksp-offchain-transport-lib
-> ksp-core-lib
-> ksp-logging-lib
-> reqwest
-> serde / serde_json
-> tokio
Aucune ksp-offchain-transport-api globale n'est prévue.
La première surface 0.2.11 est SOL/USD uniquement et peut être servie par plusieurs adapters REST. Aucun SDK provider n'est ajouté : les DTOs wire restent privés et les origines provider V1 sont fixes. La crate possède le registry, les capacités/rate limits, les cooldowns, l'état d'indisponibilité et les refresh individuel/multiple.
ksp-offchain-transport-lib -X-> ksp-config-lib
ksp-offchain-transport-lib -X-> ksp-onchain-transport-lib
ksp-offchain-transport-lib -X-> provider SDKs
Config peut dépendre d'Off-chain Transport pour adapter un document standard vers ses settings publics. Metadata HTTP/IPFS/Arweave et autres besoins sont ajoutés lorsqu'ils deviennent concrets.
Wallet
ksp-wallet-lib
-> ksp-core-lib # Pubkey/Error/Result
-> ksp-logging-lib # observabilité KSP
-> argon2 / chacha20poly1305 # KDF + AEAD
-> getrandom / zeroize # CSPRNG + secret memory
-> ed25519-dalek # autorité d'état OWNER
-> solana-keypair # keypair Solana encapsulée
-> serde / serde_json # wire JSON V1
-> tempfile / tokio # persistence + spawn_blocking
ksp-core-lib::Pubkey reste le type public transversal. solana-keypair est volontairement possédée directement par Wallet : elle contient le secret et la capacité de signature, n'est pas réexportée et n'est pas remontée dans Core par anticipation.
Interdictions :
ksp-wallet-lib -X-> ksp-config-lib
ksp-wallet-lib -X-> ksp-onchain-transport-lib
ksp-wallet-lib -X-> ksp-execution-policy-api
ksp-wallet-lib -X-> Tauri / Store
ksp-wallet-lib -X-> tracing direct / std::env
ksp-wallet-lib -X-> solana-pubkey direct
ksp-wallet-lib -X-> solana-signer / solana-signature direct
Le Wallet stocke/ouvre/signe. Il ne décide pas si une dépense est autorisée.
WalletPolicy historique migre conceptuellement vers execution policy, pas vers ksp-wallet-lib.
Interface / contrats passifs
ksp-interface-lib
-> ksp-core-lib
-> official/compatible wire dependencies uniquement lorsqu'un protocole réel les exige
ksp-interface-lib contient la façade wire officielle et les contrats passifs KSP-owned dont la sémantique est réellement partagée, y compris des faits d'acquisition provider-neutral. Les composants Program et les composants de composition peuvent consommer ces contrats sans importer un runtime Transport.
Un événement passif n'autorise aucune dépendance Interface vers Transport, Store, worker/job ou logging runtime. Les converters depuis des DTOs Transport restent dans la composition.
Aucune ksp-interface-api séparée n'est retenue actuellement.
Interdictions :
ksp-interface-lib -X-> ksp-program-api
ksp-interface-lib -X-> ksp-program-lib
ksp-interface-lib -X-> transport
ksp-interface-lib -X-> Store
ksp-interface-lib -X-> Wallet
Program
ksp-program-api
-> ksp-core-lib
-> ksp-interface-lib si types wire publics communs nécessaires
ksp-program-lib
-> ksp-program-api
-> ksp-interface-lib
-> ksp-core-lib
-> ksp-logging-lib
Une extension externe :
ksp-program-<name>-lib
-> ksp-program-api
-> ksp-interface-lib si interface officielle disponible
Elle n'a pas besoin de dépendre de ksp-program-lib.
Execution / Policy
ksp-execution-policy-api
-> ksp-core-lib
ksp-execution-lib
-> ksp-program-api
-> ksp-execution-policy-api
-> ksp-wallet-lib
-> ksp-onchain-transport-lib
-> ksp-core-lib
-> ksp-logging-lib
Interdiction structurante :
ksp-execution-lib -X-> ksp-program-lib
Une petite policy spécifique peut vivre dans une crate scenario/orchestrateur. Une ou plusieurs bibliothèques de policies communes ne sont créées qu'après démonstration d'une réutilisation réelle.
Data plane durable
D1 RAW
-> D2 STRUCTURAL
-> D3 DECODED
-> D4 DOMAIN
RAW
La canonicalisation RawTransaction source-neutral est une lower layer explicite, séparée du Transport et de la persistence runtime :
ksp-raw-transaction-lib
-> ksp-store-api
-> ksp-core-lib
-> base64 / serde_json / sha2
Interdictions :
ksp-raw-transaction-lib -X-> ksp-onchain-transport-lib
ksp-raw-transaction-lib -X-> ksp-store-lib
ksp-raw-transaction-lib -X-> ksp-job-api / ksp-job-backfill-lib
ksp-raw-transaction-lib -X-> ksp-worker-api / concrete workers
ksp-raw-transaction-lib -X-> Config / runtime async / backend Store
Le flux de composition devient :
transport model / fixture source-neutral
|
v
producer adapter
|
v
ksp-raw-transaction-lib
|
+--> RawTransaction + RawTransactionObservation (types ksp-store-api)
|
v
producer concret
|
v
ksp-store-lib
Le Job Backfill et le Worker RAW peuvent donc partager exactement la canonicalisation et le wire sans que la common crate possède le runtime, le Transport ou le backend.
STRUCTURAL
D1 RAW
|
v
Solana generic normalizer
|
v
D2 STRUCTURAL
Le normalizer STRUCTURAL peut utiliser ksp-interface-lib pour des wires Solana génériques.
Interdictions :
RAW -> STRUCTURAL -X-> ksp-program-api
RAW -> STRUCTURAL -X-> ksp-program-lib
RAW -> STRUCTURAL -X-> ksp-materializer-api
DECODED
D2 STRUCTURAL
|
v
ksp-program-api implementation
|
v
decoded facts
|
v
ksp-materializer-api implementation
|
v
D3 DECODED / generic journal
DOMAIN
D3 DECODED
|
v
specialized projector/materializer
|
v
D4 DOMAIN
Materialization
ksp-materializer-api
-> ksp-core-lib
ksp-materializer-lib
-> ksp-materializer-api
-> ksp-core-lib
-> ksp-logging-lib
Program/Materializer ne dépendent pas du Store backend.
Store
ksp-store-api
-> ksp-core-lib
ksp-store-lib
-> ksp-store-api
-> ksp-core-lib
-> ksp-logging-lib
-> ksp-store-postgres-lib # feature postgres par défaut, optionnelle au build
ksp-store-postgres-lib
-> ksp-store-api
-> ksp-core-lib
-> ksp-logging-lib
-> PostgreSQL dependencies
Interdictions :
ksp-store-api -X-> transport/program/materializer
ksp-store-lib -X-> transport/program/materializer
ksp-store-postgres-lib -X-> ksp-store-lib
worker/job -X-> ksp-store-postgres-lib
La première release Store (0.3.1) est RAW-only ; les contrats STRUCTURAL/DECODED/DOMAIN sont ajoutés avec leurs couches. Les consumers runtime ordinaires (jobs, workers, apps) utilisent ksp-store-lib; ils ne sélectionnent ni n'importent directement ksp-store-postgres-lib ou un autre backend.
Jobs
ksp-job-api
-> ksp-core-lib
Premier job concret :
ksp-job-backfill-lib
-> ksp-job-api
-> ksp-core-lib
-> ksp-logging-lib
-> ksp-onchain-transport-lib
-> ksp-raw-transaction-lib # canonicalisation/wire RAW v1 partagés
-> ksp-store-lib # default-features = false ; aucun backend imposé
-> futures-util / tokio # runtime privé du job, jamais dans ksp-job-api
-> serde_json / sha2 # usages résiduels propres au job tant qu'ils existent
Il remplit RAW et ne décode aucun programme. Il ne dépend pas de Config : la composition supérieure construit explicitement Transport, Store et BackfillRequest. Le réseau appartient au scope/à l'identité durable (network, signature) ; rôle, provider, endpoint et protocole restent des choix ou provenances d'acquisition et ne deviennent jamais une clé de transaction.
ksp-job-api ne dépend en retour d'aucun runtime ou domaine concret. ksp-job-backfill-lib ne dépend ni directement de ksp-store-api, ni de ksp-store-postgres-lib; la façade Store demeure l'unique frontière runtime de persistance.
Workers
ksp-worker-api
-> ksp-core-lib
ksp-worker-raw-transaction-ingest-lib # fondation + acquisition live multi-source matérialisées
-> ksp-core-lib
-> ksp-logging-lib
-> ksp-onchain-transport-lib # Yellowstone, WS standard/Helius et HTTP observed/polling
-> ksp-raw-transaction-lib
-> ksp-store-lib # default-features = false ; aucun backend imposé
-> ksp-worker-api
-> sha2 / tokio # observation key + runtime privé
ksp-worker-control-lib # composant retenu, non matérialisé ici
-> ksp-worker-api
-> ksp-core-lib
ksp-worker-api est ouvert en 0.3.9 comme contrat générique de services continus et ne connaît ni Solana, ni Transport, ni Store, ni Tauri. ksp-worker-raw-transaction-ingest-lib est son premier consumer concret : sa fondation 0.3.11 possède admission/persistence/snapshots/shutdown ; 0.3.12 ouvre la première verticale Yellowstone + hydration HTTP ; 0.3.13 matérialise la composition live multi-source ; 0.3.14 ferme la continuité run-local par gaps bornés, preuves de coverage, repair conservatif, health gap-aware et shutdown/fairness durcis. Config et le backend physique restent hors du Worker.
La verticale actuelle n'est ni « un worker WebSocket » ni un moteur historique : RawTransactionIngestRuntimeResources contient de 1 à 32 sources logiques validées d'un même réseau parmi cinq familles — Yellowstone, Standard WS logsSubscribe, Standard WS blockSubscribe, Helius transactionSubscribe et HTTP live block polling. Yellowstone, Standard Logs et Helius convergent vers une registry globale d'hydration HTTP getTransaction; Standard Block et HTTP Block Polling qualifient directement le wire Base64 Legacy/V0/V1 vers Common RAW. Toutes les acquisitions rejoignent la même admission/persistence, la convergence canonique (network, signature) et des observations distinctes par provenance. Reconnect, from_slot, replay natif et retries réseau restent propriétaires de Transport. Le Worker observe leurs preuves sûres, maintient processing/continuity frontiers distinctes, réconcilie uniquement des gaps du run courant avec coverage explicite et mécanismes bornés, et n'appelle jamais le Job Backfill. Une source perdue ne peut rester absente que si sa perte passée est réconciliée et si les sources restantes prouvent encore tout le TargetCoverage futur.
RAW worker puis STRUCTURAL worker sont introduits à la fin de leur couche respective, lorsque persistence/backlog sont disponibles. Le traitement RAW -> STRUCTURAL borné est porté par un STRUCTURAL job distinct du service continu. Les workers DECODED/DOMAIN sont introduits avec les groupes Program concernés plutôt que tous anticipés en bloc.
Apps
Wallet Desk
ksp-app-wallet-desk
-> ksp-config-lib
-> ksp-wallet-lib
-> ksp-onchain-transport-lib
-> ksp-offchain-transport-lib
-> ksp-logging-lib
L'app compose ; elle ne déplace pas Config/Wallet/Transport dans Tauri. Les handles WalletView/WalletOwner restent côté Rust, et le frontend ne reçoit que des DTOs sûrs. Config fournit la racine/profil Wallet, le profil Transport et le profil Off-chain Transport. Le refresh de balance peut composer une moyenne SOL/USD et un équivalent USD auxiliaires à partir des observations génériques du refresh courant sans introduire de provider concret dans Wallet Desk. Les passwords Wallet ne deviennent jamais des champs des documents JSON Config ; ils peuvent être saisis éphémèrement frontend -> Rust ou provenir plus tard de secrets process/.env KSP_SECRET_WALLET_PASS_* possédés exclusivement par Config. Le secret Solana ne devient jamais une valeur Config ni un DTO frontend.
SOL Prices Desk
ksp-app-solprices-desk
-> ksp-config-lib
-> ksp-offchain-transport-lib
-> ksp-logging-lib
L'application est une HID pure. Elle ne dépend d'aucun SDK provider, ne construit aucune requête HTTP provider et ne connaît ni endpoint, ni credential, ni limite provider. Les rows et actions de refresh sont alimentées par les descriptors/états/opérations génériques de ksp-offchain-transport-lib.
Backfill Desk
ksp-app-backfill-desk
-> ksp-core-lib
-> ksp-config-lib
-> ksp-job-api
-> ksp-job-backfill-lib
-> ksp-logging-lib
-> ksp-onchain-transport-lib
-> ksp-store-lib
La Desk compose les ressources et contrôles du job sans traverser la façade Store : aucune dépendance directe à ksp-store-api, ksp-store-postgres-lib, tokio-postgres, reqwest, tonic ou yellowstone-grpc-proto. Le frontend ne connaît que des rôles HTTP logiques et des DTOs sûrs ; endpoints, credentials, backend Store, RAW et checkpoint concret restent sous les composants Rust propriétaires.
RAW Transaction Ingest Desk
ksp-app-raw-transaction-ingest-desk
-> ksp-config-lib
-> ksp-core-lib
-> ksp-logging-lib
-> ksp-worker-api
-> ksp-worker-raw-transaction-ingest-lib
-> ksp-onchain-transport-lib
-> ksp-store-lib
La Desk sélectionne et supervise les stratégies d'acquisition exposées par le worker et par la composition Config/Transport. Elle peut activer plusieurs sources lorsqu'elles sont compatibles, mais ne reconstruit ni discovery, ni hydration, ni déduplication, ni provenance dans Tauri/TypeScript. Les endpoints, credentials, capacités provider et handles Transport/Store restent Rust-owned.
Store Desk
ksp-app-store-desk
-> ksp-config-lib
-> ksp-core-lib
-> ksp-logging-lib
-> ksp-store-lib
Store Desk est un consumer read-only de la façade Store. Il ne dépend pas directement de ksp-store-api, ksp-store-postgres-lib ou tokio-postgres, ne possède aucun SQL et n'ouvre aucun Transport. Les capabilities d'inspection random-access alimentent les DataTables server-side ; les reads par identité alimentent les détails bornés. Les URI, secrets, handles backend, payloads complets et source bytes ne traversent pas la frontière frontend.
Market Desk
ksp-app-market-desk
-> ksp-store-lib
-> live transport only where explicitly useful
-> KSP domain/query contracts
Elle consomme les projections DOMAIN normalisées ; elle ne dépend pas directement des bibliothèques protocole externes.
Scenarios
ksp-scenario-<domain>-lib
-> ksp-program-api
-> program implementation(s)
-> ksp-execution-policy-api
-> ksp-execution-lib
-> ksp-wallet-lib
-> ksp-onchain-transport-lib
-> ksp-config-lib si configuration nécessaire
Une policy Devnet petite et spécifique peut être implémentée dans la crate scenario.
L'app demo correspondante reste un adapter UI mince.
Progression verticale Program
À partir de DECODED :
wire
-> decode
-> materialize/D3
-> specialized/D4 si utile
-> prepare
-> policy
-> execute
-> Devnet scenario
Les satellites nécessaires restent dans le même groupe protocolaire.
Contrôle des cycles
Le sens général reste descendant :
core
<- interface
<- program-api
<- program implementations
store-api
<- store-lib
worker-api
<- worker-control / workers
job-api
<- jobs
Les applications/orchestrateurs réalisent les compositions explicites ; aucune boucle inverse ne doit être créée pour éviter une conversion au bon niveau.
Dépendances non retenues actuellement
ksp-api-lib
ksp-interface-api
ksp-onchain-transport-api
ksp-offchain-transport-api
ksp-wallet-api
ksp-scenario-api
ksp-job-control-lib
ksp-pipeline-lib
ksp-data-api
Elles ne seront réévaluées qu'après démonstration d'un besoin concret.