v0.2.2-pre.003
This commit is contained in:
335
deltas/0.2.2/pre.003.md
Normal file
335
deltas/0.2.2/pre.003.md
Normal file
@@ -0,0 +1,335 @@
|
||||
<!-- file: deltas/0.2.2/pre.003.md -->
|
||||
<!-- version: 1 -->
|
||||
|
||||
# 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 :
|
||||
|
||||
```text
|
||||
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é :
|
||||
|
||||
```text
|
||||
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 :
|
||||
|
||||
```text
|
||||
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 :
|
||||
|
||||
```text
|
||||
getAccountInfo
|
||||
getLargestAccounts
|
||||
getMinimumBalanceForRentExemption
|
||||
getMultipleAccounts
|
||||
getProgramAccounts
|
||||
```
|
||||
|
||||
Tous passent par la foundation HTTP `0.2.1` :
|
||||
|
||||
```text
|
||||
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` :
|
||||
|
||||
```text
|
||||
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 :
|
||||
|
||||
```text
|
||||
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 :
|
||||
|
||||
```text
|
||||
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 :
|
||||
|
||||
```text
|
||||
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 :
|
||||
|
||||
```text
|
||||
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 :
|
||||
|
||||
```text
|
||||
role + program Pubkey + Option<SolanaProgramAccountsConfig>
|
||||
-> SolanaProgramAccountsResult
|
||||
```
|
||||
|
||||
Le résultat préserve les deux formes wire :
|
||||
|
||||
```text
|
||||
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 :
|
||||
|
||||
```text
|
||||
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 :
|
||||
|
||||
```text
|
||||
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
|
||||
|
||||
```text
|
||||
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 :
|
||||
|
||||
```text
|
||||
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 :
|
||||
|
||||
```text
|
||||
98 unit tests
|
||||
10 public API tests
|
||||
3 release completeness tests
|
||||
```
|
||||
|
||||
## Fichiers ajoutés
|
||||
|
||||
```text
|
||||
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
|
||||
|
||||
```text
|
||||
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
|
||||
|
||||
```text
|
||||
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 :
|
||||
|
||||
```bash
|
||||
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`.
|
||||
Reference in New Issue
Block a user