v0.4.8-pre.010

kb-onchain-transport/USAGE.md

@@ -1,5 +1,5 @@
 <!-- file: kb-onchain-transport/USAGE.md -->
-<!-- version: 2 -->
+<!-- version: 5 -->
 
 # Utilisation de kb-onchain-transport
 
@@ -126,6 +126,18 @@ Les types suivants couvrent les opérations d’exécution :
 
 La soumission ne remplace pas les contrôles de sécurité, préflights et confirmations opérateur réalisés par les couches supérieures.
 
+## Lectures complètes et limites de débit
+
+`MAX_COMPLETE_ACCOUNT_DATA_BYTES` expose la borne commune des données décodées retournées par une lecture complète `getAccountInfo`. Les couches supérieures doivent utiliser cette constante au lieu d’aligner une lecture RPC sur la capacité maximale d’un décodeur offline.
+
+Le client applique d’abord les limites préventives du rôle sélectionné :
+
+- `requests_per_second` alimente un token bucket partagé ;
+- `burst_capacity` borne le burst initial et les crédits accumulés ;
+- `max_concurrent_requests` borne les requêtes simultanément en vol.
+
+Ces limiteurs sont partagés entre les clones d’un même endpoint. Les statuts HTTP `429` et erreurs JSON-RPC `429` restent réessayés avec un backoff borné, car un fournisseur peut appliquer un quota global, dynamique ou partagé que la configuration locale ne peut pas connaître. Le délai configuré par `pause_after_rate_limit_ms` est alors appliqué comme cooldown partagé, sauf lorsqu’un en-tête `Retry-After` impose une attente supérieure. Le nombre de retries reste limité et une erreur terminale conserve le nombre de tentatives.
+
 ## Erreurs et invariants
 
 - les réponses sont validées et adaptées avant exposition aux couches supérieures ;
@@ -145,3 +157,25 @@ La soumission ne remplace pas les contrôles de sécurité, préflights et confi
 - la crate traite les transports on-chain ; elle ne gère pas les métadonnées HTTP, IPFS ou Arweave ;
 - elle ne décode pas les instructions de programmes ;
 - elle ne décide pas seule de l’autorisation d’envoyer une transaction.
+
+## Limitation préventive et réponses `429`
+
+Le client applique les limites du rôle sélectionné avant chaque tentative :
+
+- `requests_per_second` et `burst_capacity` alimentent un token bucket partagé ;
+- `max_concurrent_requests` borne les requêtes simultanées ;
+- `pause_after_rate_limit_ms` fournit le cooldown de repli ;
+- `Retry-After` est prioritaire lorsqu’il est fourni par l’endpoint.
+
+Ces limites sont propres aux rôles du client. Elles ne créent pas de quotas indépendants côté fournisseur. Lorsque plusieurs rôles utilisent le même endpoint, leur débit et leurs bursts doivent être additionnés pour rester sous la limite globale de cet endpoint.
+
+Pour `api.devnet.solana.com`, le profil d’exemple utilise volontairement :
+
+```text
+http_queries     3 r/s, burst 3, concurrence 2
+http_transactions 1 r/s, burst 1, concurrence 1
+cooldown          10000 ms
+```
+
+Un warning `retry_http_json_rpc_after_rate_limit` signifie que le serveur a tout de même renvoyé `429` et que la seconde ligne de défense a été activée. La requête n’est perdue que si le retry borné se termine en erreur.
+