v0.3.1-pre.004
This commit is contained in:
252
deltas/0.3.1/pre.004.md
Normal file
252
deltas/0.3.1/pre.004.md
Normal file
@@ -0,0 +1,252 @@
|
||||
<!-- file: deltas/0.3.1/pre.004.md -->
|
||||
<!-- version: 1 -->
|
||||
|
||||
# Delta `0.3.1-pre.004` — admission cross-source + account state N1
|
||||
|
||||
## Base requise
|
||||
|
||||
```text
|
||||
0.3.1-pre.3-fix.1
|
||||
```
|
||||
|
||||
Le gate opérateur de `pre.003-fix.001` est fourni vert : `cargo fmt --all`, audits Rust/Markdown, `cargo check --workspace`, Clippy workspace et `cargo test -p ksp-store-api` passent.
|
||||
|
||||
## Objectif
|
||||
|
||||
Auditer les formes HTTP/WS/gRPC déjà possédées par `ksp-onchain-transport-lib` avant d'ajouter une nouvelle famille N1, puis matérialiser uniquement le modèle dont la sémantique commune est démontrée.
|
||||
|
||||
La tranche :
|
||||
|
||||
- admet `RawAccountState`/`RawAccountObservation` avec bytes complets + slot durable ;
|
||||
- sépare les enrichissements Yellowstone de l'état canonique commun ;
|
||||
- refuse conceptuellement les réponses account partielles/parsées comme états persistants ;
|
||||
- diffère `TransactionStatusObservation` parce que snapshot HTTP, transition WS et update Yellowstone ne représentent pas encore le même fait ;
|
||||
- ferme la classification logs/slot/vote/block/Entry sans créer de modèles Store prématurés.
|
||||
|
||||
## Version
|
||||
|
||||
Le workspace passe à :
|
||||
|
||||
```text
|
||||
0.3.1-pre.4
|
||||
```
|
||||
|
||||
## Audit account cross-source
|
||||
|
||||
Surfaces KSP relues :
|
||||
|
||||
```text
|
||||
HTTP
|
||||
getAccountInfo
|
||||
getMultipleAccounts
|
||||
getProgramAccounts
|
||||
|
||||
WebSocket
|
||||
accountSubscribe
|
||||
programSubscribe
|
||||
Helius standard account/program reuse
|
||||
|
||||
Yellowstone gRPC
|
||||
Account / AccountInfo
|
||||
```
|
||||
|
||||
Champs communs retenus pour un état complet :
|
||||
|
||||
```text
|
||||
network
|
||||
pubkey
|
||||
slot
|
||||
lamports
|
||||
owner
|
||||
executable
|
||||
rent_epoch
|
||||
complete account data bytes
|
||||
canonical state hash
|
||||
```
|
||||
|
||||
Règles d'admission :
|
||||
|
||||
```text
|
||||
getAccountInfo/getMultipleAccounts
|
||||
-> admissibles avec account non-null + bytes complets
|
||||
|
||||
getProgramAccounts/programSubscribe
|
||||
-> slot/context obligatoire
|
||||
|
||||
accountSubscribe
|
||||
-> admissible avec bytes complets
|
||||
|
||||
Yellowstone Account
|
||||
-> admissible seulement sans accounts_data_slice tronquant les bytes
|
||||
|
||||
jsonParsed/dataSlice/bare program notification
|
||||
-X-> RawAccountState persistant
|
||||
```
|
||||
|
||||
`space` n'est pas une vérité stockée séparément lorsque les bytes complets sont présents : `data.len()` est déterministe.
|
||||
|
||||
## Modèles ajoutés
|
||||
|
||||
```text
|
||||
RawAccountStateReference
|
||||
network
|
||||
pubkey
|
||||
slot
|
||||
state_hash
|
||||
|
||||
RawAccountState
|
||||
reference
|
||||
lamports
|
||||
owner
|
||||
executable
|
||||
rent_epoch
|
||||
complete data bytes
|
||||
|
||||
RawAccountObservation
|
||||
observation_key
|
||||
account reference
|
||||
provenance
|
||||
optional write_version
|
||||
optional transaction_signature
|
||||
optional is_startup
|
||||
```
|
||||
|
||||
La référence inclut `state_hash` parce que plusieurs écritures d'une account peuvent survenir dans le même slot alors que HTTP/WS standards ne possèdent pas le `write_version` Yellowstone. Plusieurs sources observant le même état complet peuvent donc converger sans faire de l'ordinal Yellowstone un identifiant commun.
|
||||
|
||||
Le calcul du digest reste producer/converter-owned. `ksp-store-api` n'ajoute aucun codec ni algorithme de hash.
|
||||
|
||||
## Borne account data
|
||||
|
||||
Nouvelle admission guard Store-owned :
|
||||
|
||||
```text
|
||||
MAX_RAW_ACCOUNT_DATA_BYTES = 16 MiB
|
||||
```
|
||||
|
||||
Les bytes vides restent valides pour une account vide. La borne n'est pas présentée comme une limite protocolaire Solana.
|
||||
|
||||
`RawAccountState` n'implémente pas `Clone` et son `Debug` ne rend jamais les bytes.
|
||||
|
||||
## Observation account
|
||||
|
||||
Les informations présentes uniquement sur certaines sources restent observation-only :
|
||||
|
||||
```text
|
||||
Yellowstone write_version
|
||||
Yellowstone transaction signature
|
||||
Yellowstone is_startup
|
||||
```
|
||||
|
||||
HTTP/WS utilisent le même `RawAccountObservation` sans inventer ces valeurs.
|
||||
|
||||
Provider/protocol/method/endpoint/commitment/timing restent dans `RawAcquisitionProvenance` conformément à `pre.003`.
|
||||
|
||||
## Transaction status différé
|
||||
|
||||
Surfaces auditées :
|
||||
|
||||
```text
|
||||
getSignatureStatuses
|
||||
= snapshot interrogé avec confirmations/confirmationStatus
|
||||
|
||||
signatureSubscribe
|
||||
= event one-shot de réception/commitment demandé
|
||||
|
||||
Yellowstone TransactionStatus
|
||||
= update avec slot/signature/is_vote/index/error, sans commitment commun
|
||||
```
|
||||
|
||||
La tranche n'introduit donc aucun `TransactionStatusObservation` générique rempli d'options. La future conception devra distinguer snapshot durable et event realtime et auditer l'ownership `ksp-interface-lib` des événements passifs.
|
||||
|
||||
## Classification fermée
|
||||
|
||||
```text
|
||||
logsSubscribe
|
||||
-> event-only candidat ; pas de RawLog Store
|
||||
|
||||
transaction logMessages
|
||||
-> restent dans RawTransaction jusqu'à N2 STRUCTURAL
|
||||
|
||||
slot/root/slotsUpdates
|
||||
-> event-only candidat
|
||||
|
||||
vote
|
||||
-> event-only candidat après compatibilité utile
|
||||
|
||||
getBlock/Yellowstone Block
|
||||
-> conteneur d'acquisition RawTransaction ; RawBlock reste IDEA
|
||||
|
||||
Yellowstone Entry
|
||||
-> explicitement non retenu
|
||||
```
|
||||
|
||||
Le Store runtime ne publie aucune notification ; workers/analyzers/runtime possèdent les futurs déclenchements.
|
||||
|
||||
## Tests ajoutés/mis à jour
|
||||
|
||||
Unitaires account :
|
||||
|
||||
- état complet et champs communs ;
|
||||
- account data vide accepté ;
|
||||
- account data oversized rejeté ;
|
||||
- `Debug` sans bytes ;
|
||||
- metadata Yellowstone optionnelle sur observation.
|
||||
|
||||
Canaris d'intégration :
|
||||
|
||||
- surface crate-root `RawAccountState*`/`RawAccountObservation` ;
|
||||
- dépendance runtime toujours exactement Core-only ;
|
||||
- absence de Transport/backend/runtime/codec ;
|
||||
- absence de `TransactionStatusObservation`, `RawLogNotification`, `RawSlotEvent`, `RawVoteEvent`, `RawBlock` et `YellowstoneEntry` publics.
|
||||
|
||||
## Documentation mise à jour
|
||||
|
||||
```text
|
||||
docs/plans/022-V0_3_1_STORE_RAW_PLAN.md
|
||||
docs/validation/018-V0_3_1_STORE_RAW.md
|
||||
```
|
||||
|
||||
La matrice cross-source est désormais explicite et `pre.004` ne prétend pas que toutes les réponses on-chain constituent des modèles Store.
|
||||
|
||||
## Validations exécutées dans l'environnement de génération
|
||||
|
||||
```text
|
||||
python3 scripts/audit_rust_workspace_rules.py
|
||||
python3 scripts/audit_markdown_tables.py README.md RULES.md ROADMAP.md CHANGELOG.md docs prompts crates deltas/0.3.1
|
||||
```
|
||||
|
||||
## Validations non exécutées dans l'environnement de génération
|
||||
|
||||
`cargo`, `rustc` et `rustfmt` ne sont pas installés dans l'environnement de génération. L'opérateur doit donc exécuter :
|
||||
|
||||
```text
|
||||
cargo fmt --all
|
||||
cargo check --workspace
|
||||
cargo clippy --workspace --all-targets
|
||||
cargo test -p ksp-store-api
|
||||
```
|
||||
|
||||
Une commande non exécutée n'est pas déclarée PASS.
|
||||
|
||||
## Hors scope confirmé
|
||||
|
||||
```text
|
||||
source converter HTTP/WS/gRPC concret
|
||||
TransactionStatus model commun
|
||||
logs/slot/vote event model
|
||||
RawBlock persistence
|
||||
Yellowstone Entry persistence
|
||||
capabilities read/write
|
||||
queries/outcomes
|
||||
retention/tombstone concret
|
||||
ksp-store-lib
|
||||
ksp-store-postgres-lib
|
||||
PostgreSQL/tokio-postgres
|
||||
Config std.store
|
||||
N2 STRUCTURAL
|
||||
N3/N4
|
||||
```
|
||||
|
||||
## Suite
|
||||
|
||||
`0.3.1-pre.005` introduit les capabilities backend extensibles et object-safe pour les modèles persistants réellement matérialisés, sans façade runtime `Store`, sans backend PostgreSQL et sans obliger un backend à supporter toutes les familles N1.
|
||||
Reference in New Issue
Block a user