khadhroony-solana-project/deltas/0.3.1/pre.004.md

Delta 0.3.1-pre.004 — admission cross-source + account state N1

Base requise

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 à :

0.3.1-pre.4

Audit account cross-source

Surfaces KSP relues :

HTTP
  getAccountInfo
  getMultipleAccounts
  getProgramAccounts

WebSocket
  accountSubscribe
  programSubscribe
  Helius standard account/program reuse

Yellowstone gRPC
  Account / AccountInfo

Champs communs retenus pour un état complet :

network
pubkey
slot
lamports
owner
executable
rent_epoch
complete account data bytes
canonical state hash

Règles d'admission :

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

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 :

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 :

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 :

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

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

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

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 :

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é

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.