228 lines
8.3 KiB
Markdown
228 lines
8.3 KiB
Markdown
<!-- 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.
|