Sasedev/khadhroony-solana-project
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
c03a3eaf5d07a2bc093146d8876380827f04e79b
khadhroony-solana-project/docs/plans/011-V0_2_4_HTTP_BLOCKS_ECONOMICS_PLAN.md
SinuS Von SifriduS c03a3eaf5d v0.2.4-pre.001
2026-08-18 19:36:57 +02:00

24 KiB
Raw Blame History

Plan 0.2.4 — HTTP Blocks + Economics + compliance HTTP finale

Statut

Ce plan ouvre 0.2.4 par 0.2.4-pre.001 sur la base stable attendue v0.2.3.

0.2.1 a stabilisé la foundation HTTP et 4 wrappers typed, 0.2.2 les 22 wrappers Accounts/Tokens/Cluster et 0.2.3 les 11 wrappers Transactions. La surface acquise au démarrage est donc :

52 méthodes HTTP courantes enregistrées
14 méthodes historiques Deprecated / runtime Removed
37 wrappers typed courants
15 wrappers typed restant sous HttpRpcCoverageRelease::V0_2_4

La mission de 0.2.4 est strictement de compléter les 10 Blocks + 5 Economics déjà affectées à V0_2_4, puis de fermer la compliance HTTP globale 52/52 current + 14/14 historical sous la règle KSP-TRANSPORT-007.

Gate de sizing pre.001

Question obligatoire :

Les 15 wrappers Blocks/Economics, leurs DTOs/wires, les overloads/legacy,
les tests, la compliance 52+14 et la documentation peuvent-ils être
clôturés proprement dans cette release/session ?

Réponse :

OUI.

Aucun split de release n'est nécessaire avant implémentation. Le volume est supérieur à 0.2.3 en nombre de wrappers mais reste inférieur à 0.2.2. La complexité est surtout concentrée dans getBlock, getBlockProduction, getInflationReward et la compliance finale ; ces fils sont donc isolés dans des prereleases dédiées. Si une tranche réelle dépasse le budget KSP d'environ 15–20 minutes, une prerelease supplémentaire sera créée dans 0.2.4 sans déplacer silencieusement une méthode vers 0.2.5.

Sources normatives réauditées le 2026-08-18

Documentation publique :

https://solana.com/docs/rpc/http
https://solana.com/docs/rpc/json-structures

Pages Blocks :

https://solana.com/docs/rpc/http/getblock
https://solana.com/docs/rpc/http/getblockcommitment
https://solana.com/docs/rpc/http/getblockheight
https://solana.com/docs/rpc/http/getblockproduction
https://solana.com/docs/rpc/http/getblocks
https://solana.com/docs/rpc/http/getblockswithlimit
https://solana.com/docs/rpc/http/getblocktime
https://solana.com/docs/rpc/http/getfirstavailableblock
https://solana.com/docs/rpc/http/getrecentperformancesamples
https://solana.com/docs/rpc/http/minimumledgerslot

Pages Economics :

https://solana.com/docs/rpc/http/getinflationgovernor
https://solana.com/docs/rpc/http/getinflationrate
https://solana.com/docs/rpc/http/getinflationreward
https://solana.com/docs/rpc/http/getstakeminimumdelegation
https://solana.com/docs/rpc/http/getsupply

La documentation Solana actuelle relie encore plusieurs définitions/source examples à Agave v3.1.8. Ce pointeur documentaire n'est donc pas utilisé comme preuve que v3.1.8 représente le runtime stable actuel.

Le cross-audit runtime a été effectué contre Agave v4.2.1, release patch publiée le 2026-08-13 dans la branche stable 4.2.x. v4.2.0 est explicitement publiée comme stable pour Mainnet Beta, Devnet et Testnet ; v4.3.0-beta.0, plus récente en date, reste une prerelease et n'est pas la baseline normative de cette release KSP.

Sources primaires Agave ciblées :

https://github.com/anza-xyz/agave/releases/tag/v4.2.1
https://github.com/anza-xyz/agave/blob/v4.2.1/rpc/src/rpc.rs
https://github.com/anza-xyz/agave/blob/v4.2.1/rpc-client-types/src/config.rs
https://github.com/anza-xyz/agave/blob/v4.2.1/rpc-client-types/src/response.rs

Inventaire officiel réaudité

L'index HTTP Solana actuel contient toujours exactement les catégories suivantes :

Accounts      6
Tokens        5
Transactions 11
Blocks       10
Cluster      15
Economics     5
             --
Current      52

La navigation Deprecated conserve les 14 noms historiques déjà enregistrés par KSP :

confirmTransaction
getConfirmedBlock
getConfirmedBlocks
getConfirmedBlocksWithLimit
getConfirmedSignaturesForAddress2
getConfirmedTransaction
getFeeCalculatorForBlockhash
getFeeRateGovernor
getFees
getRecentBlockhash
getSignatureConfirmation
getSignatureStatus
getSnapshotSlot
getStakeActivation

