# 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 -> 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. ```text 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 ```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. ### SOL Prices Desk ```text 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 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.