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

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

Pendant 0.5.1, ks-config reconstruit encore AppConfig/ProfileConfig afin de préserver les consommateurs existants. Il s'agit d'une projection runtime, pas d'un document source.

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

Frontière TS-RS

L'audit pre.007 confirme que le frontend du desktop n'importe directement aucun binding généré depuis ks-config ou ks-lib. Les dérivations TS-RS des crates généralistes seront donc réévaluées dans la prerelease suivante : les DTO réellement destinés à Tauri doivent être définis/wrappés dans l'application, sauf contrat TypeScript générique explicitement justifié.

Étape suivante

La prochaine prerelease traite ensemble :

• représentation source / runtime / publique / diagnostic ;
• propagation SECRET / PUBLIC / interne ;
• suppression de l'exposition Tauri de la configuration runtime complète ;
• réduction des bindings TS-RS dans les crates généralistes et wrappers applicatifs nécessaires.

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.