khadhroony-bot3/config/README.md

Configuration locale

Ce dossier contient les exemples et le schéma de configuration JSON.

Règles

• Le fichier versionné doit rester sans secret.
• Les placeholders de clés restent directement dans les URLs.
• Le champ active_profile sélectionne un seul profil actif.
• Un profil actif doit être présent et unique.
• Les profils non actifs peuvent rester dans le fichier pour les tests devnet, mainnet lecture seule, backfill ou future production.
• Le contrat courant couvre HTTP JSON-RPC Solana et WebSocket JSON-RPC générique.
• Helius transactionSubscribe et Yellowstone gRPC seront ajoutés plus tard dans ks_onchain_transport, avec évolution explicite du schéma quand les transports seront réellement utilisés.
• Les IDLs restent des artefacts de développement et ne font pas partie de la configuration runtime.

Fichiers

• example.config.json : exemple complet avec profils local_devnet, mainnet_research et mainnet.
• schema.config.json : JSON Schema de validation du fichier de configuration.

Variables d’environnement de l’exemple

example.config.json conserve la topologie des profils et référence les valeurs locales avec des placeholders :

HELIUS_API_KEY
KB_POSTGRES_MAINNET_URL
KB_POSTGRES_DEVNET_URL

KB_POSTGRES_TEST_URL n’est pas utilisé par un profil runtime : il reste réservé aux tests d’intégration PostgreSQL. Le profil local_devnet utilise KB_POSTGRES_DEVNET_URL; les profils mainnet_research et mainnet utilisent KB_POSTGRES_MAINNET_URL. Les trois bases doivent être distinctes.

Le fichier réel .env reste local et ignoré par Git. .env.example est le seul modèle dotenv versionné.

Phase 0.3.x

0.3.x utilise les endpoints HTTP des profils de recherche existants pour :

getSignaturesForAddress
getTransaction
getSignatureStatuses

Aucun profil Helius payant ou Yellowstone n’est activé à ce stade.

Les sources futures devront déclarer séparément :

• provider ;
• protocole ;
• rôle ;
• limites de streams et filtres ;
• authentification ;
• région éventuelle.

Évolution du schéma

schema.config.json est le contrat de validation runtime. Il évolue seulement lorsqu’un champ est réellement utilisé par l’exécution.

Logging de développement

L’exemple configure, pour chacun des trois profils, quatre fichiers globaux puis trois fichiers dédiés par crate opérationnelle utilisant tracing : debug.log, info.log et error.jsonl.

Les matérialisateurs natifs consolidés rejoignent la console et disposent de leurs routes propres sous :

logs/<profil>/ks-lib/materializer/admin/
logs/<profil>/ks-lib/materializer/compliance/audit/
logs/<profil>/ks-lib/materializer/lifecycle/
logs/<profil>/ks-lib/materializer/risk/
logs/<profil>/ks-lib/materializer/staking/
logs/<profil>/ks-lib/materializer/token/accounts/
logs/<profil>/ks-lib/materializer/transaction/annotations/

Le test de configuration découvre dynamiquement toutes les crates déclarant tracing.workspace = true et vérifie leurs trois routes dans chaque profil. Les logs ne doivent contenir ni secret, ni DSN non masqué, ni payload Config ou bytecode complet.

Limites du profil public Devnet

api.devnet.solana.com est un endpoint public partagé. Les limites configurées par rôle ne sont pas des quotas indépendants fournis par le serveur : leur débit cumulé doit rester sous la limite globale de l’endpoint, et chaque méthode RPC doit également rester sous sa propre limite.

L’exemple local_devnet utilise donc volontairement des valeurs conservatrices :

http_queries:
  requests_per_second: 3
  burst_capacity: 3
  max_concurrent_requests: 2
  pause_after_rate_limit_ms: 10000

http_transactions:
  requests_per_second: 1
  burst_capacity: 1
  max_concurrent_requests: 1
  pause_after_rate_limit_ms: 10000

Un fichier de configuration local déjà créé n’est pas modifié automatiquement lorsque example.config.json évolue. L’opérateur doit reporter explicitement ces valeurs dans son profil local_devnet.

Un warning retry_http_json_rpc_after_rate_limit reste possible sur un service public partagé. Il indique que le cooldown et le retry borné ont été activés ; il ne constitue un échec que si les tentatives finissent par être épuisées.