khadhroony-solana-project/docs/architecture/005-DEPENDENCY_GRAPH.md

<!-- file: docs/architecture/005-DEPENDENCY_GRAPH.md -->
<!-- version: 12 -->

# 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-<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

```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-<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 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.