v0.3.1-pre.004
This commit is contained in:
@@ -1,5 +1,5 @@
|
||||
<!-- file: docs/plans/022-V0_3_1_STORE_RAW_PLAN.md -->
|
||||
<!-- version: 4 -->
|
||||
<!-- version: 5 -->
|
||||
|
||||
# Plan `0.3.1` — Store API RAW foundation
|
||||
|
||||
@@ -434,61 +434,123 @@ logsSubscribe
|
||||
|
||||
Le Store n'envoie lui-même aucun événement.
|
||||
|
||||
### 6.4 `RawAccountState` et observation
|
||||
### 6.4 `RawAccountState` et observation — matrice `pre.004`
|
||||
|
||||
Les réponses account complètes provenant de HTTP, WS ou Yellowstone peuvent potentiellement converger vers un même état canonique :
|
||||
L'audit de la surface KSP réelle confirme qu'un **état complet de compte** possède une sémantique commune entre HTTP, WebSocket et Yellowstone lorsque la source fournit les bytes complets et un slot durable. Le Store ne conserve pas la forme d'encodage réseau : base58/base64/base64+zstd et protobuf doivent être décodés avant construction du modèle commun.
|
||||
|
||||
Le modèle commun matérialisé est :
|
||||
|
||||
```text
|
||||
pubkey
|
||||
slot/context utile
|
||||
lamports
|
||||
owner
|
||||
executable
|
||||
rent_epoch
|
||||
data bytes exacts
|
||||
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
|
||||
```
|
||||
|
||||
Les détails propres à l'acquisition (`write_version`, signature source, startup, provider, transport, timing, etc.) appartiennent à `RawAccountObservation` lorsqu'ils sont utiles et disponibles.
|
||||
`state_hash` fait partie de la référence car une même account peut subir plusieurs écritures dans un slot, alors que les surfaces HTTP/WS standards n'exposent pas le `write_version` Yellowstone. Le digest permet à plusieurs sources observant **le même état complet** de converger sans promouvoir un ordinal provider-specific dans l'identité commune. Le producer/converter possède le calcul déterministe du digest ; Store API ne choisit pas l'algorithme de hash.
|
||||
|
||||
`RawAccountState`/`RawAccountObservation` doivent être **prévus dans `ksp-store-api`** après validation de la matrice de compatibilité. Leur persistence concrète PostgreSQL peut rester non implémentée au début de `0.3.2`.
|
||||
La matrice d'admission courante est :
|
||||
|
||||
Un compte demandé sous une forme déjà interprétée par le provider ne doit pas remplacer arbitrairement les bytes canoniques nécessaires à un futur decoder.
|
||||
| Source KSP | État complet commun | Slot durable | Admission `RawAccountState` |
|
||||
|------------------------------------|---------------------|---------------|-------------------------------------------------------------------------------------|
|
||||
| HTTP `getAccountInfo` | oui | oui | oui si account non-null, bytes complets et aucun `dataSlice`/`jsonParsed` |
|
||||
| HTTP `getMultipleAccounts` | oui | oui | oui par position non-null si bytes complets ; pubkey reprise depuis la requête |
|
||||
| HTTP `getProgramAccounts` | oui | conditionnel | oui seulement avec résultat contextualisé + bytes complets ; forme bare refusée |
|
||||
| WS `accountSubscribe` | oui | oui | oui si bytes complets ; pubkey reprise depuis l'identité de subscription |
|
||||
| WS `programSubscribe` | oui | conditionnel | oui seulement pour la forme contextualisée + bytes complets ; forme bare event-only |
|
||||
| Helius standard account/program WS | oui | idem standard | mêmes règles que le wire Solana standard réutilisé |
|
||||
| Yellowstone `Account` | oui | oui | oui si `accounts_data_slice` n'a pas tronqué les bytes |
|
||||
|
||||
### 6.5 Transaction status
|
||||
|
||||
Les surfaces signature/status peuvent représenter un fait distinct d'une transaction complète :
|
||||
Règles négatives :
|
||||
|
||||
```text
|
||||
signatureSubscribe
|
||||
getSignatureStatuses
|
||||
Yellowstone TransactionStatus
|
||||
provider equivalent
|
||||
jsonParsed
|
||||
request-side data slice
|
||||
Yellowstone accounts_data_slice
|
||||
program account sans context/slot
|
||||
account absent/null
|
||||
-X-> RawAccountState persistant incomplet
|
||||
```
|
||||
|
||||
Le candidat `TransactionStatusObservation` doit être étudié et, si la sémantique commune est démontrée, prévu dans l'API même si sa persistence n'est pas immédiatement implémentée.
|
||||
`space` n'est pas conservé comme vérité indépendante : lorsqu'on possède les bytes complets, leur longueur est déterministe. Les enrichissements Yellowstone `write_version`, `txn_signature` et `is_startup` appartiennent à `RawAccountObservation`. Le timestamp serveur et les filters/capture ids restent de la provenance lorsque le converter peut les représenter sans perte utile.
|
||||
|
||||
Il peut plus tard servir à un worker/analyser pour détecter des transitions de commitment/status. Ce déclenchement n'est pas une responsabilité du Store.
|
||||
|
||||
### 6.6 Slot, vote, block et Yellowstone Entry
|
||||
|
||||
Classification actuelle :
|
||||
La borne initiale Store-owned est :
|
||||
|
||||
```text
|
||||
complete account data <= 16 MiB
|
||||
```
|
||||
|
||||
Elle est un admission guard KSP, pas une affirmation sur la limite protocolaire Solana.
|
||||
|
||||
### 6.5 Transaction status — convergence insuffisante pour un modèle Store unique
|
||||
|
||||
L'audit `pre.004` conclut que les trois surfaces candidates ne représentent pas encore exactement le même fait :
|
||||
|
||||
| Source | Sémantique principale | Conclusion `0.3.1` |
|
||||
|-------------------------------|---------------------------------------------------------------------------|-----------------------------------------------------|
|
||||
| HTTP `getSignatureStatuses` | snapshot interrogé : slot, confirmations, error, confirmation status | candidat snapshot durable, non figé |
|
||||
| WS `signatureSubscribe` | event one-shot : received puis/ou commitment demandé atteint | event runtime, ownership Interface/worker à étudier |
|
||||
| Yellowstone TransactionStatus | update d'exécution : slot, signature, vote, index, error, sans commitment | event/status provider-neutral potentiel, non figé |
|
||||
|
||||
Créer maintenant un `TransactionStatusObservation` rempli d'options ferait perdre la distinction entre **snapshot interrogé**, **transition de commitment** et **update d'exécution**. Aucun modèle Store n'est donc ajouté en `pre.004`.
|
||||
|
||||
TODO avant matérialisation :
|
||||
|
||||
```text
|
||||
séparer explicitement snapshot durable vs event realtime
|
||||
étudier l'ownership ksp-interface-lib des events passifs
|
||||
prouver la correspondance des états/commitments
|
||||
prévoir un éventuel wake-up worker/analyser sans notification émise par Store
|
||||
```
|
||||
|
||||
### 6.6 Logs, slot, vote, block et Yellowstone Entry — classification fermée `pre.004`
|
||||
|
||||
Classification actuelle après audit :
|
||||
|
||||
```text
|
||||
logsSubscribe
|
||||
-> event realtime passif distinct
|
||||
-> signature + error + ordered log lines + context slot
|
||||
-> pas de RawLog Store
|
||||
-> ownership ksp-interface-lib/worker à préciser
|
||||
|
||||
slot/root/slotsUpdates
|
||||
-> event-only candidat ; persistence non justifiée actuellement
|
||||
-> event-only candidat
|
||||
-> aucune persistence N1 démontrée
|
||||
|
||||
vote
|
||||
-> event-only candidat si la forme est suffisamment commune entre les ledgers/providers qui l'exposent
|
||||
-> event-only candidat si la forme commune utile est prouvée
|
||||
-> aucune persistence N1 par défaut
|
||||
|
||||
getBlock / Yellowstone Block
|
||||
-> source/conteneur d'acquisition de RawTransaction par défaut
|
||||
RawBlock persistant seulement si un besoin block-level non reconstructible est démontré
|
||||
-> source/conteneur d'acquisition de RawTransaction
|
||||
-> RawBlock persistant reste IDEA uniquement
|
||||
|
||||
Yellowstone Entry
|
||||
-> examiné et non retenu actuellement : trop bas niveau et aucune destination replay/decomposition/event métier suffisante identifiée
|
||||
-> transport-only
|
||||
-> explicitement non retenu actuellement
|
||||
```
|
||||
|
||||
`RawBlock` reste une IDEA, pas un modèle actif. Recréer le ledger bloc par bloc sans besoin supplémentaire irait à l'encontre de l'objectif KSP de transformer la donnée blockchain en unités directement exploitables.
|
||||
Les logs contenus dans `RawTransaction` restent distincts de `logsSubscribe` : les premiers sont de la matière replayable de transaction et seront extraits en N2 STRUCTURAL ; le second est un événement realtime léger pouvant éventuellement déclencher l'hydratation de la transaction complète.
|
||||
|
||||
`RawBlock` ne doit être rouvert que si un besoin block-level non reconstructible apporte une valeur concrète au pipeline. Recréer le ledger bloc par bloc sans besoin supplémentaire irait à l'encontre de l'objectif KSP de produire des unités directement exploitables.
|
||||
|
||||
### 6.7 Modèles et capabilities sont indépendants
|
||||
|
||||
@@ -702,9 +764,25 @@ La signature ne doit pas être représentée comme un identifiant SQL `i64` dans
|
||||
|
||||
Chaque observation possède une clé d'idempotence déterministe fournie par le producer/composition selon un contrat documenté. Deux acquisitions légitimes distinctes peuvent donc être conservées même si elles pointent vers le même RAW.
|
||||
|
||||
### 10.4 Événements et autres familles
|
||||
### 10.4 Account states
|
||||
|
||||
Les événements realtime non persistés n'ont pas d'identité Store à inventer. Lorsqu'une nouvelle famille persistante est admise (`RawAccountState`, status durable, etc.), son identité d'idempotence doit être définie avec le modèle concret et ne jamais dépendre d'une primary key backend.
|
||||
La référence matérialisée par `pre.004` est :
|
||||
|
||||
```text
|
||||
RawAccountStateReference
|
||||
network
|
||||
pubkey
|
||||
slot
|
||||
canonical state hash
|
||||
```
|
||||
|
||||
Le hash couvre conceptuellement l'état canonique complet et sert à distinguer/converger les écritures multiples possibles dans un même slot sans dépendre de `write_version`. Le Store API ne calcule pas ce digest et ne transforme pas les bytes de transport.
|
||||
|
||||
Une `RawAccountObservation` possède sa propre `RawObservationKey`; plusieurs acquisitions HTTP/WS/gRPC peuvent donc viser la même référence d'état sans être fusionnées comme observations.
|
||||
|
||||
### 10.5 Événements et autres familles
|
||||
|
||||
Les événements realtime non persistés n'ont pas d'identité Store à inventer. Si une autre famille persistante est admise ultérieurement, son identité d'idempotence doit être définie avec le modèle concret et ne jamais dépendre d'une primary key backend.
|
||||
|
||||
Aucune promesse exactly-once distribuée n'est faite.
|
||||
|
||||
@@ -1293,7 +1371,7 @@ Introduire payload/reference/provenance/idempotence/timestamps bornés puis `Raw
|
||||
|
||||
### `pre.004` — Matrice cross-source + familles N1 prévues
|
||||
|
||||
Auditer HTTP/WS/gRPC pour `RawAccountState`/observation et `TransactionStatusObservation`; introduire les modèles communs seulement lorsque la sémantique converge. Classer explicitement logsSubscribe/slot/vote/block/Entry en event, IDEA ou rejet.
|
||||
Audit HTTP/WS/gRPC matérialisé. `RawAccountState`/observation sont admis avec bytes complets + slot et enrichissements source-specific séparés. `TransactionStatusObservation` est différé car snapshot HTTP, transition WS et update Yellowstone ne convergent pas encore assez. `logsSubscribe`/slot/vote restent event-only candidats, block reste conteneur/IDEA et Entry reste rejeté.
|
||||
|
||||
### `pre.005` — Capabilities backend extensibles
|
||||
|
||||
|
||||
Reference in New Issue
Block a user