v0.2.2-pre.002
This commit is contained in:
227
deltas/0.2.2/pre.002.md
Normal file
227
deltas/0.2.2/pre.002.md
Normal file
@@ -0,0 +1,227 @@
|
||||
<!-- file: deltas/0.2.2/pre.002.md -->
|
||||
<!-- version: 1 -->
|
||||
|
||||
# Delta `0.2.2-pre.002` — primitives RPC Accounts/Tokens/Cluster et wire commun
|
||||
|
||||
## Base requise
|
||||
|
||||
Livraison précédente corrigée :
|
||||
|
||||
```text
|
||||
0.2.2-pre.001-fix.001
|
||||
workspace.package.version = "0.2.2-pre.1"
|
||||
```
|
||||
|
||||
Le plan canonique attendu est `docs/plans/009-V0_2_2_HTTP_ACCOUNTS_TOKENS_CLUSTER_PLAN.md` version 3, qui inclut le réaudit Agave `v4.2.1`.
|
||||
|
||||
## Objectif
|
||||
|
||||
Installer les primitives/configurations/résultats partagés nécessaires aux 22 wrappers `0.2.2`, sans encore implémenter les cinq wrappers
|
||||
Accounts prévus pour `pre.003`. La tranche mutualise les contrats nés avec les canaris `0.2.1`, fixe les formes wire Account/Token/Cluster et
|
||||
ajoute des fixtures déterministes pour les variantes nullable/versionnées identifiées pendant `pre.001` et son fix.
|
||||
|
||||
## Version Cargo
|
||||
|
||||
Conformément à `VER-ID-009`, la nouvelle prerelease synchronise le signal technique :
|
||||
|
||||
```text
|
||||
0.2.2-pre.1 -> 0.2.2-pre.2
|
||||
```
|
||||
|
||||
Aucune dépendance ou feature Cargo n'est ajoutée.
|
||||
|
||||
## Implémentation
|
||||
|
||||
### RPC commun
|
||||
|
||||
Un nouveau module commun possède désormais :
|
||||
|
||||
```text
|
||||
SolanaCommitment
|
||||
SolanaCommitmentConfig
|
||||
SolanaContextConfig
|
||||
SolanaRpcContext
|
||||
SolanaRpcResponse<T>
|
||||
```
|
||||
|
||||
`SolanaCommitment` et `SolanaRpcContext` ont été déplacés hors du module canari sans casser leurs réexports crate-root. `GetBalanceConfig`
|
||||
conserve son nom, ses champs internes, son constructeur, ses getters et sa forme `Debug` `0.2.1`; seule sa sérialisation réutilise désormais
|
||||
`SolanaContextConfig`.
|
||||
|
||||
Les helpers internes de décodage :
|
||||
|
||||
- convertissent les erreurs serde vers `ERROR_CODE_INVALID_RESPONSE` ;
|
||||
- convertissent explicitement les chaînes de public key vers `ksp_core_lib::Pubkey` ;
|
||||
- n'incluent pas la valeur de public key invalide dans les diagnostics.
|
||||
|
||||
### Accounts
|
||||
|
||||
Les primitives suivantes sont ajoutées :
|
||||
|
||||
```text
|
||||
SolanaAccountEncoding
|
||||
SolanaDataSliceConfig
|
||||
SolanaAccountInfoConfig
|
||||
SolanaLargestAccountsFilter
|
||||
SolanaLargestAccountsConfig
|
||||
SolanaMemcmpBytes
|
||||
SolanaMemcmpFilter
|
||||
SolanaProgramAccountFilter
|
||||
SolanaProgramAccountsConfig
|
||||
SolanaParsedAccountData
|
||||
SolanaAccountData
|
||||
SolanaAccount
|
||||
SolanaKeyedAccount
|
||||
SolanaAccountBalance
|
||||
SolanaProgramAccountsResult
|
||||
```
|
||||
|
||||
`SolanaAccountData` préserve les trois familles de wire : chaîne legacy, tuple encodé et `jsonParsed`. Le contenu `parsed` reste un
|
||||
`serde_json::Value`; aucun décodage Program/SPL n'entre dans Transport. `space` reste `Option<u64>`.
|
||||
|
||||
`SolanaProgramAccountFilter` conserve `dataSize`, `memcmp` et `tokenAccountState`. Les bytes `memcmp` peuvent rester base58/base64 textuels ou
|
||||
raw sans ajouter `bs58`/`base64`; les limites de cardinalité et de taille seront appliquées par les wrappers/validation `pre.003` conformément au
|
||||
plan.
|
||||
|
||||
### Tokens
|
||||
|
||||
Les primitives suivantes sont ajoutées :
|
||||
|
||||
```text
|
||||
SolanaTokenAccountSelector
|
||||
SolanaTokenAmount
|
||||
SolanaTokenAccountBalance
|
||||
```
|
||||
|
||||
Le selector est un enum `Mint | ProgramId`, ce qui interdit par construction un objet contenant simultanément les deux clés. `uiAmount` reste
|
||||
`Option<f64>` et `amount`/`uiAmountString` restent des chaînes exactes du wire.
|
||||
|
||||
### Cluster
|
||||
|
||||
Les DTOs/configs partagés suivants sont ajoutés :
|
||||
|
||||
```text
|
||||
SolanaClusterNode
|
||||
SolanaEpochInfo
|
||||
SolanaEpochSchedule
|
||||
SolanaSnapshotSlotInfo
|
||||
SolanaLeaderScheduleConfig
|
||||
SolanaLeaderScheduleRequest
|
||||
SolanaLeaderSchedule
|
||||
SolanaVoteAccountsConfig
|
||||
SolanaEpochCredits
|
||||
SolanaVoteAccountInfo
|
||||
SolanaVoteAccountStatus
|
||||
```
|
||||
|
||||
Le DTO node conserve tous les endpoints comme chaînes optionnelles et inclut `clientId: Option<String>` confirmé dans Agave `v4.2.1`.
|
||||
`SolanaVoteAccountInfo` inclut `inflationRewardsCommissionBps: Option<u16>` sans le dériver de `commission`, ainsi que les triples epoch credits
|
||||
sous un petit DTO nommé. `SolanaLeaderScheduleRequest` encode explicitement les overloads current-epoch/config et slot/config.
|
||||
|
||||
## Fixtures déterministes ajoutées
|
||||
|
||||
```text
|
||||
crates/ksp-onchain-transport-lib/fixtures/http/account_data.variants.json
|
||||
crates/ksp-onchain-transport-lib/fixtures/http/token_amount.null_ui.json
|
||||
crates/ksp-onchain-transport-lib/fixtures/http/cluster_node.v4_2_1.json
|
||||
crates/ksp-onchain-transport-lib/fixtures/http/vote_account.v4_2_1.json
|
||||
```
|
||||
|
||||
Elles couvrent notamment legacy/encoded/jsonParsed Account data, `space: null`, `uiAmount: null`, `clientId`, champs Cluster absents et présence
|
||||
de `inflationRewardsCommissionBps`. Un test supplémentaire vérifie l'absence de ce dernier champ pour une forme de noeud plus ancienne.
|
||||
|
||||
## Fichiers ajoutés
|
||||
|
||||
```text
|
||||
crates/ksp-onchain-transport-lib/src/rpc_common.rs
|
||||
crates/ksp-onchain-transport-lib/src/rpc_accounts.rs
|
||||
crates/ksp-onchain-transport-lib/src/rpc_tokens.rs
|
||||
crates/ksp-onchain-transport-lib/src/rpc_cluster.rs
|
||||
crates/ksp-onchain-transport-lib/unit_tests/rpc_common.rs
|
||||
crates/ksp-onchain-transport-lib/unit_tests/rpc_accounts.rs
|
||||
crates/ksp-onchain-transport-lib/unit_tests/rpc_tokens.rs
|
||||
crates/ksp-onchain-transport-lib/unit_tests/rpc_cluster.rs
|
||||
crates/ksp-onchain-transport-lib/fixtures/http/account_data.variants.json
|
||||
crates/ksp-onchain-transport-lib/fixtures/http/token_amount.null_ui.json
|
||||
crates/ksp-onchain-transport-lib/fixtures/http/cluster_node.v4_2_1.json
|
||||
crates/ksp-onchain-transport-lib/fixtures/http/vote_account.v4_2_1.json
|
||||
deltas/0.2.2/pre.002.md
|
||||
```
|
||||
|
||||
## Fichiers modifiés
|
||||
|
||||
```text
|
||||
Cargo.toml
|
||||
crates/ksp-onchain-transport-lib/src/lib.rs
|
||||
crates/ksp-onchain-transport-lib/src/rpc_canary.rs
|
||||
crates/ksp-onchain-transport-lib/unit_tests/rpc_canary.rs
|
||||
crates/ksp-onchain-transport-lib/tests/public_api.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-config-lib/**
|
||||
config/**
|
||||
```
|
||||
|
||||
Le plan ne change pas : `pre.003` reste consacré aux cinq wrappers Accounts.
|
||||
|
||||
## Validations exécutées
|
||||
|
||||
- reconstruction locale de l'état `v0.2.1 + pre.001 + pre.001-fix.001` à partir des archives fournies ;
|
||||
- relecture de `RULES_RUST.md`, `FILE_CONTRACTS.md`, `VERSION_WORKFLOW.md` et du plan `009` version 3 ;
|
||||
- recoupement des structures account/token Agave `v4.2.1` (`UiAccount`, `UiAccountData`, `UiAccountEncoding`, `UiTokenAmount`) ;
|
||||
- recoupement des extensions Cluster/Vote Agave `v4.2.1` (`client_id`, `inflation_rewards_commission_bps`) ;
|
||||
- contrôle statique des réexports crate-root et de l'absence de nouvelle dépendance Cargo ;
|
||||
- contrôle statique de l'absence de wrapper `0.2.2` ajouté prématurément dans cette tranche ;
|
||||
- contrôle des fixtures JSON avec un parseur JSON local ;
|
||||
- contrôle du contenu de l'archive d'échange après génération.
|
||||
|
||||
## Validations non exécutées
|
||||
|
||||
Le sandbox ne fournit pas `cargo` ni `rustfmt`. Les commandes suivantes n'ont donc pas été déclarées comme réussies et doivent être exécutées
|
||||
sur le checkout de développement avant commit :
|
||||
|
||||
```bash
|
||||
cargo fmt --all
|
||||
cargo check --workspace
|
||||
cargo clippy --workspace --all-targets
|
||||
cargo test -p ksp-onchain-transport-lib
|
||||
```
|
||||
|
||||
Conformément à `RUST-*`, `cargo test --workspace` reste requis au point de contrôle de session/clôture approprié. Aucun `cargo tree` supplémentaire
|
||||
n'est requis par ce delta, puisqu'aucune dépendance ni feature n'a changé.
|
||||
|
||||
## Décisions prises
|
||||
|
||||
- conserver les quatre canaris `0.2.1` et leurs noms publics ;
|
||||
- centraliser les primitives réellement communes plutôt que créer un mega DTO ;
|
||||
- utiliser `ksp_core_lib::Pubkey` dans les DTOs publics, avec conversion wire explicite ;
|
||||
- ne pas activer `serde` sur `solana-pubkey` uniquement pour les réponses RPC ;
|
||||
- ne pas ajouter `base64`, `bs58`, SPL ou client RPC haut niveau ;
|
||||
- conserver les champs provider/versionnés optionnels au lieu de les rendre obligatoires ;
|
||||
- ne pas ajouter de logs par DTO : l'observabilité reste au niveau du transport/executor.
|
||||
|
||||
## Questions ouvertes
|
||||
|
||||
Aucune question bloquante pour `pre.003`.
|
||||
|
||||
Le formatage final exact doit être produit par le `rustfmt` canonique du dépôt lors de l'application locale, puisque le binaire n'est pas disponible
|
||||
dans le sandbox d'échange.
|
||||
|
||||
## Suite
|
||||
|
||||
`0.2.2-pre.003` : implémenter les cinq wrappers Accounts (`getAccountInfo`, `getLargestAccounts`, `getMinimumBalanceForRentExemption`,
|
||||
`getMultipleAccounts`, `getProgramAccounts`) avec validation de cardinalité/filtres, décodage via les DTOs de cette tranche, serveur HTTP local et
|
||||
fixtures déterministes.
|
||||
Reference in New Issue
Block a user