khadhroony-bot3/docs/guides/CONFIGURATION.md

Guide de configuration

Objectif

La configuration est organisée autour de compositions propres aux binaires et de documents spécialisés réutilisables. Un binaire choisit les fichiers partagés et les profils dont il a besoin au lieu de recopier une configuration monolithique.

Fichiers actifs

Compositions :

• config/kb-app-demo-desktop.default.config.json : composition par défaut du desktop ;
• config/ks-pipeline-demo-scenarios.default.config.json : composition par défaut du CLI/scénarios.

Documents partagés :

• config/logging.config.json ;
• config/transport.config.json ;
• config/listeners.config.json.

Exemples :

• config/example.kb-app-demo-desktop.default.config.json ;
• config/example.logging.config.json ;
• config/example.transport.config.json ;
• config/example.listeners.config.json.

Schémas :

• config/schemas/composition.config.schema.json ;
• config/schemas/logging.config.schema.json ;
• config/schemas/transport.config.schema.json ;
• config/schemas/listeners.config.schema.json ;
• config/schemas/resolved.app.config.schema.json pour le contrat runtime reconstruit.

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

Composition d'un binaire

Une composition définit :

1. son active_profile ;
2. les chemins des documents partagés ;
3. pour chaque profil, le logging_profile, transport_profile et listeners_profile à sélectionner ;
4. temporairement, les sections qui n'ont pas encore leur document spécialisé.

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

    profile mainnet_research
        logging_profile   -> mainnet_research
        transport_profile -> mainnet_research
        listeners_profile -> mainnet_research

Les active_profile propres aux documents partagés restent utiles lorsqu'ils sont chargés seuls. Dans une composition, la référence explicite du binaire prime.

Desktop

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

KB_APP_DEMO_DESKTOP_CONFIG_PATH

Le logging conserve l'override opérationnel :

KS_LOGGING_CONFIG_PATH

Sans cet override, le desktop utilise le chemin logging déclaré par sa composition.

Scénarios Devnet

Les scénarios opt-in utilisent :

KS_DEVNET_CONFIG_PATH
KS_DEVNET_PROFILE

KS_DEVNET_CONFIG_PATH désigne désormais un fichier de composition. Sans override, les scénarios utilisent config/ks-pipeline-demo-scenarios.default.config.json.

Transport

transport.config.json possède les endpoints HTTP et WebSocket ainsi que leurs rôles et limites. Le profil transport peut être consommé directement par ks-onchain-transport sans dépendre d'un profil applicatif complet.

Cela prépare les futurs workers : un worker de capture pourra sélectionner un profil transport différent du desktop tout en partageant le même document.

Listeners

listeners.config.json contient les déclarations de subscriptions par logs, programme et compte. Un profil listeners peut être associé à n'importe quel profil transport compatible par le fichier de composition du consommateur.

La séparation évite de recopier les listes de program_id et les filtres lorsque plusieurs binaires observent la même surface Solana.

Logging

logging.config.json appartient à ks-logging. Une composition référence son fichier et son profil, mais les types et validations logging ne reviennent pas dans ks-config.

Contrat runtime résolu

Pendant la migration 0.5.1, ks-config reconstruit encore un AppConfig/ProfileConfig contenant les sections nécessaires aux consommateurs existants. Ce contrat est une projection runtime, pas une configuration source.

Les tests de compatibilité utilisent les fixtures sous test-fixtures/config/. Aucun binaire ne doit charger ces fixtures en production.

Étapes suivantes

Le prochain split doit extraire :

• database vers le document store ;
• logs_directory vers logging ;
• wallets_directory, le stockage wallet et les paramètres de wallet vers un document wallet ;
• les permissions *_send_enabled du wallet vers la politique execution ;
• execution ;
• configuration spécifique au desktop.

Après cette étape seulement, les DTO publics, diagnostics et règles de camouflage seront construits sur les nouvelles frontières.

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 ;
• un fichier de composition appartient à son binaire ;
• un document spécialisé reste indépendant des binaires qui le consomment ;
• ks-config fournit les mécanismes partagés sans enregistrer une liste fermée de workers/applications.