La partition KSP reste donc inchangée :

0.2.1 =  4
0.2.2 = 22
0.2.3 = 11
0.2.4 = 15
          --
current  = 52
historical = 14

Les 15 descriptors V0_2_4 sont déjà classés Read / RetrySafe. getBlock reste le seul de ces descriptors marqué StableWithDeprecatedLegacy à cause de son second paramètre bare encoding encore accepté pour compatibilité.

Règle de complétude KSP-TRANSPORT-007

Un wrapper de cette release n'est complet que s'il expose sans perte toutes les possibilités RPC retenues par l'audit : paramètres ordonnés, objets de config, overloads, formes legacy encore supportées, contraintes déterministes utiles, variantes de réponse et distinctions omitted/null nécessaires.

Pour 0.2.4, cela impose notamment :

  • de ne pas réduire getBlocks à la seule forme [start, end, config] ;
  • de conserver le bare encoding legacy de getBlock sans le présenter comme forme recommandée ;
  • de préserver transactionDetails = full | signatures | none | accounts et les conséquences sur la présence des champs de bloc ;
  • de préserver les champs wire riches des transactions/meta/rewards sans importer un client RPC Solana haut niveau ;
  • de conserver les null positionnels de getInflationReward et le champ runtime commissionBps lorsqu'il est présent ;
  • de ne pas inventer de limite d'adresses getInflationReward si aucune limite sémantique fixe n'est établie par la documentation/runtime courant ; la limite générale de taille de requête HTTP n'est pas transformée artificiellement en cardinalité métier KSP.

Matrice Blocks — 10 wrappers

Méthode Requête à couvrir Résultat à préserver Contraintes / décisions KSP-TRANSPORT-007
getBlock slot; second paramètre absent, bare encoding legacy, ou config {commitment, encoding, transactionDetails, maxSupportedTransactionVersion, rewards} object ou null; previousBlockhash, blockhash, parentSlot, transactions/signatures/rewards selon config, numRewardPartitions, blockTime, blockHeight commitment runtime au moins confirmed; réutiliser les encodings/version/transaction wire de 0.2.3; préserver omission vs null ; garder les erreurs runtime de bloc/version comme erreurs RPC, sans les masquer
getBlockCommitment slot uniquement {commitment: array<u64> ou null, totalStake: u64} aucune config à inventer ; préserver commitment nullable
getBlockHeight config contextuelle optionnelle {commitment, minContextSlot} u64 réutiliser SolanaContextConfig; minContextSlot est transmis tel quel au runtime
getBlockProduction config optionnelle {commitment, identity, range:{firstSlot,lastSlot?}} SolanaRpcResponse<{byIdentity, range}> identity typée Pubkey ; validation locale déterministe lastSlot >= firstSlot lorsque les deux sont fournis ; préserver les couples [leaderSlots, blocksProduced]
getBlocks [start], [start,end], [start,config], [start,end,config] Vec<u64> commitment au moins confirmed; conserver l'overload untagged du second paramètre ; end < start donne []; rejeter localement une différence end-start > 500_000
getBlocksWithLimit start, limit, config contextuelle optionnelle Vec<u64> commitment au moins confirmed; limit <= 500_000; limit = 0 est valide et donne []
getBlockTime slot uniquement i64 ou null préserver l'absence de timestamp ; les cas cleaned/skipped/not available restent des erreurs RPC runtime, pas des valeurs synthétiques
getFirstAvailableBlock aucun paramètre u64 requête exacte params: [] ; aucune config
getRecentPerformanceSamples limit? tableau de {slot,numTransactions,numSlots,samplePeriodSecs,numNonVoteTransactions?} défaut runtime 720; maximum 720; rejeter avant I/O limit > 720; préserver numNonVoteTransactions nullable/ancien runtime
minimumLedgerSlot aucun paramètre u64 requête exacte params: []; conserver les erreurs ledger/runtime

getBlock — stratégie wire

getBlock est le plus gros fil de la release et reçoit une prerelease dédiée.

Les primitives déjà acquises de rpc_transactions doivent être réutilisées lorsque le wire est réellement commun :

SolanaTransactionEncoding
SolanaEncodedTransaction
SolanaTransactionVersion
SolanaWireField<T>

SolanaConfirmedTransaction ne doit pas être réutilisé tel quel pour un élément de bloc : ce DTO contient slot et blockTime, qui appartiennent au résultat top-level de getTransaction et non à chaque élément transactions[] d'un bloc. Un type wire de transaction de bloc dédié peut en revanche composer les primitives ci-dessus et préserver transaction, meta et version sans décodage Program.

