Sasedev/khadhroony-solana-project
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

v0.3.10-pre.002

Browse Source
This commit is contained in:
SinuS von SifriduS
2026-09-06 09:58:31 +02:00
parent 6b434750c5
commit d0da907c00
17 changed files with 1453 additions and 29 deletions
Download Patch File Download Diff File Expand all files Collapse all files

49
docs/plans/031-V0_3_10_RAW_TRANSACTION_INGEST_PLAN.md
View File

@@ -1,5 +1,5 @@
<!-- file: docs/plans/031-V0_3_10_RAW_TRANSACTION_INGEST_PLAN.md -->
<!-- version: 1 -->
<!-- version: 2 -->
# Plan v0.3.10 — RAW Transaction commune + Worker d’ingestion multi-source
@@ -19,7 +19,7 @@ sources live
-> matériau transaction complet ou discovery/hydration
-> canonicalisation RAW v1 unique
-> RawTransaction + RawTransactionObservation
-> ksp-store-lib
-> persistence par le producteur concret via ksp-store-lib
```
Le Worker et le Job Backfill sont deux producteurs autonomes du même modèle durable. Aucun appel, lifecycle, orchestration, checkpoint ou contrat fonctionnel ne doit relier les deux.
@@ -161,7 +161,7 @@ Les décisions de fermeture du gate sont :
RAW v1 reste unique ; aucun RAW v2.
mainnet reste l’identité KSP canonique ; mainnet-beta reste alias externe/legacy.
ksp-raw-transaction-lib devient l’unique owner de la canonicalisation RAW v1.
La common crate dépend de Store façade, jamais de Transport/Config/Job/Worker.
La common crate dépend des modèles `ksp-store-api` conformément à `DEP-PIPE-006`, jamais de la façade runtime Store ni de Transport/Config/Job/Worker.
RawObservationKey reste producer-owned comme le contrat Store l’indique déjà.
Le Backfill conserve son observation-key Job-owned et ses métadonnées de campagne.
Le Worker possède son runtime concret, ses source IDs, ses observation keys et sa continuité de run.
@@ -290,7 +290,7 @@ Cible retenue :
```text
ksp-raw-transaction-lib
-> ksp-core-lib
-> ksp-store-lib default-features=false
-> ksp-store-api
-> serde_json
-> sha2
```
@@ -298,13 +298,14 @@ ksp-raw-transaction-lib
Justification :
- `ksp-core-lib` est nécessaire aux codes/erreurs KSP propres à la canonicalisation ;
- `ksp-store-lib` fournit les reexports approuvés de `RawTransaction`, `RawPayload`, provenance et primitives ;
- `ksp-store-api` fournit directement les modèles canoniques `RawTransaction`, `RawPayload`, provenance et primitives, conformément à `DEP-PIPE-006` ;
- `serde_json` reste requis par RAW v1 pour canonicaliser `meta` et préserver les états wire ;
- `sha2` reste requis pour le digest canonique exact.
Interdits :
```text
ksp-store-lib
ksp-onchain-transport-lib
ksp-config-lib
ksp-job-api
@@ -979,33 +980,29 @@ Une preuve sur `transactions` ne valide pas automatiquement `blocks`.
## 16. Graphe de dépendances cible
```text
ksp-core-lib
^
|
ksp-store-api <- ksp-store-lib <- ksp-raw-transaction-lib
^ ^
| |
| +-------+------------------+
| | |
| ksp-job-backfill-lib ksp-worker-raw-transaction-ingest-lib
| ^ ^
| | |
+----------+--------------------------+
|
ksp-onchain-transport-lib
ksp-raw-transaction-lib -> ksp-core-lib
ksp-raw-transaction-lib -> ksp-store-api -> ksp-core-lib
ksp-worker-api --------------------------> ksp-worker-raw-transaction-ingest-lib
ksp-logging-lib -------------------------> ksp-worker-raw-transaction-ingest-lib
ksp-job-backfill-lib -> ksp-raw-transaction-lib
ksp-job-backfill-lib -> ksp-store-lib -> ksp-store-api
ksp-job-backfill-lib -> ksp-onchain-transport-lib
ksp-job-backfill-lib -> ksp-job-api
ksp-worker-raw-transaction-ingest-lib -> ksp-raw-transaction-lib
ksp-worker-raw-transaction-ingest-lib -> ksp-store-lib -> ksp-store-api
ksp-worker-raw-transaction-ingest-lib -> ksp-onchain-transport-lib
ksp-worker-raw-transaction-ingest-lib -> ksp-worker-api
ksp-worker-raw-transaction-ingest-lib -> ksp-logging-lib
```
Lecture des flèches du schéma : les consumers dépendent des lower layers ; aucun lower layer ne dépend d’un consumer. Le dessin ne crée pas d’edge `ksp-store-lib -> common` : c’est bien `common -> ksp-store-lib`.
Lecture des flèches du schéma : les consumers dépendent des lower layers ; aucun lower layer ne dépend d’un consumer. `ksp-raw-transaction-lib` dépend directement de `ksp-store-api` comme pipeline RAW réutilisable ; `ksp-store-lib` reste la façade runtime utilisée séparément par les producteurs concrets pour la persistence.
Edges exacts attendus :
```text
ksp-raw-transaction-lib
-> ksp-core-lib
-> ksp-store-lib default-features=false
-> ksp-store-api
-> serde_json
-> sha2
@@ -1037,7 +1034,11 @@ Présente tranche : archive/règles, common extraction, capability matrix, fraî
### `pre.002` — common RAW foundation
Créer `ksp-raw-transaction-lib`, types source-neutral minimaux, signature parser, canonical JSON, SHA-256 et golden RAW v1 exact. Aucun Worker.
**Statut : réalisé.**
`ksp-raw-transaction-lib` matérialise les types source-neutral minimaux, le parser Base58 strict vers 64 octets, la canonicalisation JSON RAW v1, SHA-256 et l’assemblage transaction + observation producer-owned. Le golden `112` bytes / `220792...a7c3` est verrouillé par test. Aucun Worker ni migration Backfill n’est ouvert.
La matérialisation a révélé une correction normative du sizing `pre.001` : `DEP-PIPE-006` impose `ksp-store-api` au pipeline RAW et interdit `ksp-store-lib`. Le graphe et la section 5.4 sont donc corrigés dans cette tranche sans changer le contrat fonctionnel RAW.
### `pre.003` — migration Backfill vers common

130
docs/validation/027-V0_3_10_RAW_TRANSACTION_INGEST.md
View File

@@ -1,5 +1,5 @@
<!-- file: docs/validation/027-V0_3_10_RAW_TRANSACTION_INGEST.md -->
<!-- version: 1 -->
<!-- version: 2 -->
# Validation v0.3.10 — RAW Transaction commune + Worker d’ingestion
@@ -80,6 +80,31 @@ Tauri build : NON EXÉCUTÉ ici
Aucun de ces gates n’est déclaré PASS par cette session. Le journal opérateur fourni pour la stable `0.3.9` montre un gate complet antérieur ; il reste une preuve externe de la base stable, pas une exécution `pre.001` locale.
### 2.4 Gate opérateur après livraison de `pre.001`
Le 6 septembre 2026, l’opérateur a exécuté sur `workspace.package.version = 0.3.10-pre.1` :
```text
cargo fmt --all
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
cargo check --workspace
cargo clippy --workspace --all-targets --all-features -- -D warnings
```
Résultats communiqués :
```text
General Rust rule audit: clean
Rust export completeness audit: 0 candidate(s)
KSP workspace Rust rule audit: clean
Markdown table audit: clean (339 table(s), 753 file(s))
cargo check --workspace : terminé sans erreur
cargo clippy --workspace --all-targets --all-features -- -D warnings : terminé sans erreur
```
Ce gate opérateur ferme les contrôles demandés pour passer à `pre.002`. Aucun `cargo test` de `pre.001` n’a été fourni dans ce message et il n’est pas inventé.
## 3. Preuves de conception fermées en `pre.001`
### 3.1 Common RAW
@@ -92,7 +117,7 @@ format_version courant = 1
RawObservationKey est explicitement producer-owned dans Store
RawTransaction identity = network + signature
RawTransactionObservation est séparée de l’entité
ksp-store-lib reexporte les primitives nécessaires
`DEP-PIPE-006` impose les modèles `ksp-store-api` à la lower-layer RAW réutilisable ; la décision `ksp-store-lib` de `pre.001` est corrigée en `pre.002`
Backfill conversion mélange actuellement canonicalisation commune et metadata Job-owned
```
@@ -352,3 +377,104 @@ pre.015 final docs reconciliation
pre.016 publication preparation
rel.001 stable publication
```
## 11. Gate `pre.002` — common RAW foundation
État : **matérialisé ; gate Cargo opérateur requis**.
### 11.1 Crate et frontière
```text
crate = ksp-raw-transaction-lib
workspace.package.version = 0.3.10-pre.2
runtime async = aucun
Transport / Config / Job / Worker = absents
backend Store = absent
```
La dépendance exacte retenue après contrôle normatif est :
```text
ksp-raw-transaction-lib
-> ksp-core-lib
-> ksp-store-api
-> serde_json
-> sha2
```
Cette correction remplace la proposition `ksp-store-lib(default-features=false)` de `pre.001` car `DEP-PIPE-006` est plus spécifique : le pipeline RAW partagé peut dépendre de `ksp-store-api`, pas de `ksp-store-lib`.
### 11.2 Surface matérialisée
```text
RAW_TRANSACTION_FORMAT_ID = ksp.solana.raw_transaction
RAW_TRANSACTION_FORMAT_VERSION = 1
MIN_RAW_TRANSACTION_SIGNATURE_TEXT_BYTES = 64
MAX_RAW_TRANSACTION_SIGNATURE_TEXT_BYTES = 88
RawTransactionMaterial
RawTransactionWireField<T>
RawTransactionVersion
RawTransactionAcquisition
parse_raw_transaction_signature(...)
canonicalize_raw_transaction(...)
assemble_raw_transaction_acquisition(...)
ERROR_CODE_RAW_TRANSACTION_CANONICALIZATION_INVALID
ERROR_CODE_RAW_TRANSACTION_MATERIAL_INVALID
ERROR_CODE_RAW_TRANSACTION_SIGNATURE_INVALID
```
`RawObservationKey` reste fournie par le producteur. La common crate ne contient aucun domaine de clé Backfill/Worker.
### 11.3 Preuves déterministes ajoutées
```text
signature Base58 : bornes texte + alphabet + overflow + exactement 64 octets
RAW v1 golden : 112 bytes exacts
RAW v1 SHA-256 : 220792d2b15d262fda242cb220774ee9ddeffebf04dcfadabcf8ef76a9b1a7c3
meta/version/index : omitted != null != value
JSON : clés objet triées récursivement, arrays conservés, strings échappées, nombres conservés
block_time : négatif/overflow/max Store
payload : borne MAX_RAW_PAYLOAD_BYTES
Debug/error : aucune signature, transaction body ou meta hostile recopiée
acquisition : observation key producer-owned et référence exactement égale à la transaction
public API : consommation par crate-root
firewall : absence Store runtime/Transport/Config/Job/Worker/backend
```
### 11.4 Validation locale d’assemblage
Exécuté dans l’environnement d’assemblage :
```text
python3 scripts/audit_rust_workspace_rules.py
General Rust rule audit: clean
Rust export completeness audit: 0 candidate(s)
KSP workspace Rust rule audit: clean
python3 scripts/audit_markdown_tables.py README.md RULES.md ROADMAP.md CHANGELOG.md docs prompts crates deltas
Markdown table audit: clean (339 table(s), 754 file(s))
manifest TOML : 20 membres workspace, ksp-raw-transaction-lib présent
manifest common : 4 dépendances exactes, aucune feature/dev/build dependency
```
`cargo`, `rustc` et `rustfmt` ne sont pas présents dans cet environnement. Les gates Cargo de la nouvelle crate restent donc **NON EXÉCUTÉS LOCALEMENT**.
### 11.5 Gate opérateur demandé
```bash
cargo fmt --all
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
cargo check --workspace
cargo clippy --workspace --all-targets --all-features -- -D warnings
cargo test -p ksp-raw-transaction-lib
cargo tree -p ksp-raw-transaction-lib --edges normal
cargo tree -p ksp-raw-transaction-lib -e features
```
`pre.003` ne doit migrer le Backfill qu’après ce gate vert.