105 lines
4.3 KiB
Markdown
105 lines
4.3 KiB
Markdown
<!-- file: config/README.md -->
|
||
<!-- version: 17 -->
|
||
|
||
# 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 `kb_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 :
|
||
|
||
```text
|
||
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 :
|
||
|
||
```text
|
||
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 :
|
||
|
||
```text
|
||
logs/<profil>/kb-lib/materializer/admin/
|
||
logs/<profil>/kb-lib/materializer/compliance/audit/
|
||
logs/<profil>/kb-lib/materializer/lifecycle/
|
||
logs/<profil>/kb-lib/materializer/risk/
|
||
logs/<profil>/kb-lib/materializer/staking/
|
||
logs/<profil>/kb-lib/materializer/token/accounts/
|
||
logs/<profil>/kb-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 :
|
||
|
||
```text
|
||
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.
|
||
|