khadhroony-bot3/docs/guides/CONFIGURATION.md

Guide de configuration

Objectif

La configuration sépare les responsabilités Solana partagées des choix propres aux binaires. Les documents spécialisés sont autonomes grâce à leurs valeurs globales et à leur default_profile; une composition de binaire ne fournit que les overrides nécessaires.

Documents actifs

Composition actuelle :

• config/kb-app-demo-desktop.default.config.json : composition par défaut du desktop.

Documents partagés :

• config/logging.config.json ;
• config/transport.config.json ;
• config/listeners.config.json ;
• config/store.config.json ;
• config/wallet.config.json ;
• config/execution.config.json.

Chaque document possède un exemple sous config/exemples/ avec un nom example.*.config.json. Les schémas correspondants résident sous config/schemas/.

.env, ou le fichier sélectionné par KS_ENV_FILE, fournit les valeurs non versionnées.

Defaults partagés

Chaque document spécialisé définit un default_profile. Lorsqu'aucune composition n'est fournie, ks-config combine les defaults propres à transport, listeners, store, wallet et execution ; les noms de ces profils n'ont pas besoin d'être identiques. Une composition sélectionne des sources et profils, mais ne duplique pas des paramètres arbitraires : les overrides fins restent dans le schéma propriétaire et les globals explicitement configurables passent par leur variable d'environnement dédiée.

Cette règle permet à une bibliothèque, un scénario ou un futur worker d'utiliser une configuration cohérente sans créer un fichier de composition uniquement pour répéter les choix par défaut.

Composition d'un binaire

Une composition définit :

1. son active_profile applicatif ;
2. les chemins des documents partagés ;
3. les éventuels overrides de profils spécialisés ;
4. les paramètres propres au binaire qui ne relèvent pas d'un document partagé.

Exemple conceptuel :

kb-app-demo-desktop.default.config.json
    sources.logging   -> config/logging.config.json
    sources.transport -> config/transport.config.json
    sources.listeners -> config/listeners.config.json
    sources.store     -> config/store.config.json
    sources.wallet    -> config/wallet.config.json
    sources.execution -> config/execution.config.json

    profile local_devnet
        aucun override -> defaults des documents partagés

    profile mainnet_research
        logging_profile   -> mainnet_research
        transport_profile -> mainnet_research
        listeners_profile -> mainnet_research
        store_profile     -> mainnet_research
        wallet_profile    -> mainnet_research
        execution_profile -> mainnet_research

ks-config charge les fichiers référencés, valide leurs schémas/types et refuse une composition qui référence un profil inexistant.

Desktop

Le chemin de composition du desktop peut être remplacé par :

KB_APP_DEMO_DESKTOP_CONFIG_PATH

Le logging conserve aussi l'override opérationnel :

KS_LOGGING_CONFIG_PATH

Scénarios Devnet

Par défaut, ks-pipeline-demo-scenarios utilise directement les defaults des documents partagés. Il n'existe plus de config/ks-pipeline-demo-scenarios.default.config.json obligatoire.

Les overrides opérateur restent :

KS_DEVNET_CONFIG_PATH   # composition explicite facultative
KS_DEVNET_PROFILE       # sélection d'un profil runtime compatible Devnet

Valeurs hors profils

Les paramètres globaux ne doivent pas être dupliqués dans chaque profil.

Logging

logs_directory = ${KS_LOGS_DIRECTORY:-logs}

Les chemins de fichiers des targets sont relatifs à cette racine lorsqu'ils ne sont pas absolus.

Wallet

wallets_directory = ${KS_WALLETS_DIRECTORY:-wallets}

Chaque profil wallet ne contient plus qu'un chemin relatif et ses paramètres d'identité/persistance.

Transport WebSocket

Les paramètres communs d'un type d'endpoint WebSocket sont définis dans ws_endpoint_defaults. Chaque endpoint choisit une classe de defaults et peut écraser individuellement :

• connect_timeout_ms ;
• request_timeout_ms ;
• unsubscribe_timeout_ms ;
• write_channel_capacity ;
• event_channel_capacity ;
• auto_reconnect.

Les classes actuelles couvrent le RPC WS standard et le RPC WS à capacité plus élevée. Une future surface Helius avancée devra avoir son propre contrat/default lorsqu'elle sera réellement implémentée.

Store

store.config.json porte les paramètres PostgreSQL/SQLite. Ce déplacement ne change aucune table ni migration SQL ; la normalisation SQL reste réservée à 0.5.3.

Wallet et politique d'exécution

Les propriétés de stockage/identité du wallet appartiennent à wallet.config.json. Un profil peut définir le champ optionnel wallet_alias pour sélectionner un wallet natif persistant par alias. Son omission ou null signifie qu’aucun wallet persistant n’est sélectionné. Le champ est non sensible et ne contient jamais de mot de passe, de keypair ou de chemin de fichier individuel.

Les autorisations :

localnet_send_enabled
devnet_send_enabled
testnet_send_enabled
mainnet_send_enabled

appartiennent à execution.config.json, avec les limites de dépense, frais, simulation et confirmation. Un wallet sait signer ; la politique d'exécution décide si une soumission est autorisée.

Contrat runtime transitoire

ks-config reconstruit encore AppConfig/ProfileConfig comme projection runtime transitoire afin de préserver les consommateurs backend existants. Il s'agit d'une projection runtime, pas d'un document source ni d'une surface de sortie. Depuis 0.5.1, ces contrats et les documents spécialisés susceptibles de contenir des valeurs résolues ne dérivent ni serde::Serialize ni Debug.

Les fixtures de compatibilité sont sous test-fixtures/config/. Elles ne doivent pas être chargées en production.

Frontière publique et diagnostic

Une application ne transmet jamais AppConfig/ProfileConfig directement. Elle construit :

• une projection publique explicitement typée, limitée aux champs autorisés ;
• un diagnostic borné contenant au plus des états tels que configured/missing pour les URLs, DSN et chemins sensibles ;
• aucune projection construite par sérialisation du runtime suivie d'un masquage a posteriori.

La sensibilité suit Secret > Internal > Public. Une valeur composée hérite de la sensibilité la plus forte des placeholders qu'elle contient ; une URL incorporant ${KS_SECRET_HELIUS_API_KEY} est donc secrète même si son champ final est simplement url.

La section application d'une composition est opaque à ks-config. Le desktop la valide avec son schéma config/schemas/kb-app-demo-desktop.application.config.schema.json; un futur worker pourra posséder son propre schéma sans modifier ks-config.

Frontière TS-RS

Depuis 0.5.1, ks-config et ks-lib ne dépendent plus de TS-RS et ne possèdent plus de bindings TypeScript générés. Les DTO traversant Tauri appartiennent à kb-app-demo-desktop ou à la future application concernée. Une exception dans une crate ks-* exige un contrat TypeScript générique indépendant de Tauri explicitement justifié et audité.

Étape suivante

0.5.1 clôt cette architecture de configuration. Les changements fonctionnels de wallet appartiennent à 0.5.2, la normalisation SQL à 0.5.3 et l’audit final des scénarios/exécuteurs à 0.5.4.

Invariants

• aucun secret réel dans les fichiers versionnés ;
• tous les schémas actifs sous config/schemas/ ;
• aucun retour au fichier monolithique app.config.json ;
• les valeurs globales restent hors profils ;
• une composition appartient à son binaire ;
• un document spécialisé reste indépendant des binaires qui le consomment ;
• ks-config valide les références mais ne maintient pas une liste fermée de futurs workers/applications.