khadhroony-solana-project/deltas/0.2.2/pre.003.md

Delta 0.2.2-pre.003 — cinq wrappers HTTP Accounts typés

Base requise

Livraison précédente corrigée et validée localement par l'opérateur :

0.2.2-pre.002-fix.002
workspace.package.version = "0.2.2-pre.2.fix.2"

La validation opérateur du 2026-08-18 a confirmé :

cargo fmt --all                         OK
cargo check --workspace                 OK
cargo clippy --workspace --all-targets  OK
cargo test -p ksp-onchain-transport-lib OK

Résultats Transport de cette base :

85 unit tests
9 public API tests
2 release completeness tests
0 warning signalé par check/clippy

Le plan canonique reste docs/plans/009-V0_2_2_HTTP_ACCOUNTS_TOKENS_CLUSTER_PLAN.md version 3.

Objectif

Clôturer la famille Accounts attribuée à 0.2.2 avec cinq wrappers publics typés :

getAccountInfo
getLargestAccounts
getMinimumBalanceForRentExemption
getMultipleAccounts
getProgramAccounts

Tous passent par la foundation HTTP 0.2.1 :

wrapper typé
  -> descriptor audité
  -> execute_standard_rpc
  -> pool/admission/retry/deadline
  -> reqwest HTTP
  -> JSON-RPC validation
  -> décodage DTO KSP

Aucun wrapper ne contacte reqwest directement.

Version Cargo

Conformément à VER-ID-009 :

0.2.2-pre.2.fix.2 -> 0.2.2-pre.3

Aucune dépendance ni feature Cargo n'est ajoutée.

Surface typée Accounts

getAccountInfo

Signature publique conceptuelle :

role + Pubkey + Option<SolanaAccountInfoConfig>
  -> SolanaRpcResponse<Option<SolanaAccount>>

Le wrapper :

• sérialise encoding, dataSlice, commitment et minContextSlot ;
• omet l'objet config lorsqu'il est vide ;
• conserve l'absence du compte sous None ;
• conserve les formes Account data legacy, tuple encodé et jsonParsed ;
• convertit l'owner en ksp_core_lib::Pubkey sans recopier une valeur invalide dans le diagnostic.

getLargestAccounts

Signature publique conceptuelle :

role + Option<SolanaLargestAccountsConfig>
  -> SolanaRpcResponse<Vec<SolanaAccountBalance>>

Le wrapper conserve l'ordre du wire et sérialise les champs KSP déjà audités dans pre.002, y compris filter et sortResults lorsqu'ils sont explicitement renseignés.

getMinimumBalanceForRentExemption

Signature publique conceptuelle :

role + usize data_len + Option<SolanaCommitmentConfig>
  -> u64 lamports

Le wrapper encode la longueur de données sans valeur sentinelle et conserve les erreurs JSON-RPC applicatives comme telles.

getMultipleAccounts

Signature publique conceptuelle :

role + &[Pubkey] + Option<SolanaAccountInfoConfig>
  -> SolanaRpcResponse<Vec<Option<SolanaAccount>>>

Le wrapper :

• refuse localement plus de 100 public keys ;
• sérialise les adresses dans l'ordre fourni ;
• conserve les null individuels ;
• vérifie que le nombre d'éléments retournés correspond au nombre d'adresses demandées, afin de ne pas fabriquer silencieusement un mapping positionnel incohérent.

getProgramAccounts

Signature publique conceptuelle :

role + program Pubkey + Option<SolanaProgramAccountsConfig>
  -> SolanaProgramAccountsResult

Le résultat préserve les deux formes wire :

Accounts(Vec<SolanaKeyedAccount>)
Context(SolanaRpcResponse<Vec<SolanaKeyedAccount>>)

Le wrapper sérialise dataSize, memcmp, tokenAccountState, withContext, sortResults et la config Account commune.

Validation locale des paramètres

Nouveau code d'erreur public Transport :

ERROR_CODE_INVALID_RPC_PARAMETERS
onchain_transport.invalid_rpc_parameters

