0.1.0

docs/RPC_ENDPOINT_ROLES.md

@@ -0,0 +1,77 @@
+<!-- file: docs/RPC_ENDPOINT_ROLES.md -->
+<!-- version: 4 -->
+
+# Rôles des endpoints RPC et streams
+
+Les rôles servent à sélectionner un endpoint selon l’opération, le provider, le protocole et les limites locales.
+
+## Rôles HTTP actifs
+
+| Rôle                | Usage                                                           |
+|---------------------|-----------------------------------------------------------------|
+| `http_queries`      | lectures courantes                                              |
+| `history_backfill`  | `getSignaturesForAddress`, `getTransaction` et backfills ciblés |
+| `http_transactions` | simulation, envoi et confirmation                               |
+| `http_fallback`     | endpoint de secours                                             |
+| `http_heavy`        | appels lourds                                                   |
+
+`0.3.x` utilise principalement `history_backfill` avec les comptes gratuits.
+
+## Rôles WebSocket standard existants
+
+| Rôle                    | Usage                         |
+|-------------------------|-------------------------------|
+| `slot_notifications`    | progression et santé du flux  |
+| `logs_subscribe`        | logs ciblés                   |
+| `program_subscribe`     | comptes détenus par programme |
+| `account_subscribe`     | comptes précis                |
+| `program_logs`          | compatibilité historique      |
+| `account_notifications` | compatibilité historique      |
+
+## Rôles futurs `0.10.x`
+
+| Rôle                             | Usage                                         |
+|----------------------------------|-----------------------------------------------|
+| `helius_transaction_stream`      | extension Helius `transactionSubscribe`       |
+| `yellowstone_transaction_stream` | filtre transactions Yellowstone gRPC          |
+| `logs_all_probe`                 | comparaison temporaire `logsSubscribe("all")` |
+| `realtime_transaction_hydration` | hydratation HTTP et réparation                |
+
+Les transports Helius et Yellowstone restent implémentés dans `kb_rpc`. Les rôles ne créent pas de dépendance provider dans les décodeurs.
+
+## Request kinds actifs pour le backfill
+
+```text
+get_signatures_for_address
+get_transaction
+get_signature_statuses
+get_slot
+get_version
+```
+
+## Request kinds futurs
+
+```text
+transaction_subscribe
+transaction_unsubscribe
+yellowstone_transaction_subscribe
+logs_subscribe_all
+logs_unsubscribe
+```
+
+## Limites par rôle
+
+```text
+requests_per_second
+burst_capacity
+max_concurrent_requests
+max_subscriptions
+pause_after_rate_limit_ms
+```
+
+Pour les streams gRPC, la configuration future ajoutera les limites de streams, filtres, adresses et taille de queue sans casser les rôles HTTP/WS existants.
+
+## Preuve runtime
+
+Un rôle ou un plan configuré ne garantit pas la capacité distante. La réponse du provider reste la preuve runtime. Les refus de plan, filtres invalides et limitations doivent être normalisés comme erreurs de `kb_rpc`.
+