# 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 ```text 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 ```text 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 ```text ksp-onchain-transport-lib -> ksp-core-lib -> ksp-logging-lib -> external HTTP/WS/gRPC crates réellement nécessaires ``` Interdictions : ```text 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 : ```text 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 ```text 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 ```text 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 ```text ksp-offchain-transport-lib -> ksp-core-lib -> ksp-logging-lib -> external HTTP/client crates nécessaires ``` Aucune `ksp-offchain-transport-api` globale n'est prévue. La première surface est un reader de prix ; metadata HTTP/IPFS/Arweave et autres besoins sont ajoutés lorsqu'ils deviennent concrets. # Wallet ```text 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 : ```text 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 / wire ```text ksp-interface-lib -> ksp-core-lib -> ksp-logging-lib lorsque runtime logging réel -> official/compatible wire dependencies retenues ``` `ksp-interface-lib` contient **à la fois** la façade wire officielle et une API publique wire utilisable par les implémentations Program officielles/externes. Aucune `ksp-interface-api` séparée n'est retenue actuellement. Interdictions : ```text 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 ```text 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 : ```text ksp-program--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 ```text 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 : ```text 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 ```text D1 RAW -> D2 CORE -> D3 DECODE -> D4 SPECIALIZED ``` ## RAW ```text transport model | v composition/RAW ingestion | v ksp-store-api | v ksp-store-lib ``` ## CORE ```text D1 RAW | v Solana generic normalizer | v D2 CORE ``` Le normalizer CORE peut utiliser `ksp-interface-lib` pour des wires Solana génériques. Interdictions : ```text RAW -> CORE -X-> ksp-program-api RAW -> CORE -X-> ksp-program-lib RAW -> CORE -X-> ksp-materializer-api ``` ## DECODE ```text D2 CORE | v ksp-program-api implementation | v decoded facts | v ksp-materializer-api implementation | v D3 DECODE / generic journal ``` ## SPECIALIZED ```text D3 DECODE | v specialized projector/materializer | v D4 SPECIALIZED ``` # Materialization ```text 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 ```text ksp-store-api -> ksp-core-lib ksp-store-lib -> ksp-store-api -> ksp-core-lib -> ksp-logging-lib -> PostgreSQL dependencies ``` Interdictions : ```text ksp-store-api -X-> transport/program/materializer ksp-store-lib -X-> transport/program/materializer ``` La première release Store (`0.3.1`) est RAW-only ; les contrats CORE/DECODE/SPECIALIZED sont ajoutés avec leurs couches. # Jobs ```text ksp-job-api -> ksp-core-lib ``` Premier job pressenti : ```text ksp-job-backfill -> ksp-job-api -> ksp-onchain-transport-lib -> ksp-store-api -> ksp-config-lib -> ksp-logging-lib ``` Il remplit RAW et ne décode rien. # Workers ```text ksp-worker-api -> ksp-core-lib ksp-worker-control-lib -> ksp-worker-api -> ksp-core-lib ``` RAW worker et CORE worker sont introduits à la fin de leur couche respective, lorsque persistence/backlog sont disponibles. Les workers DECODE/SPECIALIZED sont introduits avec les groupes Program concernés plutôt que tous anticipés en bloc. # Apps ## Wallet Desk ```text ksp-app-wallet-desk -> ksp-config-lib -> ksp-wallet-lib -> ksp-onchain-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 et le profil Transport. 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. ## Price Desk ```text price desk -> ksp-config-lib -> ksp-offchain-transport-lib -> ksp-logging-lib ``` ## Backfill app ```text backfill app -> ksp-job-api -> concrete backfill job -> ksp-config-lib -> ksp-logging-lib ``` ## Market Desk ```text ksp-app-market-desk -> ksp-store-api -> live transport only where explicitly useful -> KSP domain/query contracts ``` Elle consomme les projections SPECIALIZED normalisées ; elle ne dépend pas directement des bibliothèques protocole externes. # Scenarios ```text ksp-scenario--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 DECODE : ```text 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 : ```text 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 ```text 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.