Il distingue une requête KSP localement invalide d'une erreur JSON-RPC distante ou d'une réponse invalide.

Les invariants appliqués avant I/O sont :

getMultipleAccounts : <= 100 public keys
getProgramAccounts  : <= 4 filters
memcmp raw bytes    : <= 128 bytes

Pour memcmp encodé sous forme base58/base64, KSP ne décode toujours pas localement la chaîne : la limite des 128 octets décodés reste donc contrôlée par le serveur. Cette décision évite d'ajouter bs58 ou base64 uniquement pour une validation anticipée.

Wire Account activé en production

Les helpers privés préparés par pre.002 et réellement nécessaires à ces wrappers deviennent production-live :

• sérialisation des configs Account/Largest/Program ;
• conversion des encodings Account ;
• décodage SolanaAccountData ;
• décodage Account/KeyedAccount/AccountBalance ;
• conversion Pubkey wire ;
• construction interne de SolanaRpcResponse<T>.

Les helpers Cluster/Token préparatoires restent inchangés et ne deviennent pas production-live avant leurs tranches respectives.

Fixtures HTTP déterministes ajoutées

crates/ksp-onchain-transport-lib/fixtures/http/get_account_info.success.json
crates/ksp-onchain-transport-lib/fixtures/http/get_account_info.null.json
crates/ksp-onchain-transport-lib/fixtures/http/get_account_info.invalid_owner.json
crates/ksp-onchain-transport-lib/fixtures/http/get_largest_accounts.success.json
crates/ksp-onchain-transport-lib/fixtures/http/get_largest_accounts.invalid_address.json
crates/ksp-onchain-transport-lib/fixtures/http/get_minimum_balance_for_rent_exemption.success.json
crates/ksp-onchain-transport-lib/fixtures/http/get_minimum_balance_for_rent_exemption.error.json
crates/ksp-onchain-transport-lib/fixtures/http/get_multiple_accounts.success.json
crates/ksp-onchain-transport-lib/fixtures/http/get_program_accounts.bare.success.json
crates/ksp-onchain-transport-lib/fixtures/http/get_program_accounts.context.success.json

Les tests locaux utilisent un serveur HTTP loopback et n'accèdent pas à Internet.

Couverture de tests ajoutée

Les tests Accounts couvrent :

• request exacte pour chaque méthode ;
• config et omission de config vide ;
• succès typé ;
• account absent ;
• null dans getMultipleAccounts ;
• ordre de getMultipleAccounts ;
• résultat bare et contextualisé de getProgramAccounts ;
• invalid owner/address ;
• erreur JSON-RPC applicative ;
• limite des 100 comptes ;
• limite des 4 filtres ;
• limite raw memcmp de 128 octets ;
• mismatch cardinalité request/result de getMultipleAccounts.

Le test public compile explicitement les cinq méthodes sur HttpTransportPool et vérifie le nouveau code d'erreur.

Un canari release supplémentaire fige l'ensemble Accounts 0.2.2 exact :

getAccountInfo
getLargestAccounts
getMinimumBalanceForRentExemption
getMultipleAccounts
getProgramAccounts

Il vérifie aussi que ces descriptors restent Read + RetrySafe. Aucune famille Tokens/Cluster n'est déclarée typed-complete par cette tranche.

Après application, la cible Transport attendue devient :

98 unit tests
10 public API tests
3 release completeness tests

Fichiers ajoutés

crates/ksp-onchain-transport-lib/fixtures/http/get_account_info.success.json
crates/ksp-onchain-transport-lib/fixtures/http/get_account_info.null.json
crates/ksp-onchain-transport-lib/fixtures/http/get_account_info.invalid_owner.json
crates/ksp-onchain-transport-lib/fixtures/http/get_largest_accounts.success.json
crates/ksp-onchain-transport-lib/fixtures/http/get_largest_accounts.invalid_address.json
crates/ksp-onchain-transport-lib/fixtures/http/get_minimum_balance_for_rent_exemption.success.json
crates/ksp-onchain-transport-lib/fixtures/http/get_minimum_balance_for_rent_exemption.error.json
crates/ksp-onchain-transport-lib/fixtures/http/get_multiple_accounts.success.json
crates/ksp-onchain-transport-lib/fixtures/http/get_program_accounts.bare.success.json
crates/ksp-onchain-transport-lib/fixtures/http/get_program_accounts.context.success.json
deltas/0.2.2/pre.003.md

