91 lines
3.5 KiB
Markdown
91 lines
3.5 KiB
Markdown
<!-- file: kb-config/README.md -->
|
||
<!-- version: 7 -->
|
||
|
||
# kb-config
|
||
|
||
Ce crate définit le contrat de configuration commun du workspace.
|
||
|
||
## Rôle dans l'écosystème
|
||
|
||
`kb-config` charge, valide et sérialise un fichier JSON contenant plusieurs profils. Un seul profil est actif à l'exécution grâce au champ `active_profile`.
|
||
|
||
Le crate fournit les structures typées runtime pour :
|
||
|
||
- l'application et l'environnement ;
|
||
- les sorties de logs console, fichier humain, fichier JSON et fichier erreurs ;
|
||
- les filtres de targets `tracing` ;
|
||
- les stores PostgreSQL et SQLite ;
|
||
- les endpoints HTTP JSON-RPC et WebSocket Solana ;
|
||
- les rôles et limites par endpoint ;
|
||
- les listeners Solana standards ;
|
||
- le wallet temporaire géré par profil ;
|
||
- les permissions d'envoi localnet/devnet/testnet/mainnet ;
|
||
- les plafonds de dépense, frais, priorité et fraîcheur du blockhash ;
|
||
- les pages de démonstration Tauri.
|
||
|
||
## Wallet temporaire
|
||
|
||
Le profil `local_devnet` active un wallet persistant de laboratoire sous :
|
||
|
||
```text
|
||
wallets/temporary/local_devnet/local-devnet-operator.json
|
||
```
|
||
|
||
Les profils mainnet conservent `temporary_wallet_enabled = false`. La validation typée refuse un wallet temporaire actif sur `mainnet-beta`, une persistance sans activation et les alias pouvant produire un chemin arbitraire.
|
||
|
||
## Exécution
|
||
|
||
La configuration sépare :
|
||
|
||
- le dry-run par défaut ;
|
||
- l'obligation de simulation ;
|
||
- la confirmation opérateur ;
|
||
- les plafonds de dépense localnet, devnet, testnet et mainnet ;
|
||
- le plafond de frais ;
|
||
- le plafond de prix par compute unit ;
|
||
- l'âge maximal du recent blockhash.
|
||
|
||
Un cluster dont l'envoi est activé doit disposer d'un plafond de dépense positif. Toute dépense configurée exige la simulation et toute dépense mainnet exige la confirmation opérateur. Les paramètres de confirmation sont bornés et le plafond d’airdrop Devnet est interdit dans les profils d’un autre cluster.
|
||
|
||
## Validation
|
||
|
||
La validation se fait en deux étapes :
|
||
|
||
1. validation JSON brute via `config/schema.config.json` et `jsonschema` ;
|
||
2. validation typée après désérialisation Rust.
|
||
|
||
## Secrets et placeholders
|
||
|
||
Le fichier versionné doit rester sans secret. Les placeholders restent directement dans les URLs. Les keypairs générés par `kb-wallet` vivent hors du fichier de configuration et sous un répertoire ignoré par Git.
|
||
|
||
## Exports TS-rs
|
||
|
||
Les structures exposées à Tauri utilisent `TS` avec un chemin `export_to` explicite. Les fichiers générés servent uniquement au partage des types Rust/TypeScript et ne remplacent pas le schéma JSON runtime.
|
||
|
||
```bash
|
||
cargo test export_bindings -p kb-config
|
||
cargo test -p kb-config settings::tests::
|
||
```
|
||
|
||
## Résolution de l'environnement
|
||
|
||
`kb-config` est l'unique propriétaire du chargement des fichiers `.env` utilisés par la configuration. La priorité est déterministe :
|
||
|
||
1. variables déjà présentes dans l'environnement du processus ;
|
||
2. fichier indiqué par `KB_ENV_FILE`, sinon `.env` à la racine du workspace ;
|
||
3. fallback `${NOM:-valeur}` déclaré dans le JSON ;
|
||
4. conservation de `${NOM}` lorsqu'une valeur requise reste absente, afin que les consommateurs optionnels puissent échouer seulement à l'utilisation.
|
||
|
||
Les crates métier ne chargent pas elles-mêmes de fichier `.env`.
|
||
|
||
Le modèle racine utilise :
|
||
|
||
```text
|
||
HELIUS_API_KEY
|
||
KB_POSTGRES_MAINNET_URL
|
||
KB_POSTGRES_DEVNET_URL
|
||
KB_POSTGRES_TEST_URL
|
||
```
|
||
|
||
Les deux URLs runtime alimentent les profils correspondants. `KB_POSTGRES_TEST_URL` reste réservé aux tests d’intégration de `kb-store`.
|