Les champs top-level dont la présence dépend de la config (transactions, signatures, rewards, numRewardPartitions) doivent utiliser une représentation capable de distinguer une omission d'un null lorsqu'une telle distinction existe sur le wire. Les transactions accounts ne doivent pas être forcées dans une structure full plus riche que le wire réellement retourné.

Matrice Economics — 5 wrappers

Méthode Requête à couvrir Résultat à préserver Contraintes / décisions KSP-TRANSPORT-007
getInflationGovernor config commitment optionnelle {initial,terminal,taper,foundation,foundationTerm} en f64 réutiliser SolanaCommitmentConfig; aucun contexte de réponse
getInflationRate aucun paramètre {total,validator,foundation,epoch} requête exacte params: []
getInflationReward liste ordonnée d'adresses ; config optionnelle {epoch,commitment,minContextSlot} Vec<Option<Reward>> positionnel ordre/cardinalité identiques aux entrées ; préserver commission: u8 ou null et commissionBps: u16 optionnel de Agave v4.2.1; aucune limite fixe d'adresses inventée
getStakeMinimumDelegation config contextuelle optionnelle {commitment,minContextSlot} SolanaRpcResponse<u64> réutiliser SolanaContextConfig / SolanaRpcResponse<T>
getSupply config optionnelle {commitment,excludeNonCirculatingAccountsList} SolanaRpcResponse<{total,circulating,nonCirculating,nonCirculatingAccounts}> le booléen runtime par défaut est false; préserver la liste ordonnée retournée lorsqu'elle est demandée

Extension runtime commissionBps

La documentation publique actuelle de getInflationReward énumère encore uniquement commission. Agave v4.2.1 définit cependant aussi :

commission_bps: Option<u16>

sérialisé en commissionBps lorsqu'il est présent. Ce champ correspond à l'évolution SIMD-0291 et doit être conservé dans le DTO KSP pour ne pas perdre une capacité/extension du runtime stable courant.

Contraintes locales retenues

Les validations déterministes suivantes doivent être réalisées avant I/O :

getBlock                  commitment >= confirmed
getBlocks                 commitment >= confirmed
getBlocks                 end-start <= 500_000 lorsqu'end >= start
getBlocksWithLimit        commitment >= confirmed
getBlocksWithLimit        limit <= 500_000
getRecentPerformanceSamples limit <= 720
getBlockProduction        lastSlot >= firstSlot lorsqu'ils sont tous deux présents

getBlocks(end < start) et getBlocksWithLimit(limit = 0) sont des cas valides qui doivent produire un tableau vide plutôt qu'une erreur locale.

Ne pas reproduire localement les validations qui nécessiteraient un décodage disproportionné ou l'état du ledger : disponibilité réelle d'un bloc, slot cleaned/skipped, support effectif d'une version de transaction par le caller, présence historique des metadata, epoch disponible, minContextSlot atteint, etc. Ces cas restent des erreurs/réponses RPC validées par le flux central.

Réutilisation des contrats existants

À réutiliser directement

SolanaCommitment
SolanaCommitmentConfig
SolanaContextConfig
SolanaRpcContext
SolanaRpcResponse<T>
SolanaTransactionEncoding
SolanaEncodedTransaction
SolanaTransactionVersion
SolanaWireField<T>

À introduire dans 0.2.4

Noms définitifs ajustables pendant l'implémentation, responsabilités fixes :

config getBlock moderne + enum transactionDetails
config/range/result getBlockProduction
block commitment result
confirmed block + transaction-in-block + reward wire
performance sample
inflation governor/rate/reward
supply result/config

La déduplication ne doit pas fusionner des contrats ayant des sémantiques différentes uniquement parce que leurs champs se ressemblent.

Architecture d'exécution

Les 15 wrappers restent Read / RetrySafe et passent exclusivement par :

wrapper typed
    -> descriptor central
    -> execute_standard_rpc
    -> pool/admission
    -> executor HTTP
    -> validation JSON-RPC
    -> decode typed

Interdits :

client HTTP parallèle
reqwest direct dans un wrapper
retry/deadline/admission bypass
Transport -> Config
Transport -> Store/Program
tracing direct
solana-rpc-client / solana-client pour masquer les possibilités RPC

Dépendances

Aucune nouvelle dépendance n'est nécessaire au vu de l'audit pre.001.

En particulier :

solana-rpc-client NON
solana-client     NON
crate SDK Block   NON
base64/bs58       NON pour cette release

Les primitives serde/serde_json, ksp-core-lib::Pubkey et les wires Transaction déjà présents suffisent à exprimer les contrats sans introduire un SDK RPC haut niveau.

Tests déterministes attendus