Fichiers modifiés

Cargo.toml
crates/ksp-onchain-transport-lib/src/error.rs
crates/ksp-onchain-transport-lib/src/lib.rs
crates/ksp-onchain-transport-lib/src/rpc_accounts.rs
crates/ksp-onchain-transport-lib/src/rpc_common.rs
crates/ksp-onchain-transport-lib/unit_tests/rpc_accounts.rs
crates/ksp-onchain-transport-lib/tests/public_api.rs
crates/ksp-onchain-transport-lib/tests/release_completeness.rs

Fichiers supprimés

Aucun.

Fichiers volontairement inchangés

CHANGELOG.md
ROADMAP.md
docs/plans/009-V0_2_2_HTTP_ACCOUNTS_TOKENS_CLUSTER_PLAN.md
crates/ksp-onchain-transport-lib/Cargo.toml
crates/ksp-onchain-transport-lib/src/executor.rs
crates/ksp-onchain-transport-lib/src/rpc_method.rs
crates/ksp-onchain-transport-lib/src/rpc_tokens.rs
crates/ksp-onchain-transport-lib/src/rpc_cluster.rs
crates/ksp-config-lib/**
config/**

La tranche suivante reste pre.004 — cinq wrappers Tokens.

Validations exécutées

• prise en compte de la validation opérateur propre de pre.002-fix.002 comme base ;
• relecture des règles VERSION_WORKFLOW.md et RULES_RUST.md applicables ;
• revérification de la documentation HTTP Solana actuelle pour les cinq méthodes Accounts ;
• recoupement des signatures/limites avec la source Agave v4.2.1 auditée par le plan ;
• validation JSON syntaxique des dix nouvelles fixtures ;
• contrôle statique de l'absence de unwrap, expect, panic! et #[allow(dead_code)] dans le code de production modifié ;
• contrôle statique que les cinq wrappers utilisent execute_standard_rpc et aucun appel reqwest direct ;
• contrôle statique de l'absence de nouvelle dépendance/feature ;
• contrôle exact des fichiers inclus dans l'archive d'échange.

Validations non exécutées

Le sandbox d'échange ne fournit pas cargo, rustc ou rustfmt. Les commandes suivantes doivent être exécutées sur le checkout opérateur avant commit :

cargo fmt --all
cargo check --workspace
cargo clippy --workspace --all-targets
cargo test -p ksp-onchain-transport-lib

cargo test --workspace reste réservé au checkpoint de clôture/session conformément au workflow KSP. Aucun cargo tree n'est requis par cette tranche puisqu'aucune dépendance ni feature n'a changé.

Décisions prises

• utiliser les DTOs pre.002 sans créer de seconde couche RPC ;
• conserver execute_standard_rpc() comme unique entrée d'exécution HTTP standard ;
• introduire un code d'erreur dédié aux paramètres typed invalides plutôt que détourner invalid_settings ;
• vérifier localement les limites dont KSP peut connaître la violation sans dépendance de décodage supplémentaire ;
• préserver les null, l'ordre et la dualité bare/context au lieu de normaliser artificiellement les réponses ;
• ne pas modifier Config ;
• ne pas ajouter de logging spécifique par méthode.

Questions ouvertes

Aucune question bloquante pour pre.004.

Suite

0.2.2-pre.004 : implémenter les cinq wrappers Tokens (getTokenAccountBalance, getTokenAccountsByDelegate, getTokenAccountsByOwner, getTokenLargestAccounts, getTokenSupply) avec les DTOs préparés, selector Mint | ProgramId, fixtures HTTP déterministes et conservation de uiAmount: null.