<!-- 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`.