Chaque wrapper doit couvrir :

  • request JSON exacte ;
  • absence de config et objet vide lorsque ces deux formes sont significatives ;
  • tous les overloads/configs/encodings pertinents ;
  • réponse typed nominale ;
  • null et omission lorsque le wire les distingue ;
  • ordre et cardinalité ;
  • erreur JSON-RPC propagée ;
  • validation déterministe avant I/O lorsqu'elle est retenue par ce plan.

Cas de régression obligatoires spécifiques :

getBlock bare encoding legacy
getBlock transactionDetails full/signatures/none/accounts
getBlock result null
getBlocks [start,config] vs [start,end,config]
getBlocks range > 500_000 rejetée avant I/O
getBlocksWithLimit 0 et > 500_000
getRecentPerformanceSamples défaut/720/>720
getBlockProduction lastSlot < firstSlot rejeté avant I/O
getInflationReward ordre + null positionnels + commissionBps
getSupply excludeNonCirculatingAccountsList true/false/omitted

Compliance finale HTTP

La dernière prerelease doit ajouter une preuve explicite que les 52 méthodes courantes enregistrées possèdent désormais toutes un wrapper typed public réel. Un appel raw/générique ne compte pas.

Canaries finales :

current registry                  == 52
historical registry               == 14
V0_2_1 exact                      == 4
V0_2_2 exact                      == 22
V0_2_3 exact                      == 11
V0_2_4 exact                      == 15
typed wrappers current            == 52/52
historical Deprecated/Removed     == 14/14
KSP-TRANSPORT-007 audited current == 52/52

La compliance KSP-TRANSPORT-007 des 37 wrappers de 0.2.1–0.2.3 reste acquise par docs/validation/005-V0_2_3_KSP_TRANSPORT_007_RETRO_AUDIT.md; la clôture 0.2.4 vérifie qu'aucune régression n'a été introduite et applique la même règle aux 15 nouveaux wrappers.

Smokes live

Les smokes restent opt-in et secondaires par rapport aux fixtures locales.

Le smoke Transport pur peut être étendu uniquement avec quelques reads robustes, par exemple getBlockHeight, getFirstAvailableBlock, minimumLedgerSlot, getInflationRate ou getStakeMinimumDelegation. Éviter un getBlock dépendant d'un slot fixe ou tout scénario fragile lié à des récompenses d'un epoch précis.

Le smoke historique Config -> Transport reste une exception transitoire de composition et ne devient pas la destination générale des futurs scénarios cross-crates.

Prévision souple des prereleases

pre.001  audit officiel actuel + Agave stable + matrice + wires + contraintes + sizing
pre.002  primitives/configs/results Blocks/Economics partagés + fixtures communes
pre.003  Blocks simples : getBlockCommitment, getBlockHeight, getBlockTime,
         getFirstAvailableBlock, minimumLedgerSlot
pre.004  ranges/performance : getBlocks, getBlocksWithLimit, getRecentPerformanceSamples
pre.005  getBlockProduction + range/identity/result contextualisé
pre.006  getBlock moderne + bare encoding legacy + transactionDetails + wire bloc riche
pre.007  Economics simples : getInflationGovernor, getInflationRate,
         getStakeMinimumDelegation, getSupply
pre.008  getInflationReward + null positionnels + commissionBps + invariants
pre.009  compliance finale 52/52 + 14/14 + KSP-TRANSPORT-007 + docs + smokes + graphes
         + prompt 0.2.5 — Wallet foundation
rel.001  publication strictement publicationnelle

Cette prévision peut être redécoupée si une tranche dépasse le budget réel. Elle ne doit pas être compressée artificiellement pour conserver un numéro de prerelease prévu.

Hors périmètre

Wallet / .kspwallet
WebSocket
LaserStream
Yellowstone gRPC
Store/Program/Materializer
modèle métier de transaction/bloc
client RPC Solana haut niveau
réécriture des deltas historiques

Critères de clôture 0.2.4

  • 15/15 wrappers V0_2_4 publics, typed et KSP-TRANSPORT-007 conformes ;
  • 52/52 méthodes HTTP courantes avec wrapper typed ;
  • 14/14 historiques conservées en compliance ;
  • aucun bypass du flux central Transport ;
  • aucune nouvelle dépendance injustifiée ;
  • tests déterministes complets ;
  • smokes live pertinents validés par preuve opérateur ;
  • graphes Cargo Transport/Config réaudités ;
  • README/USAGE/matrices/validation synchronisés ;
  • prompt 0.2.5 — Wallet foundation finalisé ;
  • dernière prerelease candidate complète ;
  • 0.2.4-rel.001 strictement publicationnelle.

Questions ouvertes

Aucune question bloquante pour pre.002.

Les noms Rust exacts des DTOs peuvent encore être ajustés pendant l'implémentation. En revanche, les formes RPC, overloads, distinctions wire et limites fixées dans ce plan ne doivent pas être réduits pour simplifier l'API KSP.

Reference in New Issue View Git Blame Copy Permalink