v0.3.10-pre.008
This commit is contained in:
@@ -1,12 +1,12 @@
|
||||
# file: Cargo.toml
|
||||
# version: 502
|
||||
# version: 503
|
||||
|
||||
[workspace]
|
||||
resolver = "3"
|
||||
members = ["crates/ksp-app-backfill-desk", "crates/ksp-app-config-desk", "crates/ksp-app-solprices-desk", "crates/ksp-app-store-desk", "crates/ksp-app-wallet-desk", "crates/ksp-config-lib", "crates/ksp-core-lib", "crates/ksp-interface-lib", "crates/ksp-job-api", "crates/ksp-job-backfill-lib", "crates/ksp-logging-lib", "crates/ksp-offchain-transport-lib", "crates/ksp-onchain-transport-lib", "crates/ksp-program-api", "crates/ksp-raw-transaction-lib", "crates/ksp-store-api", "crates/ksp-store-lib", "crates/ksp-store-postgres-lib", "crates/ksp-wallet-lib", "crates/ksp-worker-api"]
|
||||
|
||||
[workspace.package]
|
||||
version = "0.3.10-pre.7"
|
||||
version = "0.3.10-pre.8"
|
||||
edition = "2024"
|
||||
license = "MIT"
|
||||
repository = "https://git.sasedev.com/Sasedev/khadhroony-solana-project"
|
||||
|
||||
20
ROADMAP.md
20
ROADMAP.md
@@ -1,5 +1,5 @@
|
||||
<!-- file: ROADMAP.md -->
|
||||
<!-- version: 105 -->
|
||||
<!-- version: 107 -->
|
||||
|
||||
# Roadmap KSP
|
||||
|
||||
@@ -40,7 +40,7 @@ Le roadmap décrit les objectifs à atteindre et les grandes étapes prévues. U
|
||||
|
||||
### Cadrage
|
||||
|
||||
- [X] `0.2.0` — Audit bot3, ordre fonctionnel de `0.2.x`, architecture durable, discipline de sizing et pipeline RAW/CORE/DECODE/SPECIALIZED stabilisés.
|
||||
- [X] `0.2.0` — Audit bot3, ordre fonctionnel de `0.2.x`, architecture durable, discipline de sizing et pipeline RAW/STRUCTURAL/DECODED/DOMAIN stabilisés.
|
||||
- [X] `0.2.1` — HTTP foundation stable : matrice 52+14, runtime/routing/résilience/exécution HTTP, 4 canaris typés, `std.transport`, adapter Config -> Transport, canaries de clôture, smoke Devnet opt-in et documentation durable validés ; les 48 wrappers typés restants sont reportés à `0.2.2`–`0.2.4`.
|
||||
|
||||
### Releases fonctionnelles décidées/pressenties
|
||||
@@ -87,13 +87,13 @@ RAW -> STRUCTURAL -> DECODED -> DOMAIN
|
||||
```
|
||||
|
||||
- **RAW** et **STRUCTURAL** ne nécessitent aucun décodage Program.
|
||||
- La progression n'est pas une chaîne obligatoire pour chaque famille : une donnée event-only peut s'arrêter en N1, et un état de compte pourra aller directement vers un futur decoder si aucune décomposition STRUCTURAL utile n'existe.
|
||||
- La progression n'est pas une chaîne obligatoire pour chaque famille : une donnée event-only peut s'arrêter en D1, et un état de compte pourra aller directement vers un futur decoder si aucune décomposition STRUCTURAL utile n'existe.
|
||||
- À la fin des couches horizontales RAW/STRUCTURAL réellement persistées, ajouter les jobs/workers/apps nécessaires avant d'ouvrir la couche suivante.
|
||||
- À partir de **DECODED**, avancer verticalement groupe par groupe ; **DOMAIN** désigne les projections métier et la matérialisation est le processus qui les produit.
|
||||
|
||||
## 0.3.x — RAW / acquisition persistée
|
||||
|
||||
- [X] `0.3.1` — `ksp-store-api` stable : modèles N1 RAW backend-agnostic `RawTransaction` et `RawAccountState` avec observations, provenance, payload/hash/timestamps bornés, 10 capabilities object-safe, queries cursorisées sans plafond métier arbitraire, outcomes idempotence/conflit et lifecycle logique rétention/tombstone/force-rehydrate ; aucun backend physique, Config, runtime Store, notification dédiée ni surface STRUCTURAL/DECODED/DOMAIN.
|
||||
- [X] `0.3.1` — `ksp-store-api` stable : modèles D1 RAW backend-agnostic `RawTransaction` et `RawAccountState` avec observations, provenance, payload/hash/timestamps bornés, 10 capabilities object-safe, queries cursorisées sans plafond métier arbitraire, outcomes idempotence/conflit et lifecycle logique rétention/tombstone/force-rehydrate ; aucun backend physique, Config, runtime Store, notification dédiée ni surface STRUCTURAL/DECODED/DOMAIN.
|
||||
- [X] `0.3.2` — `ksp-store-lib` + `ksp-store-postgres-lib` stables comme fondation runtime/backend PostgreSQL : feature `postgres` par défaut, `Store` lié à un unique `RawNetworkId`, Config `std.store` avec targets/bases `devnet`/`mainnet`/`testnet`, pool Deadpool borné, `tokio-postgres`, TLS Rustls `Disabled`/`VerifyFull`, moteur de migrations privé `V000` + SHA-256/advisory lock, health/readiness portable et close borné. Gate complet + PostgreSQL réel major 17 verts ; aucune table/capability `RawTransaction`/`RawAccountState` métier n'est encore ajoutée.
|
||||
- [X] `0.3.3` — Vertical slice PostgreSQL `RawTransaction` complète sur `ksp-store-lib` + `ksp-store-postgres-lib` : six capabilities transaction/observation/rétention, V001 physique liée à un réseau, acquisition canonical+observation atomique, idempotence/conflit, get/list keyset cursorisé, archive/purge/tombstone/ForceRehydrate, hardening des erreurs et du schéma, concurrence et rollback validés sur PostgreSQL 17.
|
||||
- [X] `0.3.4` — Vertical slice PostgreSQL `RawAccountState` complète sur `ksp-store-lib` + `ksp-store-postgres-lib` : quatre capabilities account ajoutées aux six transaction pour une conformance RAW 10/10, V002 additive de 32 ressources au-dessus de V000/V001 immuables, state+observation atomiques, idempotence/conflit exacts, metadata Yellowstone observation-only, get/list keyset `(slot,pubkey,state_hash)` avec cursor KSPA anti-replay, hardening cross-family et live validé sur PostgreSQL 17 sans rétention destructive account.
|
||||
@@ -113,14 +113,14 @@ RAW -> STRUCTURAL -> DECODED -> DOMAIN
|
||||
### TODO/IDEAS — applications spécialisées et control plane
|
||||
|
||||
- [ ] **TODO** — faire évoluer `ksp-app-store-desk` avec chaque nouvelle couche réellement persistée : RAW d'abord, puis STRUCTURAL, DECODED, journal de processing/materialization et projections DOMAIN selon les contrats effectivement disponibles. Les vues avancées restent backend-agnostiques et passent uniquement par `ksp-store-lib`.
|
||||
- [ ] **TODO** — différer une future `ksp-app-control-desk` jusqu'à ce que KSP dispose au minimum d'un niveau N3/D3 de processing/materialization exploitable et de plusieurs decoders réels. Cette application sera une surface **end-user simplifiée** : démarrer/arrêter les flux autorisés, lancer une recherche courante, voir l'état global et les erreurs importantes. Elle ne recopiera pas le diagnostic détaillé, les réglages avancés, les tables complètes ni toutes les fonctions des `ksp-app-*-desk` spécialisées, qui resteront les outils d'administration, développement et investigation approfondie.
|
||||
- [ ] **TODO** — différer une future `ksp-app-control-desk` jusqu'à ce que KSP dispose au minimum d'une couche D3 DECODED de processing/materialization exploitable et de plusieurs decoders réels. Cette application sera une surface **end-user simplifiée** : démarrer/arrêter les flux autorisés, lancer une recherche courante, voir l'état global et les erreurs importantes. Elle ne recopiera pas le diagnostic détaillé, les réglages avancés, les tables complètes ni toutes les fonctions des `ksp-app-*-desk` spécialisées, qui resteront les outils d'administration, développement et investigation approfondie.
|
||||
|
||||
### TODO/IDEAS — taxonomie N1, processing et rétention
|
||||
### TODO/IDEAS — taxonomie D1, processing et rétention
|
||||
|
||||
- [ ] **TODO** — maintenir la matrice d’admission HTTP/WS/gRPC/provider lors de toute nouvelle famille N1 : plusieurs sources ne convergent vers un même struct que si elles satisfont la même sémantique sans perte.
|
||||
- [ ] **TODO** — maintenir la matrice d’admission HTTP/WS/gRPC/provider lors de toute nouvelle famille D1 : plusieurs sources ne convergent vers un même struct que si elles satisfont la même sémantique sans perte.
|
||||
- [X] **TODO `0.3.9`** — matrice RAW Transaction unique produite et consolidée dans `docs/architecture/011-RAW_TRANSACTION_ACQUISITION.md`, avec séparation possibilités/support/preuve, capabilities orthogonales aux producteurs, provenance/déduplication/continuité et handoffs désormais scindés `0.3.11`–`0.3.14` Worker live / `0.3.16` Backfill historique.
|
||||
- [ ] **TODO Helius `0.3.13`** — ajouter uniquement les profils/capabilities Helius réellement nécessaires au Worker live après revalidation des surfaces/tier courants ; réutiliser exclusivement `KSP_SECRET_HELIUS_API_KEY` via Config et la surface `transactionSubscribe` déjà Transport-owned, sans SDK provider ni second client parallèle.
|
||||
- [X] **TODO réseau** — identité KSP canonique fixée à `mainnet` dans Config/Store/Transport/tests ; `mainnet-beta` reste uniquement un alias legacy/externe lorsque la frontière provider l'exige. Les données N1 RAW antérieures restent non autoritaires pendant cette phase et aucune compatibilité de base de test n'impose l'ancien libellé.
|
||||
- [X] **TODO réseau** — identité KSP canonique fixée à `mainnet` dans Config/Store/Transport/tests ; `mainnet-beta` reste uniquement un alias legacy/externe lorsque la frontière provider l'exige. Les données D1 RAW antérieures restent non autoritaires pendant cette phase et aucune compatibilité de base de test n'impose l'ancien libellé.
|
||||
- [X] `RawAccountState` + observation — contrat commun stabilisé en `0.3.1` avec bytes complets + slot, provenance séparée et enrichissements source-specific optionnels ; la persistence PostgreSQL physique est complétée en `0.3.4` avec les quatre capabilities account et la conformance RAW 10/10.
|
||||
- [ ] **TODO** — statut/commitment transactionnel restant : `0.3.5` couvre uniquement le fait passif d’exécution `slot + signature + outcome`; réauditer séparément `signatureSubscribe` et `getSignatureStatuses` lorsqu’un consumer de commitment/snapshot réel apparaît, sans fusionner snapshot, transition et execution update dans un modèle Option-soup.
|
||||
- [ ] **IDEA** — logs realtime enrichis : `logsSubscribe` alimente déjà la projection minimale `TransactionExecutionEvent`, mais un éventuel `TransactionLogEvent` portant les lignes de log reste différé dans `docs/IDEAS.md` jusqu’à démonstration d’un consumer et de bornes explicites. `logMessages` reste dans `RawTransaction` jusqu’à STRUCTURAL ; le wake-up post-commit reste distinct et Store API-owned conformément à `KSP-NOTIFY-*`.
|
||||
@@ -133,13 +133,13 @@ RAW -> STRUCTURAL -> DECODED -> DOMAIN
|
||||
- [X] rétention physique `RawTransaction` PostgreSQL — `0.3.3` matérialise `Full -> Archived -> Purged`, tombstone et ForceRehydrate atomiques ; `Compacted` reste explicitement unsupported tant qu’aucune représentation compactée réelle n’existe.
|
||||
- [ ] **TODO** — policy de rétention/compaction : définir les critères d’éligibilité fondés sur les preuves de processing et la maintenance worker/job ; Store applique une transition demandée mais ne décide pas seul qu’un RAW peut être archivé/purgé, et la compaction physique ne sera ajoutée qu’avec un besoin réel.
|
||||
- [X] frontière `ksp-interface-lib` / `ksp-store-api` — ownership documenté et canaris de non-duplication stabilisés en `0.3.1`; les events passifs non persistés restent Interface, les modèles persistants/replayables restent Store API.
|
||||
- [ ] **IDEA** — réauditer la structure de processing/decode/materialization historique kbot2/kbot3 lors de l’ouverture de N2/N3 ; conserver l’isolation instruction/CPI et les statuts terminal/versionnés, sans reprendre automatiquement le schéma SQL historique.
|
||||
- [ ] **IDEA** — réauditer la structure de processing/decode/materialization historique kbot2/kbot3 lors de l’ouverture de D2/D3 ; conserver l’isolation instruction/CPI et les statuts terminal/versionnés, sans reprendre automatiquement le schéma SQL historique.
|
||||
|
||||
## Série STRUCTURAL suivante
|
||||
|
||||
- [ ] Définir la persistence STRUCTURAL canonique Solana générique pour les familles réellement décomposables.
|
||||
- [ ] Implémenter en priorité `RawTransaction -> STRUCTURAL` sans decoder Program : transaction/message, comptes/références, instructions top-level, CPI/inner instructions, logs/meta/balances/return data et relations structurelles.
|
||||
- [ ] Vérifier avant extension si d'autres familles N1 possèdent une vraie décomposition STRUCTURAL utile ; ne pas créer de niveau vide par convention.
|
||||
- [ ] Vérifier avant extension si d'autres familles D1 possèdent une vraie décomposition STRUCTURAL utile ; ne pas créer de niveau vide par convention.
|
||||
- [ ] Ajouter replay/backfill RAW -> STRUCTURAL avec processing versionné.
|
||||
- [ ] Ajouter le worker/service STRUCTURAL utile sans le coupler à un worker RAW concret.
|
||||
- [ ] Faire évoluer `ksp-app-store-desk` avec des vues/requêtes STRUCTURAL lorsque cette couche est réellement persistée ; ne pas créer une seconde application de browsing des mêmes données.
|
||||
|
||||
97
crates/ksp-raw-transaction-lib/README.md
Normal file
97
crates/ksp-raw-transaction-lib/README.md
Normal file
@@ -0,0 +1,97 @@
|
||||
<!-- file: crates/ksp-raw-transaction-lib/README.md -->
|
||||
<!-- version: 1 -->
|
||||
|
||||
# ksp-raw-transaction-lib
|
||||
|
||||
`ksp-raw-transaction-lib` fournit la lower-layer KSP source-neutral commune aux producteurs de `RawTransaction`.
|
||||
|
||||
La crate transforme un matériau transactionnel complet déjà acquis en représentation RAW canonique KSP, fournit les primitives de parsing de signature et de sérialisation wire Solana nécessaires aux voies qualifiées, puis permet d'associer la transaction canonique à une observation/provenance possédée par le producer.
|
||||
|
||||
Elle ne possède aucun Transport, Config, Job, Worker, runtime async, Store runtime ou backend physique.
|
||||
|
||||
## Responsabilités
|
||||
|
||||
La façade crate-root expose quatre familles de contrats.
|
||||
|
||||
### Canonicalisation RAW Transaction
|
||||
|
||||
- `RawTransactionMaterial` ;
|
||||
- `RawTransactionWireField<T>` pour préserver distinctement omission, `null` explicite et valeur ;
|
||||
- `RawTransactionVersion` ;
|
||||
- `canonicalize_raw_transaction` ;
|
||||
- `RAW_TRANSACTION_FORMAT_ID` et `RAW_TRANSACTION_FORMAT_VERSION`.
|
||||
|
||||
La canonicalisation produit un `ksp_store_api::RawTransaction` avec payload KSP déterministe et SHA-256 de contenu. Le producer reste responsable de fournir un matériau source-neutral complet ; la crate n'effectue aucune I/O réseau.
|
||||
|
||||
### Signature Solana
|
||||
|
||||
- `parse_raw_transaction_signature` valide et décode une signature Base58 bornée vers exactement 64 bytes ;
|
||||
- `extract_raw_transaction_signature_from_binary_base64` extrait la première signature canonique d'un wire transactionnel Base64 complet ;
|
||||
- les bornes textuelles publiques permettent l'admission avant décodage.
|
||||
|
||||
Les diagnostics ne recopient pas la signature hostile.
|
||||
|
||||
### Wire transactionnel source-neutral
|
||||
|
||||
La surface `RawSolana*` représente et sérialise les messages transactionnels Solana Legacy, V0 et V1 nécessaires à la common RAW :
|
||||
|
||||
- `RawSolanaMessageVersion` ;
|
||||
- `RawSolanaMessageHeader` ;
|
||||
- `RawSolanaCompiledInstruction` ;
|
||||
- `RawSolanaAddressTableLookup` ;
|
||||
- `RawSolanaTransactionConfig` ;
|
||||
- `RawSolanaTransactionMessage` ;
|
||||
- `RawSolanaTransactionWire` ;
|
||||
- `serialize_solana_transaction_wire` et `serialize_solana_transaction_wire_base64`.
|
||||
|
||||
Cette surface est un contrat de wire commun, pas un decoder Program et pas une façade Transport.
|
||||
|
||||
### Acquisition canonique + observation
|
||||
|
||||
`assemble_raw_transaction_acquisition` associe une transaction canonique à :
|
||||
|
||||
- une `RawObservationKey` déterministe possédée par le producer ;
|
||||
- une `RawAcquisitionProvenance` sûre possédée par le producer.
|
||||
|
||||
Le résultat `RawTransactionAcquisition` contient exactement une entité canonique et une observation liée. Il ne persiste rien lui-même.
|
||||
|
||||
## Frontières
|
||||
|
||||
```text
|
||||
Transport / fixture / import / producer
|
||||
|
|
||||
v
|
||||
matériau source-neutral
|
||||
|
|
||||
v
|
||||
ksp-raw-transaction-lib
|
||||
| |
|
||||
| +-> exact Solana wire helpers
|
||||
v
|
||||
RawTransaction + RawTransactionObservation
|
||||
|
|
||||
v
|
||||
producer runtime -> ksp-store-lib / capability Store appropriée
|
||||
```
|
||||
|
||||
Interdictions structurelles :
|
||||
|
||||
```text
|
||||
ksp-raw-transaction-lib -X-> ksp-onchain-transport-lib
|
||||
ksp-raw-transaction-lib -X-> ksp-config-lib
|
||||
ksp-raw-transaction-lib -X-> ksp-job-api / ksp-job-backfill-lib
|
||||
ksp-raw-transaction-lib -X-> ksp-worker-api / worker concret
|
||||
ksp-raw-transaction-lib -X-> ksp-store-lib / backend physique
|
||||
```
|
||||
|
||||
Le graphe normal reste limité à `ksp-core-lib`, `ksp-store-api`, `base64`, `serde_json` et `sha2`.
|
||||
|
||||
## Relation avec STRUCTURAL
|
||||
|
||||
Cette crate appartient à **RAW**. Elle ne réalise pas la décomposition Store D2 `RAW -> STRUCTURAL`. La future couche STRUCTURAL consommera le RAW persistant et le décomposera en unités Solana génériques plus fines avant tout décodage Program.
|
||||
|
||||
## Documentation
|
||||
|
||||
- [`USAGE.md`](USAGE.md) — utilisation durable de la façade publique ;
|
||||
- [`../../docs/architecture/008-DATA_MATERIALIZATION_AND_STORE.md`](../../docs/architecture/008-DATA_MATERIALIZATION_AND_STORE.md) — frontières RAW / STRUCTURAL / DECODED / DOMAIN ;
|
||||
- [`../../docs/architecture/011-RAW_TRANSACTION_ACQUISITION.md`](../../docs/architecture/011-RAW_TRANSACTION_ACQUISITION.md) — qualification des sources `RawTransaction`.
|
||||
153
crates/ksp-raw-transaction-lib/USAGE.md
Normal file
153
crates/ksp-raw-transaction-lib/USAGE.md
Normal file
@@ -0,0 +1,153 @@
|
||||
<!-- file: crates/ksp-raw-transaction-lib/USAGE.md -->
|
||||
<!-- version: 1 -->
|
||||
|
||||
# Utilisation de ksp-raw-transaction-lib
|
||||
|
||||
Cette page décrit la façade publique durable de `ksp-raw-transaction-lib`. Les consumers utilisent uniquement les exports du crate-root.
|
||||
|
||||
## Parser une signature transactionnelle
|
||||
|
||||
Lorsqu'une source fournit une signature Base58 textuelle, la convertir avec le parser commun plutôt que de dupliquer le décodage :
|
||||
|
||||
```rust
|
||||
fn parse_signature(value: &str) -> ksp_core_lib::Result<ksp_store_api::RawTransactionSignature> {
|
||||
return ksp_raw_transaction_lib::parse_raw_transaction_signature(value);
|
||||
}
|
||||
```
|
||||
|
||||
Le résultat contient exactement 64 bytes canoniques. Les entrées vides, hors bornes, Base58 invalides ou de longueur décodée incorrecte sont rejetées sans recopier la valeur hostile dans l'erreur.
|
||||
|
||||
Lorsqu'un wire Base64 complet contient déjà son tableau de signatures, utiliser :
|
||||
|
||||
```rust
|
||||
fn embedded_signature(value: &str) -> ksp_core_lib::Result<ksp_store_api::RawTransactionSignature> {
|
||||
return ksp_raw_transaction_lib::extract_raw_transaction_signature_from_binary_base64(value);
|
||||
}
|
||||
```
|
||||
|
||||
## Construire et sérialiser un wire Solana source-neutral
|
||||
|
||||
Le producer peut projeter son DTO Transport/protobuf vers les types `RawSolana*`, puis utiliser le sérialiseur commun. Exemple V1 minimal :
|
||||
|
||||
```rust
|
||||
fn serialize_v1() -> ksp_core_lib::Result<std::string::String> {
|
||||
let message = ksp_raw_transaction_lib::RawSolanaTransactionMessage::new(
|
||||
ksp_raw_transaction_lib::RawSolanaMessageVersion::V1,
|
||||
ksp_raw_transaction_lib::RawSolanaMessageHeader::new(1, 0, 0),
|
||||
vec![[1_u8; 32]],
|
||||
[2_u8; 32],
|
||||
vec![ksp_raw_transaction_lib::RawSolanaCompiledInstruction::new(0, vec![0], vec![3])],
|
||||
vec![],
|
||||
std::option::Option::Some(ksp_raw_transaction_lib::RawSolanaTransactionConfig::default()),
|
||||
);
|
||||
let wire = ksp_raw_transaction_lib::RawSolanaTransactionWire::new(vec![[4_u8; 64]], message);
|
||||
return ksp_raw_transaction_lib::serialize_solana_transaction_wire_base64(&wire);
|
||||
}
|
||||
```
|
||||
|
||||
Pour Legacy ou V0, choisir `RawSolanaMessageVersion::Legacy` ou `V0` et fournir uniquement les éléments admis par cette version. Le sérialiseur valide les invariants structurels avant de produire les bytes.
|
||||
|
||||
`RawSolanaAddressTableLookup` représente les lookups V0. `RawSolanaTransactionConfig` représente la configuration inline V1 ; le cas explicite où toutes ses options valent `None` reste sémantiquement présent.
|
||||
|
||||
## Construire le matériau RAW canonique
|
||||
|
||||
Une fois le wire transactionnel Base64 et les métadonnées source-neutral disponibles, construire `RawTransactionMaterial`. Les états wire doivent conserver la différence entre champ absent, `null` explicite et valeur :
|
||||
|
||||
```rust
|
||||
fn material(
|
||||
network: ksp_store_api::RawNetworkId,
|
||||
signature: ksp_store_api::RawTransactionSignature,
|
||||
transaction_base64: std::string::String,
|
||||
) -> ksp_raw_transaction_lib::RawTransactionMaterial {
|
||||
return ksp_raw_transaction_lib::RawTransactionMaterial::binary_base64(
|
||||
network,
|
||||
signature,
|
||||
42,
|
||||
std::option::Option::None,
|
||||
transaction_base64,
|
||||
ksp_raw_transaction_lib::RawTransactionWireField::Omitted,
|
||||
ksp_raw_transaction_lib::RawTransactionWireField::Value(ksp_raw_transaction_lib::RawTransactionVersion::Legacy),
|
||||
ksp_raw_transaction_lib::RawTransactionWireField::Omitted,
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
Pour une source où la signature doit être extraite du wire lui-même, `RawTransactionMaterial::binary_base64_with_embedded_signature` évite un second parser producer-owned.
|
||||
|
||||
## Canonicaliser vers RawTransaction
|
||||
|
||||
La canonicalisation est déterministe pour un même matériau complet :
|
||||
|
||||
```rust
|
||||
fn canonicalize(
|
||||
material: ksp_raw_transaction_lib::RawTransactionMaterial,
|
||||
) -> ksp_core_lib::Result<ksp_store_api::RawTransaction> {
|
||||
return ksp_raw_transaction_lib::canonicalize_raw_transaction(material);
|
||||
}
|
||||
```
|
||||
|
||||
La crate :
|
||||
|
||||
- canonicalise les sous-arbres JSON significatifs ;
|
||||
- conserve les états omission / `null` / valeur ;
|
||||
- construit le payload au format KSP RAW Transaction ;
|
||||
- calcule son SHA-256 ;
|
||||
- applique les bornes communes avant construction du modèle Store.
|
||||
|
||||
Elle ne persiste pas la transaction et ne choisit aucune politique de retry, endpoint ou source.
|
||||
|
||||
## Associer l'observation du producer
|
||||
|
||||
Le producer construit sa provenance avec les types Store API, puis assemble l'entité et l'observation :
|
||||
|
||||
```rust
|
||||
fn acquisition(
|
||||
transaction: ksp_store_api::RawTransaction,
|
||||
) -> ksp_core_lib::Result<ksp_raw_transaction_lib::RawTransactionAcquisition> {
|
||||
let provider = match ksp_store_api::RawProvenanceCode::new("example") {
|
||||
std::result::Result::Ok(value) => value,
|
||||
std::result::Result::Err(error) => return std::result::Result::Err(error),
|
||||
};
|
||||
let protocol = match ksp_store_api::RawProvenanceCode::new("solana.http") {
|
||||
std::result::Result::Ok(value) => value,
|
||||
std::result::Result::Err(error) => return std::result::Result::Err(error),
|
||||
};
|
||||
let method = match ksp_store_api::RawProvenanceCode::new("get_transaction") {
|
||||
std::result::Result::Ok(value) => value,
|
||||
std::result::Result::Err(error) => return std::result::Result::Err(error),
|
||||
};
|
||||
let received_at = match ksp_store_api::RawTimestamp::from_unix_millis(1_700_000_000_000) {
|
||||
std::result::Result::Ok(value) => value,
|
||||
std::result::Result::Err(error) => return std::result::Result::Err(error),
|
||||
};
|
||||
let provenance = ksp_store_api::RawAcquisitionProvenance::new(
|
||||
provider,
|
||||
protocol,
|
||||
method,
|
||||
ksp_store_api::RawAcquisitionOrigin::Live,
|
||||
received_at,
|
||||
);
|
||||
return std::result::Result::Ok(ksp_raw_transaction_lib::assemble_raw_transaction_acquisition(
|
||||
transaction,
|
||||
ksp_store_api::RawObservationKey::new([7_u8; 32]),
|
||||
provenance,
|
||||
));
|
||||
}
|
||||
```
|
||||
|
||||
La clé d'observation doit être déterministe selon la politique du producer. Plusieurs sources peuvent produire des observations différentes pour la même identité canonique `(network, signature)`.
|
||||
|
||||
## Persister depuis un Job ou un Worker
|
||||
|
||||
La common crate ne dépend pas du Store runtime. Le lifecycle host concret récupère les deux parties puis appelle la façade Store appropriée :
|
||||
|
||||
```rust
|
||||
let (transaction, observation) = acquisition.into_parts();
|
||||
// Le Job/Worker concret transmet ensuite transaction + observation à ksp-store-lib.
|
||||
```
|
||||
|
||||
Ne pas introduire `ksp-store-lib`, Transport, Config, Job ou Worker dans `ksp-raw-transaction-lib` pour simplifier cet appel. La direction de dépendance reste du producer vers la common RAW, puis du producer vers le Store runtime.
|
||||
|
||||
## Frontière avec STRUCTURAL
|
||||
|
||||
Ne pas utiliser cette crate pour décoder des Programs ou pour produire directement des unités STRUCTURAL. Son résultat reste D1 RAW. La décomposition `RAW -> STRUCTURAL` appartient à une couche ultérieure et réutilise le RAW durable comme input.
|
||||
109
deltas/0.3.10/pre.008-fix.001.md
Normal file
109
deltas/0.3.10/pre.008-fix.001.md
Normal file
@@ -0,0 +1,109 @@
|
||||
<!-- file: deltas/0.3.10/pre.008-fix.001.md -->
|
||||
<!-- version: 1 -->
|
||||
|
||||
# Delta `0.3.10-pre.008-fix.001` — fermeture de la nomenclature D1–D4
|
||||
|
||||
## 1. Base requise
|
||||
|
||||
```text
|
||||
0.3.10-pre.008
|
||||
workspace.package.version = 0.3.10-pre.8
|
||||
```
|
||||
|
||||
Le gate opérateur de `pre.008` est vert : format check, audits Rust/Markdown, `cargo check --workspace` et Clippy workspace/all-targets/all-features avec `-D warnings` passent sur cette baseline.
|
||||
|
||||
## 2. Objet
|
||||
|
||||
Corriger les dernières survivances actives de l'ancienne notation des couches de données découvertes pendant la préparation de `pre.009`, sans les absorber dans le couloir de publication.
|
||||
|
||||
`pre.008` a réservé :
|
||||
|
||||
```text
|
||||
N1–N4 = niveaux architecturaux de composants
|
||||
D1–D4 = couches durables Store/data
|
||||
|
||||
D1 RAW
|
||||
D2 STRUCTURAL
|
||||
D3 DECODED
|
||||
D4 DOMAIN
|
||||
```
|
||||
|
||||
La correction reste donc strictement dans la responsabilité de réconciliation documentaire de `pre.008`.
|
||||
|
||||
## 3. Version Cargo
|
||||
|
||||
Correction strictement documentaire :
|
||||
|
||||
```text
|
||||
workspace.package.version reste 0.3.10-pre.8
|
||||
Cargo.toml inchangé
|
||||
```
|
||||
|
||||
Aucun identifiant `fix` n'est reflété dans Cargo pour ce correctif documentaire.
|
||||
|
||||
## 4. Corrections
|
||||
|
||||
### `ROADMAP.md`
|
||||
|
||||
Les usages actifs qui désignaient encore les couches de données avec `N1`, `N2` ou `N3` deviennent :
|
||||
|
||||
```text
|
||||
N1 data/event-only -> D1
|
||||
« taxonomie N1 » -> « taxonomie D1 »
|
||||
« nouvelle famille N1 » -> « nouvelle famille D1 »
|
||||
« ouverture N2/N3 » -> « ouverture D2/D3 »
|
||||
« autres familles N1 » -> « autres familles D1 »
|
||||
```
|
||||
|
||||
Les occurrences où `N1–N4` désignent réellement les niveaux architecturaux restent inchangées.
|
||||
|
||||
### `docs/architecture/011-RAW_TRANSACTION_ACQUISITION.md`
|
||||
|
||||
La mention active « migration de données N1 » devient « migration de données D1 ».
|
||||
|
||||
Les anciennes traces historiques de releases, prompts, plans ou validations clôturés ne sont pas réécrites.
|
||||
|
||||
## 5. Hors périmètre
|
||||
|
||||
```text
|
||||
Cargo.toml
|
||||
CHANGELOG.md
|
||||
prompt 0.3.11
|
||||
code / tests / Config / schemas
|
||||
README / USAGE
|
||||
plans / validations
|
||||
autres corrections de publication
|
||||
```
|
||||
|
||||
`pre.009` reste la prochaine tranche et conservera uniquement CHANGELOG, ROADMAP, prompt suivant et fichiers mécaniques.
|
||||
|
||||
## 6. Fichiers modifiés
|
||||
|
||||
```text
|
||||
ROADMAP.md
|
||||
docs/architecture/011-RAW_TRANSACTION_ACQUISITION.md
|
||||
```
|
||||
|
||||
## 7. Fichier ajouté
|
||||
|
||||
```text
|
||||
deltas/0.3.10/pre.008-fix.001.md
|
||||
```
|
||||
|
||||
## 8. Validation
|
||||
|
||||
```bash
|
||||
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
|
||||
```
|
||||
|
||||
Comme le correctif est exclusivement documentaire et ne touche pas Cargo, Rust, build, runtime ou Config, aucun replay du workspace complet n'est requis si ces audits restent verts.
|
||||
|
||||
## 9. Suite
|
||||
|
||||
Après application et audits documentaires verts :
|
||||
|
||||
```text
|
||||
0.3.10-pre.009 — préparation de publication + prompt 0.3.11
|
||||
0.3.10-rel.001 — publication stable mécanique
|
||||
```
|
||||
201
deltas/0.3.10/pre.008.md
Normal file
201
deltas/0.3.10/pre.008.md
Normal file
@@ -0,0 +1,201 @@
|
||||
<!-- file: deltas/0.3.10/pre.008.md -->
|
||||
<!-- version: 1 -->
|
||||
|
||||
# Delta `0.3.10-pre.008` — réconciliation documentaire finale RAW commune / cross-source
|
||||
|
||||
## 1. Base requise
|
||||
|
||||
```text
|
||||
0.3.10-pre.007 appliquée
|
||||
workspace.package.version = 0.3.10-pre.7
|
||||
```
|
||||
|
||||
Le rejeu opérateur communiqué le 8 septembre 2026 ferme entièrement le gate technique final de `pre.007` : audits Rust/Markdown, `cargo check --workspace`, Clippy workspace strict, `cargo test --workspace --all-targets --all-features`, suites ciblées common/Transport/Backfill et graphes Cargo demandés sont exécutés sans échec.
|
||||
|
||||
Les smokes live opt-in restent `ignored` par politique et ne sont pas revendiqués comme preuves réseau exécutées.
|
||||
|
||||
## 2. Objet
|
||||
|
||||
Effectuer exclusivement la réconciliation documentaire finale de `0.3.10` après fermeture technique de `pre.007`, sans nouveau développement fonctionnel.
|
||||
|
||||
Cette tranche :
|
||||
|
||||
```text
|
||||
réconcilie la nomenclature durable des couches de données Store ;
|
||||
synchronise la séquence fonctionnelle active avec le redécoupage 0.3.10 -> 0.3.16 ;
|
||||
réconcilie les règles et documents d'architecture actifs ;
|
||||
complète la documentation durable de ksp-raw-transaction-lib ;
|
||||
ne modifie aucun comportement Rust, API, dépendance, feature ou runtime.
|
||||
```
|
||||
|
||||
## 3. Version
|
||||
|
||||
Cette livraison est une prerelease non-fix :
|
||||
|
||||
```text
|
||||
workspace.package.version = 0.3.10-pre.8
|
||||
commit attendu = v0.3.10-pre.008
|
||||
aucun tag prerelease
|
||||
```
|
||||
|
||||
Aucune version npm/Tauri n'est modifiée.
|
||||
|
||||
## 4. Nomenclature canonique des couches de données
|
||||
|
||||
La progression durable du Store devient :
|
||||
|
||||
```text
|
||||
D1 RAW -> D2 STRUCTURAL -> D3 DECODED -> D4 DOMAIN
|
||||
```
|
||||
|
||||
Sémantique :
|
||||
|
||||
```text
|
||||
D1 RAW = matériau acquis et conservé avant décomposition métier ;
|
||||
D2 STRUCTURAL = décomposition Solana générique en structures unitaires exploitables ;
|
||||
D3 DECODED = décodage générique des structures selon les contrats de programmes ;
|
||||
D4 DOMAIN = matérialisation métier/spécialisée issue des données décodées.
|
||||
```
|
||||
|
||||
L'ancien nom de couche D2 `CORE` est abandonné. Il créait une ambiguïté avec `ksp-core-lib` et le domaine Core fondamental alors que cette couche Store représente une décomposition structurelle du RAW.
|
||||
|
||||
Cette normalisation ne renomme jamais :
|
||||
|
||||
```text
|
||||
ksp-core-lib ;
|
||||
le domaine Core architectural fondamental ;
|
||||
les noms propres comme « Solana Core Programs » ;
|
||||
les traces historiques clôturées qui documentent l'ancienne terminologie.
|
||||
```
|
||||
|
||||
Les niveaux architecturaux `N1–N4` de `docs/architecture/002-LAYERS_AND_DEPENDENCIES.md` restent réservés aux niveaux de composants. Les couches de données utilisent désormais `D1–D4` afin d'éviter toute collision de vocabulaire. Les plans Store historiques qui parlaient de N1–N4 data restent interprétables selon la correspondance ci-dessus mais ne sont pas réécrits en masse.
|
||||
|
||||
## 5. Conséquences STRUCTURAL
|
||||
|
||||
Les rôles actifs deviennent explicitement :
|
||||
|
||||
```text
|
||||
STRUCTURAL persistence
|
||||
RAW -> STRUCTURAL replay/backfill
|
||||
STRUCTURAL job
|
||||
STRUCTURAL worker
|
||||
STRUCTURAL inspection/control app lorsque pertinent
|
||||
```
|
||||
|
||||
Le `STRUCTURAL job` est borné et rejouable. Le `STRUCTURAL worker` traite continuellement le backlog RAW. Aucun des deux ne réalise le décodage Program : la frontière `STRUCTURAL -> DECODED` reste en aval.
|
||||
|
||||
## 6. Séquence fonctionnelle active
|
||||
|
||||
`docs/plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md` est remis en cohérence avec la trajectoire réellement matérialisée :
|
||||
|
||||
```text
|
||||
0.3.1 ksp-store-api RAW
|
||||
0.3.2 Store runtime + backend PostgreSQL foundation
|
||||
0.3.3 persistence RawTransaction
|
||||
0.3.4 persistence RawAccountState
|
||||
0.3.5 Interface acquisition events
|
||||
0.3.6 ksp-job-api + RawTransaction Backfill
|
||||
0.3.7 ksp-app-backfill-desk
|
||||
0.3.8 ksp-app-store-desk RAW
|
||||
0.3.9 ksp-worker-api + audit acquisition RawTransaction
|
||||
0.3.10 common ksp-raw-transaction-lib + preuves cross-source
|
||||
0.3.11-0.3.14 Worker RAW ingest découpé par responsabilité
|
||||
0.3.15 ksp-app-raw-transaction-ingest-desk
|
||||
0.3.16 Backfill multi-source / multi-stratégie
|
||||
```
|
||||
|
||||
Le redécoupage ne change pas les frontières Job/Worker arrêtées précédemment et ne réintroduit aucun Worker concret dans `0.3.10`.
|
||||
|
||||
## 7. Documentation de `ksp-raw-transaction-lib`
|
||||
|
||||
La crate common RAW étant désormais une bibliothèque complétée de `0.3.10`, elle reçoit :
|
||||
|
||||
```text
|
||||
crates/ksp-raw-transaction-lib/README.md
|
||||
crates/ksp-raw-transaction-lib/USAGE.md
|
||||
```
|
||||
|
||||
Le `README.md` fixe son rôle, ses dépendances autorisées et ses frontières. Le `USAGE.md` reste volontairement version-neutre et montre uniquement l'utilisation durable de la surface publique de crate root : signatures, wire Solana, canonicalisation RAW et assemblage acquisition/observation.
|
||||
|
||||
La documentation rappelle explicitement que le résultat de cette crate reste D1 RAW et qu'elle n'implémente pas la transformation RAW -> STRUCTURAL.
|
||||
|
||||
## 8. ROADMAP et publication
|
||||
|
||||
`ROADMAP.md` est modifié uniquement pour éliminer l'ancien libellé actif `RAW/CORE/DECODE/SPECIALIZED` au profit de `RAW/STRUCTURAL/DECODED/DOMAIN`.
|
||||
|
||||
Les changements de statut de release, le CHANGELOG et la préparation du prompt `0.3.11` restent réservés à `pre.009`.
|
||||
|
||||
## 9. Traces historiques
|
||||
|
||||
Les prompts, deltas, plans et validations clôturés ne sont pas réécrits en masse. Une ancienne occurrence de `CORE` dans une trace historique peut donc rester légitime lorsqu'elle décrit l'état documentaire de sa livraison.
|
||||
|
||||
Cette tranche corrige les documents durables actifs, pas l'histoire du repository.
|
||||
|
||||
## 10. Fichiers modifiés
|
||||
|
||||
```text
|
||||
Cargo.toml
|
||||
ROADMAP.md
|
||||
docs/IDEAS.md
|
||||
docs/architecture/002-LAYERS_AND_DEPENDENCIES.md
|
||||
docs/architecture/003-COMPONENT_CONTRACTS.md
|
||||
docs/architecture/004-COMPONENT_INVENTORY.md
|
||||
docs/architecture/005-DEPENDENCY_GRAPH.md
|
||||
docs/architecture/006-WIRE_AND_PROGRAM.md
|
||||
docs/architecture/008-DATA_MATERIALIZATION_AND_STORE.md
|
||||
docs/architecture/009-ACQUISITION_WORKERS_AND_JOBS.md
|
||||
docs/architecture/010-APPS_SERVICES_SCENARIOS_AND_CONTROL.md
|
||||
docs/plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md
|
||||
docs/plans/031-V0_3_10_RAW_TRANSACTION_INGEST_PLAN.md
|
||||
docs/rules/RULES_DEPENDENCIES.md
|
||||
docs/rules/RULES_KSP.md
|
||||
docs/validation/027-V0_3_10_RAW_TRANSACTION_INGEST.md
|
||||
```
|
||||
|
||||
## 11. Fichiers ajoutés
|
||||
|
||||
```text
|
||||
crates/ksp-raw-transaction-lib/README.md
|
||||
crates/ksp-raw-transaction-lib/USAGE.md
|
||||
deltas/0.3.10/pre.008.md
|
||||
```
|
||||
|
||||
Aucun fichier Rust source, manifest de crate, Config, frontend ou dépendance n'est modifié.
|
||||
|
||||
## 12. Validation d'assemblage
|
||||
|
||||
À enregistrer avant livraison :
|
||||
|
||||
```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
|
||||
contrôle statique nomenclature D1-D4 / STRUCTURAL
|
||||
contrôle statique version/scope/headers
|
||||
contrôle exact de l'inventaire delta
|
||||
contrôle archive delta et reconstruction overlay
|
||||
```
|
||||
|
||||
Cargo/rustc/rustfmt ne sont pas disponibles dans l'environnement d'assemblage ; aucun gate Cargo de `pre.008` n'est déclaré PASS localement. Le gate technique complet de `pre.007` reste la baseline opérateur fermée ; `pre.008` ne modifie aucun code ni graphe de dépendances.
|
||||
|
||||
## 13. Rejeu opérateur `pre.008`
|
||||
|
||||
Comme cette tranche est documentaire hors incrément mécanique de version workspace, le rejeu minimal attendu est :
|
||||
|
||||
```bash
|
||||
cargo fmt --all -- --check
|
||||
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
|
||||
```
|
||||
|
||||
Un échec ouvre `pre.008-fix.NNN`. Aucun nouveau test fonctionnel ou smoke live n'est requis par cette réconciliation documentaire seule.
|
||||
|
||||
## 14. Suite
|
||||
|
||||
Après retour opérateur vert sur `0.3.10-pre.8` :
|
||||
|
||||
```text
|
||||
pre.009 = préparation publication, CHANGELOG, statuts ROADMAP et prompt 0.3.11
|
||||
rel.001 = publication stable mécanique de 0.3.10
|
||||
```
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- file: docs/IDEAS.md -->
|
||||
<!-- version: 27 -->
|
||||
<!-- version: 28 -->
|
||||
|
||||
# Idées à explorer
|
||||
|
||||
@@ -159,9 +159,9 @@ Conserver comme pistes séparées les offres pré-exécution/shred/deshred (Heli
|
||||
|
||||
**Status :** Retenue, granularité révisée
|
||||
|
||||
RAW et CORE peuvent disposer de workers dédiés à la fin de leur couche respective.
|
||||
RAW et STRUCTURAL peuvent disposer de workers dédiés à la fin de leur couche respective.
|
||||
|
||||
À partir de DECODE, ne pas figer à l'avance une chaîne globale `generic-materializer -> domain-projector` pour tout Solana : la granularité des workers/processors doit émerger des vertical slices Program réels et réutiliser les mêmes transformations que les jobs de replay correspondants.
|
||||
À partir de DECODED, ne pas figer à l'avance une chaîne globale `generic-materializer -> domain-projector` pour tout Solana : la granularité des workers/processors doit émerger des vertical slices Program réels et réutiliser les mêmes transformations que les jobs de replay correspondants.
|
||||
|
||||
### Worker control
|
||||
|
||||
@@ -322,7 +322,7 @@ Les futurs processing outcomes versionnés constituent la preuve durable de trai
|
||||
|
||||
**Status :** Requalifiée par `0.2.0-pre.003`
|
||||
|
||||
L'ancienne liste figée `ksp-job-replay-core` / `ksp-job-replay-generic-materialization` / `ksp-job-replay-domain-projection` n'est plus une décision KSP. La frontière `RAW -> CORE` pourra introduire un replay Core lorsque CORE sera ouverte. À partir de DECODE, les jobs de replay doivent émerger avec les groupes/capacités verticaux réels et réutiliser la même logique que le processing live correspondant, sans imposer un materializer/projector global à tout Solana.
|
||||
L'ancienne liste figée `ksp-job-replay-core` / `ksp-job-replay-generic-materialization` / `ksp-job-replay-domain-projection` n'est plus une décision KSP. La frontière `RAW -> STRUCTURAL` pourra introduire un replay STRUCTURAL lorsque STRUCTURAL sera ouverte. À partir de DECODED, les jobs de replay doivent émerger avec les groupes/capacités verticaux réels et réutiliser la même logique que le processing live correspondant, sans imposer un materializer/projector global à tout Solana.
|
||||
|
||||
### Notification backend de référence
|
||||
|
||||
@@ -344,7 +344,7 @@ Définir le schéma SQL, la durée/renouvellement de lease et la technique Postg
|
||||
|
||||
Fixer les noms/types exacts et distinguer Produced, NoOutput, NotApplicable, Unsupported et failure déterministe sans transformer des situations normales en erreurs.
|
||||
|
||||
### Contexte stateful des projections SPECIALIZED
|
||||
### Contexte stateful des projections DOMAIN
|
||||
|
||||
**Status :** À explorer avec la première projection nécessitant un état existant
|
||||
|
||||
@@ -426,4 +426,4 @@ Si cette capacité devient utile, l’intégration doit être conçue dans la pi
|
||||
|
||||
`0.2.0-pre.002` avait fixé le premier séquencement concret. `0.2.1-pre.001-fix.001` le recalibre désormais sur `0.2.1 -> 0.2.13`, sous réserve du gate de dimensionnement de chaque `pre.001` et avec possibilité d'enchaîner plusieurs releases complètement clôturées dans une même session lorsque le sizing le permet.
|
||||
|
||||
Les séries après RAW/CORE ne sont volontairement pas numérotées programme par programme à ce stade : la règle est de redécouper chaque vertical slice selon sa taille réelle et de ne jamais ouvrir une release qui ne peut pas être clôturée dans sa session.
|
||||
Les séries après RAW/STRUCTURAL ne sont volontairement pas numérotées programme par programme à ce stade : la règle est de redécouper chaque vertical slice selon sa taille réelle et de ne jamais ouvrir une release qui ne peut pas être clôturée dans sa session.
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- file: docs/architecture/002-LAYERS_AND_DEPENDENCIES.md -->
|
||||
<!-- version: 11 -->
|
||||
<!-- version: 12 -->
|
||||
|
||||
# Couches et dépendances KSP
|
||||
|
||||
@@ -26,7 +26,7 @@ Les niveaux architecturaux N1–N4 décrivent les familles de composants du proj
|
||||
### N3 — Données, jobs, workers et processing
|
||||
|
||||
- `ksp-store-api` / `ksp-store-lib` ;
|
||||
- `ksp-materializer-api` / implementations lorsque DECODE s'ouvre ;
|
||||
- `ksp-materializer-api` / implementations lorsque DECODED s'ouvre ;
|
||||
- `ksp-job-api`, `ksp-job-backfill-lib` puis les jobs concrets introduits par les couches ;
|
||||
- `ksp-worker-api` et workers ;
|
||||
- processors/pipelines spécialisés réellement réutilisés.
|
||||
@@ -45,32 +45,32 @@ La chaîne de données canonique est :
|
||||
|
||||
```text
|
||||
D1 RAW
|
||||
-> D2 CORE
|
||||
-> D3 DECODE
|
||||
-> D4 SPECIALIZED
|
||||
-> D2 STRUCTURAL
|
||||
-> D3 DECODED
|
||||
-> D4 DOMAIN
|
||||
```
|
||||
|
||||
Aliases fonctionnels :
|
||||
|
||||
```text
|
||||
RAW -> CORE -> DECODE -> SPECIALIZED
|
||||
RAW -> STRUCTURAL -> DECODED -> DOMAIN
|
||||
```
|
||||
|
||||
RAW et CORE sont indépendants du décodage Program.
|
||||
RAW et STRUCTURAL sont indépendants du décodage Program.
|
||||
|
||||
CORE est une normalisation générique de Solana : structure des blocs, transactions, messages, comptes, instructions/CPI brutes, logs/meta et relations fondamentales.
|
||||
STRUCTURAL est une normalisation générique de Solana : structure des blocs, transactions, messages, comptes, instructions/CPI brutes, logs/meta et relations fondamentales.
|
||||
|
||||
Le premier decoder Program intervient seulement à `CORE -> DECODE`.
|
||||
Le premier decoder Program intervient seulement à `STRUCTURAL -> DECODED`.
|
||||
|
||||
## Progression par couche
|
||||
|
||||
### RAW et CORE
|
||||
### RAW et STRUCTURAL
|
||||
|
||||
Ces deux couches sont construites horizontalement.
|
||||
|
||||
À la fin de chaque couche, KSP ajoute les composants d'exploitation nécessaires : persistence, replay/backfill, worker/service et application de contrôle lorsque utiles.
|
||||
|
||||
### DECODE et SPECIALIZED
|
||||
### DECODED et DOMAIN
|
||||
|
||||
À partir du décodage, KSP progresse verticalement par groupe fonctionnel :
|
||||
|
||||
@@ -134,7 +134,7 @@ Les applications Tauri restent minces :
|
||||
- instrumentation frontend ;
|
||||
- aucun déplacement de logique de transport, Wallet, Config, Program, Store ou Materializer dans Tauri.
|
||||
|
||||
Des applications spécialisées sont ajoutées au fur et à mesure pour valider les couches : Config Desk, Wallet Desk, `ksp-app-solprices-desk`, `ksp-app-backfill-desk`, `ksp-app-store-desk`, CORE tooling puis Market Desk. `ksp-app-solprices-desk` reste une HID mince : elle consomme l’inventaire, les observations, les états et les opérations génériques de `ksp-offchain-transport-lib` sans connaître les providers, leurs endpoints, leurs credentials ni leurs limites. `ksp-app-backfill-desk` compose Config, Transport HTTP, Store et `ksp-job-backfill-lib` sans absorber découverte, retry/rate-limit, persistance ou checkpoint ; son frontend ne reçoit que des DTOs sûrs et le checkpoint de reprise reste Rust-only. `ksp-app-store-desk` compose Config, Logging et `ksp-store-lib` pour une inspection RAW read-only : il n'accède ni au backend physique ni au SQL et sépare la pagination random-access de l'interface de la pagination cursor/keyset réservée aux consumers machine.
|
||||
Des applications spécialisées sont ajoutées au fur et à mesure pour valider les couches : Config Desk, Wallet Desk, `ksp-app-solprices-desk`, `ksp-app-backfill-desk`, `ksp-app-store-desk`, STRUCTURAL tooling puis Market Desk. `ksp-app-solprices-desk` reste une HID mince : elle consomme l’inventaire, les observations, les états et les opérations génériques de `ksp-offchain-transport-lib` sans connaître les providers, leurs endpoints, leurs credentials ni leurs limites. `ksp-app-backfill-desk` compose Config, Transport HTTP, Store et `ksp-job-backfill-lib` sans absorber découverte, retry/rate-limit, persistance ou checkpoint ; son frontend ne reçoit que des DTOs sûrs et le checkpoint de reprise reste Rust-only. `ksp-app-store-desk` compose Config, Logging et `ksp-store-lib` pour une inspection RAW read-only : il n'accède ni au backend physique ni au SQL et sépare la pagination random-access de l'interface de la pagination cursor/keyset réservée aux consumers machine.
|
||||
|
||||
## Workers et jobs
|
||||
|
||||
@@ -171,7 +171,7 @@ ksp-execution-policy-api
|
||||
|
||||
## Groupes Program prioritaires
|
||||
|
||||
Après RAW/CORE :
|
||||
Après RAW/STRUCTURAL :
|
||||
|
||||
```text
|
||||
Solana Core Programs
|
||||
@@ -198,4 +198,4 @@ Un satellite nécessaire à un protocole reste dans son groupe : Pump fee avec P
|
||||
- split éventuel d'une API Interface séparée uniquement si un vrai besoin apparaît ;
|
||||
- contrats Rust exacts de Program/Materializer/Store ;
|
||||
- mécanisme IPC du premier manager de worker autonome ;
|
||||
- granularité future des workers DECODE/SPECIALIZED par groupe.
|
||||
- granularité future des workers DECODED/DOMAIN par groupe.
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- file: docs/architecture/003-COMPONENT_CONTRACTS.md -->
|
||||
<!-- version: 15 -->
|
||||
<!-- version: 16 -->
|
||||
|
||||
# Contrats initiaux des composants KSP
|
||||
|
||||
@@ -137,24 +137,24 @@ La chaîne durable est :
|
||||
|
||||
```text
|
||||
D1 RAW
|
||||
-> D2 CORE
|
||||
-> D3 DECODE
|
||||
-> D4 SPECIALIZED
|
||||
-> D2 STRUCTURAL
|
||||
-> D3 DECODED
|
||||
-> D4 DOMAIN
|
||||
```
|
||||
|
||||
### RAW
|
||||
|
||||
Acquisition replayable + provenance, sans décodage Program.
|
||||
|
||||
### CORE
|
||||
### STRUCTURAL
|
||||
|
||||
Normalisation générique Solana, sans décodage Program.
|
||||
|
||||
### DECODE
|
||||
### DECODED
|
||||
|
||||
Interprétation Program/protocole puis matérialisation générique/journal durable.
|
||||
|
||||
### SPECIALIZED
|
||||
### DOMAIN
|
||||
|
||||
Projections queryables de domaine : token, metadata, pools, trades, OHLC, routes, etc.
|
||||
|
||||
@@ -166,7 +166,7 @@ La première Store release est RAW-only ; les couches suivantes sont ajoutées q
|
||||
|
||||
## Materializer
|
||||
|
||||
`ksp-materializer-api`/`ksp-materializer-lib` sont introduits avec le premier besoin DECODE réel, pas avant.
|
||||
`ksp-materializer-api`/`ksp-materializer-lib` sont introduits avec le premier besoin DECODED réel, pas avant.
|
||||
|
||||
Program et Materializer restent indépendants du backend Store ; les composants de composition convertissent leurs outputs vers les DTO persistants.
|
||||
|
||||
@@ -174,9 +174,9 @@ Program et Materializer restent indépendants du backend Store ; les composants
|
||||
|
||||
`ksp-worker-api` est la lifecycle API des services continus.
|
||||
|
||||
RAW et CORE peuvent recevoir leurs workers à la fin de leur couche respective.
|
||||
RAW et STRUCTURAL peuvent recevoir leurs workers à la fin de leur couche respective.
|
||||
|
||||
Les workers DECODE/SPECIALIZED sont introduits avec les groupes Program réels, afin de ne pas créer une orchestration générique vide avant les processors.
|
||||
Les workers DECODED/DOMAIN sont introduits avec les groupes Program réels, afin de ne pas créer une orchestration générique vide avant les processors.
|
||||
|
||||
## Jobs
|
||||
|
||||
@@ -184,7 +184,7 @@ Les workers DECODE/SPECIALIZED sont introduits avec les groupes Program réels,
|
||||
|
||||
Le premier job concret est `ksp-job-backfill-lib`. Il couvre un backfill historique `RawTransaction` : quatre scopes bornés, découverte/hydratation Transport observée, conversion RAW v1, persistance atomique par `ksp-store-lib`, concurrence bornée, frontier/checkpoint contigus caller-owned, annulation coopérative et snapshots complets sûrs. Il ne dépend ni de Config, ni d'un backend Store concret, ni d'un Worker.
|
||||
|
||||
Les jobs de replay suivants pourront suivre les frontières durables ouvertes : RAW -> CORE, CORE -> DECODE, DECODE -> SPECIALIZED. Ils ne sont pas forcés d'adopter le contrat métier du backfill RAW ; seuls les contrats vraiment communs appartiennent à `ksp-job-api`.
|
||||
Les jobs de replay suivants pourront suivre les frontières durables ouvertes : RAW -> STRUCTURAL, STRUCTURAL -> DECODED, DECODED -> DOMAIN. Ils ne sont pas forcés d'adopter le contrat métier du backfill RAW ; seuls les contrats vraiment communs appartiennent à `ksp-job-api`.
|
||||
|
||||
Aucune `ksp-job-control-lib` n'est créée sans duplication concrète.
|
||||
|
||||
@@ -206,7 +206,7 @@ ksp-app-wallet-desk
|
||||
ksp-app-solprices-desk
|
||||
ksp-app-backfill-desk
|
||||
ksp-app-store-desk
|
||||
CORE tooling
|
||||
STRUCTURAL tooling
|
||||
ksp-app-market-desk
|
||||
```
|
||||
|
||||
@@ -218,7 +218,7 @@ Une application globale reste future.
|
||||
|
||||
## Progression verticale Program
|
||||
|
||||
À partir de DECODE :
|
||||
À partir de DECODED :
|
||||
|
||||
```text
|
||||
wire -> decode -> materialize -> specialized -> prepare -> policy -> execute -> scenario
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- file: docs/architecture/004-COMPONENT_INVENTORY.md -->
|
||||
<!-- version: 36 -->
|
||||
<!-- version: 37 -->
|
||||
|
||||
# Inventaire initial des composants KSP
|
||||
|
||||
@@ -48,10 +48,10 @@ Ce document maintient l'inventaire synthétique des composants retenus ou presse
|
||||
| Worker lifecycle | `ksp-worker-api` | API | Retenu | `0.3.9` | lifecycle/health/progression génériques des services continus |
|
||||
| RAW transaction worker | `ksp-worker-raw-transaction-ingest-lib` | worker/lib | Retenu | `0.3.11`–`0.3.14` | ingestion continue `RawTransaction` multi-source, déduplication/provenance/recovery |
|
||||
| RAW ingest Desk | `ksp-app-raw-transaction-ingest-desk` | app | Retenu | `0.3.15` | choix/supervision d’une ou plusieurs sources/méthodes sans réimplémenter le worker |
|
||||
| STRUCTURAL job | nom à fixer | job/lib | Retenu | couche CORE | normalisation Solana générique RAW -> CORE bornée/rejouable |
|
||||
| STRUCTURAL worker | nom à fixer | worker/lib | Retenu | fin couche CORE | backlog RAW -> CORE continu |
|
||||
| Materializer API | `ksp-materializer-api` | API | Retenu | premier groupe DECODE | contrats extensibles matérialisation |
|
||||
| Materializer impl. | `ksp-materializer-lib` | lib | Retenu | premier groupe DECODE | implementations officielles communes |
|
||||
| STRUCTURAL job | nom à fixer | job/lib | Retenu | couche STRUCTURAL | normalisation Solana générique RAW -> STRUCTURAL bornée/rejouable |
|
||||
| STRUCTURAL worker | nom à fixer | worker/lib | Retenu | fin couche STRUCTURAL | backlog RAW -> STRUCTURAL continu |
|
||||
| Materializer API | `ksp-materializer-api` | API | Retenu | premier groupe DECODED | contrats extensibles matérialisation |
|
||||
| Materializer impl. | `ksp-materializer-lib` | lib | Retenu | premier groupe DECODED | implementations officielles communes |
|
||||
| Execution policy | `ksp-execution-policy-api` | API | Retenu | premier vrai besoin execution | décision/safety multi-contexte |
|
||||
| Execution orchestration | `ksp-execution-lib` | lib | Retenu | premier vrai cycle execution | Program + policy + Wallet + transport |
|
||||
| Scenarios | `ksp-scenario-<domain>-lib` | lib | Retenu | vertical slices | validation métier/devnet par groupe |
|
||||
@@ -107,19 +107,19 @@ Import/export reste extensible ; les formats supplémentaires sont suivis dans `
|
||||
## Data plane
|
||||
|
||||
```text
|
||||
RAW -> CORE -> DECODE -> SPECIALIZED
|
||||
RAW -> STRUCTURAL -> DECODED -> DOMAIN
|
||||
```
|
||||
|
||||
- RAW : acquisition replayable ;
|
||||
- CORE : normalisation blockchain générique sans decoder Program ;
|
||||
- DECODE : interpretation Program + matérialisation générique/journal ;
|
||||
- SPECIALIZED : projections queryables de domaine.
|
||||
- STRUCTURAL : normalisation blockchain générique sans decoder Program ;
|
||||
- DECODED : interpretation Program + matérialisation générique/journal ;
|
||||
- DOMAIN : projections queryables de domaine.
|
||||
|
||||
## Progression structurelle
|
||||
|
||||
RAW et CORE sont complétés couche par couche avec jobs/workers/apps utiles.
|
||||
RAW et STRUCTURAL sont complétés couche par couche avec jobs/workers/apps utiles.
|
||||
|
||||
À partir de DECODE, progression verticale par groupe :
|
||||
À partir de DECODED, progression verticale par groupe :
|
||||
|
||||
```text
|
||||
wire -> decode -> materialize -> specialized -> prepare -> policy -> execute -> scenario
|
||||
@@ -154,6 +154,6 @@ Market Desk est progressive : V1 après les DEX prioritaires, puis enrichissemen
|
||||
## Questions restantes
|
||||
|
||||
- nécessité future d'un pool automatique WS ;
|
||||
- types exacts `ksp-materializer-api` lors de l'ouverture DECODE ;
|
||||
- types exacts `ksp-materializer-api` lors de l'ouverture DECODED ;
|
||||
- nom/packaging précis des futurs STRUCTURAL job et STRUCTURAL worker ;
|
||||
- granularité des workers DECODE/SPECIALIZED par groupe.
|
||||
- granularité des workers DECODED/DOMAIN par groupe.
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- file: docs/architecture/005-DEPENDENCY_GRAPH.md -->
|
||||
<!-- version: 25 -->
|
||||
<!-- version: 26 -->
|
||||
|
||||
# Graphe de dépendances KSP
|
||||
|
||||
@@ -244,9 +244,9 @@ Une petite policy spécifique peut vivre dans une crate scenario/orchestrateur.
|
||||
|
||||
```text
|
||||
D1 RAW
|
||||
-> D2 CORE
|
||||
-> D3 DECODE
|
||||
-> D4 SPECIALIZED
|
||||
-> D2 STRUCTURAL
|
||||
-> D3 DECODED
|
||||
-> D4 DOMAIN
|
||||
```
|
||||
|
||||
### RAW
|
||||
@@ -292,7 +292,7 @@ ksp-store-lib
|
||||
|
||||
Le Job Backfill et le Worker RAW peuvent donc partager exactement la canonicalisation et le wire sans que la common crate possède le runtime, le Transport ou le backend.
|
||||
|
||||
### CORE
|
||||
### STRUCTURAL
|
||||
|
||||
```text
|
||||
D1 RAW
|
||||
@@ -301,23 +301,23 @@ D1 RAW
|
||||
Solana generic normalizer
|
||||
|
|
||||
v
|
||||
D2 CORE
|
||||
D2 STRUCTURAL
|
||||
```
|
||||
|
||||
Le normalizer CORE peut utiliser `ksp-interface-lib` pour des wires Solana génériques.
|
||||
Le normalizer STRUCTURAL peut utiliser `ksp-interface-lib` pour des wires Solana génériques.
|
||||
|
||||
Interdictions :
|
||||
|
||||
```text
|
||||
RAW -> CORE -X-> ksp-program-api
|
||||
RAW -> CORE -X-> ksp-program-lib
|
||||
RAW -> CORE -X-> ksp-materializer-api
|
||||
RAW -> STRUCTURAL -X-> ksp-program-api
|
||||
RAW -> STRUCTURAL -X-> ksp-program-lib
|
||||
RAW -> STRUCTURAL -X-> ksp-materializer-api
|
||||
```
|
||||
|
||||
### DECODE
|
||||
### DECODED
|
||||
|
||||
```text
|
||||
D2 CORE
|
||||
D2 STRUCTURAL
|
||||
|
|
||||
v
|
||||
ksp-program-api implementation
|
||||
@@ -329,19 +329,19 @@ decoded facts
|
||||
ksp-materializer-api implementation
|
||||
|
|
||||
v
|
||||
D3 DECODE / generic journal
|
||||
D3 DECODED / generic journal
|
||||
```
|
||||
|
||||
### SPECIALIZED
|
||||
### DOMAIN
|
||||
|
||||
```text
|
||||
D3 DECODE
|
||||
D3 DECODED
|
||||
|
|
||||
v
|
||||
specialized projector/materializer
|
||||
|
|
||||
v
|
||||
D4 SPECIALIZED
|
||||
D4 DOMAIN
|
||||
```
|
||||
|
||||
## Materialization
|
||||
@@ -386,7 +386,7 @@ ksp-store-postgres-lib -X-> ksp-store-lib
|
||||
worker/job -X-> ksp-store-postgres-lib
|
||||
```
|
||||
|
||||
La première release Store (`0.3.1`) est RAW-only ; les contrats CORE/DECODE/SPECIALIZED sont ajoutés avec leurs couches. Les consumers runtime ordinaires (jobs, workers, apps) utilisent `ksp-store-lib`; ils ne sélectionnent ni n'importent directement `ksp-store-postgres-lib` ou un autre backend.
|
||||
La première release Store (`0.3.1`) est RAW-only ; les contrats STRUCTURAL/DECODED/DOMAIN sont ajoutés avec leurs couches. Les consumers runtime ordinaires (jobs, workers, apps) utilisent `ksp-store-lib`; ils ne sélectionnent ni n'importent directement `ksp-store-postgres-lib` ou un autre backend.
|
||||
|
||||
## Jobs
|
||||
|
||||
@@ -436,7 +436,7 @@ ksp-worker-control-lib
|
||||
|
||||
Le worker RAW Transaction n'est pas défini comme « un worker WebSocket » ou « un worker gRPC ». Il reçoit une ou plusieurs stratégies d'acquisition construites au-dessus des façades KSP réellement disponibles ; celles-ci peuvent être alternatives, complémentaires (discovery + hydration), redondantes entre providers ou spécialisées live/catch-up/gap-repair. La transaction canonique reste identifiée indépendamment de la source et chaque acquisition utile conserve sa propre observation/provenance Store.
|
||||
|
||||
RAW worker puis STRUCTURAL worker sont introduits à la fin de leur couche respective, lorsque persistence/backlog sont disponibles. Le traitement RAW -> CORE borné est porté par un STRUCTURAL job distinct du service continu. Les workers DECODE/SPECIALIZED sont introduits avec les groupes Program concernés plutôt que tous anticipés en bloc.
|
||||
RAW worker puis STRUCTURAL worker sont introduits à la fin de leur couche respective, lorsque persistence/backlog sont disponibles. Le traitement RAW -> STRUCTURAL borné est porté par un STRUCTURAL job distinct du service continu. Les workers DECODED/DOMAIN sont introduits avec les groupes Program concernés plutôt que tous anticipés en bloc.
|
||||
|
||||
## Apps
|
||||
|
||||
@@ -515,7 +515,7 @@ ksp-app-market-desk
|
||||
-> KSP domain/query contracts
|
||||
```
|
||||
|
||||
Elle consomme les projections SPECIALIZED normalisées ; elle ne dépend pas directement des bibliothèques protocole externes.
|
||||
Elle consomme les projections DOMAIN normalisées ; elle ne dépend pas directement des bibliothèques protocole externes.
|
||||
|
||||
## Scenarios
|
||||
|
||||
@@ -536,7 +536,7 @@ L'app demo correspondante reste un adapter UI mince.
|
||||
|
||||
## Progression verticale Program
|
||||
|
||||
À partir de DECODE :
|
||||
À partir de DECODED :
|
||||
|
||||
```text
|
||||
wire
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- file: docs/architecture/006-WIRE_AND_PROGRAM.md -->
|
||||
<!-- version: 3 -->
|
||||
<!-- version: 4 -->
|
||||
|
||||
# Wire, Program API et implémentations Program
|
||||
|
||||
@@ -442,7 +442,7 @@ Une crate externe provoquant volontairement une génération incompatible de dé
|
||||
|
||||
## Progression verticale par groupe
|
||||
|
||||
Après les couches RAW/CORE, les Program implementations ne sont pas développées horizontalement comme une longue liste de decoders isolés. Chaque groupe prioritaire avance successivement :
|
||||
Après les couches RAW/STRUCTURAL, les Program implementations ne sont pas développées horizontalement comme une longue liste de decoders isolés. Chaque groupe prioritaire avance successivement :
|
||||
|
||||
```text
|
||||
wire -> decode -> materialize -> specialized -> execution preparation -> policy -> execution -> scenario
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- file: docs/architecture/008-DATA_MATERIALIZATION_AND_STORE.md -->
|
||||
<!-- version: 6 -->
|
||||
<!-- version: 7 -->
|
||||
|
||||
# Data, Materialization et Store
|
||||
|
||||
@@ -10,19 +10,21 @@ Ce document définit la chaîne durable KSP, la responsabilité du Store et les
|
||||
La nomenclature canonique est désormais :
|
||||
|
||||
```text
|
||||
RAW -> CORE -> DECODE -> SPECIALIZED
|
||||
RAW -> STRUCTURAL -> DECODED -> DOMAIN
|
||||
```
|
||||
|
||||
Les aliases D1–D4 restent utilisés pour les niveaux persistés :
|
||||
|
||||
```text
|
||||
D1 = RAW
|
||||
D2 = CORE
|
||||
D3 = DECODE / matérialisation générique décodée
|
||||
D4 = SPECIALIZED
|
||||
D2 = STRUCTURAL
|
||||
D3 = DECODED / matérialisation générique décodée
|
||||
D4 = DOMAIN
|
||||
```
|
||||
|
||||
Cette clarification remplace l'ancienne interprétation où D1 -> D2 pouvait déjà dépendre de `ksp-program-api`. **RAW et CORE sont indépendants de tout decoder Program.**
|
||||
Le nom de couche historique `CORE` est abandonné pour D2 parce qu'il confondait la fondation commune `ksp-core-lib` avec une opération de décomposition structurelle du Store. `Core` reste inchangé lorsqu'il désigne la crate fondamentale ou un nom propre comme « Solana Core Programs ».
|
||||
|
||||
Cette clarification remplace l'ancienne interprétation où D1 -> D2 pouvait déjà dépendre de `ksp-program-api`. **RAW et STRUCTURAL sont indépendants de tout decoder Program.**
|
||||
|
||||
## Principes structurants
|
||||
|
||||
@@ -36,7 +38,7 @@ Cette clarification remplace l'ancienne interprétation où D1 -> D2 pouvait dé
|
||||
|
||||
### Mission
|
||||
|
||||
RAW conserve l'acquisition suffisamment fidèlement pour reconstruire CORE sans redemander la donnée au provider lorsqu'elle a déjà été capturée.
|
||||
RAW conserve l'acquisition suffisamment fidèlement pour reconstruire STRUCTURAL sans redemander la donnée au provider lorsqu'elle a déjà été capturée.
|
||||
|
||||
Le transport peut normaliser plusieurs providers vers un modèle KSP homogène, mais D1 doit rester lossless pour les besoins de replay couverts.
|
||||
|
||||
@@ -77,15 +79,15 @@ Selon la catégorie, D1 doit pouvoir conserver notamment :
|
||||
- identité/hash d'idempotence ;
|
||||
- cursor/page/range/checkpoint lorsque pertinent.
|
||||
|
||||
## D2 — CORE
|
||||
## D2 — STRUCTURAL
|
||||
|
||||
### Mission
|
||||
|
||||
CORE est une **normalisation canonique générique de la blockchain Solana**.
|
||||
STRUCTURAL est une **normalisation canonique générique de la blockchain Solana**.
|
||||
|
||||
Cette couche doit fonctionner même si `ksp-program-api` et `ksp-program-lib` ne sont pas encore capables de décoder le moindre programme métier.
|
||||
|
||||
Exemples de faits CORE candidats :
|
||||
Exemples de faits STRUCTURAL candidats :
|
||||
|
||||
- slots ;
|
||||
- blocks et block metadata ;
|
||||
@@ -102,9 +104,9 @@ Exemples de faits CORE candidats :
|
||||
- return data brute ;
|
||||
- relations structurelles transaction/message/instruction/account.
|
||||
|
||||
Un fait CORE peut contenir un `program_id`, des bytes et des indexes sans savoir que l'instruction représente un `Transfer`, un `Swap` ou une mutation Metadata.
|
||||
Un fait STRUCTURAL peut contenir un `program_id`, des bytes et des indexes sans savoir que l'instruction représente un `Transfer`, un `Swap` ou une mutation Metadata.
|
||||
|
||||
### Frontière RAW -> CORE
|
||||
### Frontière RAW -> STRUCTURAL
|
||||
|
||||
```text
|
||||
D1 RAW
|
||||
@@ -113,39 +115,39 @@ D1 RAW
|
||||
normalisation Solana générique
|
||||
|
|
||||
v
|
||||
D2 CORE
|
||||
D2 STRUCTURAL
|
||||
```
|
||||
|
||||
Interdictions :
|
||||
|
||||
```text
|
||||
RAW -> CORE -X-> ksp-program-api
|
||||
RAW -> CORE -X-> ksp-program-lib
|
||||
RAW -> CORE -X-> ksp-materializer-api
|
||||
RAW -> STRUCTURAL -X-> ksp-program-api
|
||||
RAW -> STRUCTURAL -X-> ksp-program-lib
|
||||
RAW -> STRUCTURAL -X-> ksp-materializer-api
|
||||
```
|
||||
|
||||
Les codecs/wires génériques nécessaires à la structure Solana peuvent provenir de `ksp-interface-lib` lorsqu'ils appartiennent à la façade wire officielle, sans transformer cette étape en décodage Program.
|
||||
|
||||
### Provenance CORE
|
||||
### Provenance STRUCTURAL
|
||||
|
||||
D2 doit pouvoir relier chaque résultat à :
|
||||
|
||||
- son input D1 ;
|
||||
- l'identité/version du normalizer CORE ;
|
||||
- l'identité/version du normalizer STRUCTURAL ;
|
||||
- un hash logique d'input ;
|
||||
- l'instant de processing/persistence ;
|
||||
- son état de processing durable lorsque nécessaire.
|
||||
|
||||
## D3 — DECODE / matérialisation générique
|
||||
## D3 — DECODED / matérialisation générique
|
||||
|
||||
### Mission
|
||||
|
||||
DECODE commence lorsque KSP interprète un `program_id`, un layout d'instruction, un compte ou un événement selon un contrat Program/protocole.
|
||||
DECODED commence lorsque KSP interprète un `program_id`, un layout d'instruction, un compte ou un événement selon un contrat Program/protocole.
|
||||
|
||||
La progression logique d'un groupe est :
|
||||
|
||||
```text
|
||||
CORE
|
||||
STRUCTURAL
|
||||
|
|
||||
v
|
||||
decoder Program
|
||||
@@ -157,7 +159,7 @@ decoded facts
|
||||
materialisation générique / journal durable
|
||||
|
|
||||
v
|
||||
D3 DECODE
|
||||
D3 DECODED
|
||||
```
|
||||
|
||||
D3 conserve l'équivalent conceptuel obligatoire du journal générique de matérialisation de bot3 (`k_sol_mat_outputs`), sans imposer son ancien schéma ou son nom physique.
|
||||
@@ -165,7 +167,7 @@ D3 conserve l'équivalent conceptuel obligatoire du journal générique de maté
|
||||
Le journal doit pouvoir répondre au minimum :
|
||||
|
||||
```text
|
||||
quel input CORE ?
|
||||
quel input STRUCTURAL ?
|
||||
quel program/decoder ?
|
||||
quelle version ?
|
||||
quel materializer ?
|
||||
@@ -179,10 +181,10 @@ quel état/superseded/failed/replay ?
|
||||
|
||||
Les types exacts de decoded facts et du journal sont décidés lorsque les premiers vertical slices Program existent.
|
||||
|
||||
### Frontière CORE -> DECODE
|
||||
### Frontière STRUCTURAL -> DECODED
|
||||
|
||||
```text
|
||||
D2 CORE
|
||||
D2 STRUCTURAL
|
||||
|
|
||||
v
|
||||
ksp-program-api implementation
|
||||
@@ -201,11 +203,11 @@ Les implémentations officielles pourront provenir de `ksp-program-lib` et `ksp-
|
||||
|
||||
Program et Materializer ne dépendent pas du backend Store.
|
||||
|
||||
## D4 — SPECIALIZED
|
||||
## D4 — DOMAIN
|
||||
|
||||
### Mission
|
||||
|
||||
SPECIALIZED expose des projections queryables utiles aux applications, analyses et futurs modèles ML.
|
||||
DOMAIN expose des projections queryables utiles aux applications, analyses et futurs modèles ML.
|
||||
|
||||
Exemples :
|
||||
|
||||
@@ -258,15 +260,15 @@ La direction reste :
|
||||
|
||||
### OHLC
|
||||
|
||||
Les candles sont des projections SPECIALIZED calculées à partir des trades/price observations persistés.
|
||||
Les candles sont des projections DOMAIN calculées à partir des trades/price observations persistés.
|
||||
|
||||
Une application marché lit les OHLC matérialisés ; elle ne reparcourt pas toutes les transactions pour reconstruire les candles à chaque affichage.
|
||||
|
||||
## Vertical slices Program
|
||||
|
||||
RAW et CORE sont développés horizontalement.
|
||||
RAW et STRUCTURAL sont développés horizontalement.
|
||||
|
||||
À partir de DECODE, la progression est verticale par groupe :
|
||||
À partir de DECODED, la progression est verticale par groupe :
|
||||
|
||||
```text
|
||||
wire
|
||||
@@ -289,7 +291,7 @@ Les composants satellites nécessaires à un protocole appartiennent à son grou
|
||||
|
||||
La première implementation `0.3.1` est volontairement **RAW-only** : elle ne crée pas prématurément les contrats physiques D2/D3/D4.
|
||||
|
||||
Les surfaces CORE/DECODE/SPECIALIZED sont ajoutées quand leurs couches sont réellement ouvertes.
|
||||
Les surfaces STRUCTURAL/DECODED/DOMAIN sont ajoutées quand leurs couches sont réellement ouvertes.
|
||||
|
||||
## `ksp-store-lib` et backends physiques
|
||||
|
||||
@@ -342,7 +344,7 @@ La voie `RawInspectionPageRequest` est backend-neutral mais conçue pour une ins
|
||||
|
||||
## `ksp-materializer-api` et `ksp-materializer-lib`
|
||||
|
||||
Ils sont introduits seulement lorsque le premier groupe DECODE démontre le contrat réel.
|
||||
Ils sont introduits seulement lorsque le premier groupe DECODED démontre le contrat réel.
|
||||
|
||||
`ksp-materializer-api` porte les contrats extensibles ; `ksp-materializer-lib` contient les implementations officielles communes.
|
||||
|
||||
@@ -353,9 +355,9 @@ Une projection très locale/spécifique peut rester dans son groupe si la créat
|
||||
Les frontières durables restent replayables indépendamment :
|
||||
|
||||
```text
|
||||
RAW -> CORE
|
||||
CORE -> DECODE
|
||||
DECODE -> SPECIALIZED
|
||||
RAW -> STRUCTURAL
|
||||
STRUCTURAL -> DECODED
|
||||
DECODED -> DOMAIN
|
||||
```
|
||||
|
||||
Un replay d'une couche dérivée ne doit pas refaire arbitrairement les couches précédentes.
|
||||
@@ -393,16 +395,16 @@ Ils ne dupliquent pas le contrat durable.
|
||||
La stabilité cible est différente selon la couche :
|
||||
|
||||
- RAW : fortement stable après mise en production ;
|
||||
- CORE : fortement stable après validation de la normalisation Solana générique ;
|
||||
- DECODE : extensible par nouveaux Program/versions ;
|
||||
- SPECIALIZED : plus évolutif selon les besoins de query, trading et analytics.
|
||||
- STRUCTURAL : fortement stable après validation de la normalisation Solana générique ;
|
||||
- DECODED : extensible par nouveaux Program/versions ;
|
||||
- DOMAIN : plus évolutif selon les besoins de query, trading et analytics.
|
||||
|
||||
## Questions laissées ouvertes
|
||||
|
||||
- schémas SQL exacts RAW puis CORE ;
|
||||
- schémas SQL exacts RAW puis STRUCTURAL ;
|
||||
- représentation persistable exacte d'un decoded output ;
|
||||
- contrat exact du journal D3 ;
|
||||
- granularité des projectors SPECIALIZED ;
|
||||
- granularité des projectors DOMAIN ;
|
||||
- politique de supersession/versioning des outputs ;
|
||||
- fenêtres OHLC initiales ;
|
||||
- mécanisme de contexte pour les projections stateful.
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- file: docs/architecture/009-ACQUISITION_WORKERS_AND_JOBS.md -->
|
||||
<!-- version: 16 -->
|
||||
<!-- version: 17 -->
|
||||
|
||||
# Acquisition, workers, jobs et pipelines spécialisés
|
||||
|
||||
@@ -8,7 +8,7 @@
|
||||
Ce document définit le lifecycle opérationnel autour des couches :
|
||||
|
||||
```text
|
||||
RAW -> CORE -> DECODE -> SPECIALIZED
|
||||
RAW -> STRUCTURAL -> DECODED -> DOMAIN
|
||||
```
|
||||
|
||||
Il conserve la séparation stricte entre :
|
||||
@@ -20,7 +20,7 @@ Il conserve la séparation stricte entre :
|
||||
|
||||
## Règle de progression
|
||||
|
||||
RAW et CORE sont les deux premières couches horizontales. Elles ne nécessitent aucun decoder Program.
|
||||
RAW et STRUCTURAL sont les deux premières couches horizontales. Elles ne nécessitent aucun decoder Program.
|
||||
|
||||
Pour chacune, KSP peut terminer successivement :
|
||||
|
||||
@@ -31,7 +31,7 @@ persistence
|
||||
-> application de contrôle/inspection si utile
|
||||
```
|
||||
|
||||
À partir de DECODE, les processors/jobs/workers/scenarios sont introduits **avec le groupe Program concerné**, en vertical slice, au lieu de créer à l'avance une grande flotte générique de workers de décodage/materialisation sans programme réel.
|
||||
À partir de DECODED, les processors/jobs/workers/scenarios sont introduits **avec le groupe Program concerné**, en vertical slice, au lieu de créer à l'avance une grande flotte générique de workers de décodage/materialisation sans programme réel.
|
||||
|
||||
## RAW
|
||||
|
||||
@@ -86,7 +86,7 @@ Le job :
|
||||
- limite les hydrations concurrentes, avance seulement une frontier contiguë durable et retourne un checkpoint opaque caller-owned ;
|
||||
- arrête coopérativement les nouvelles admissions lors d'une annulation et draine une persistence Store déjà soumise ;
|
||||
- publie des snapshots latest-value sûrs sans payload RAW ni secrets/URLs Transport ;
|
||||
- n'effectue aucun décodage Program et n'écrit aucun fait CORE/DECODE/SPECIALIZED.
|
||||
- n'effectue aucun décodage Program et n'écrit aucun fait STRUCTURAL/DECODED/DOMAIN.
|
||||
|
||||
Le caller desktop spécialisé actuel est `ksp-app-backfill-desk`. Il compose Config, le pool HTTP et Store, puis remet ces ressources au runtime Backfill. Il peut retenir le checkpoint terminal uniquement en mémoire Rust pour un Resume in-session ; cette rétention applicative ne transforme pas le checkpoint en garantie de reprise durable après redémarrage.
|
||||
|
||||
@@ -204,7 +204,7 @@ L'archive kbot3 doit être relue uniquement comme **référence fonctionnelle**
|
||||
|
||||
L'audit `0.3.9` a conclu que `mainnet` est l'identité logique canonique KSP du réseau de production Solana. `mainnet-beta` reste un alias legacy/externe ou un libellé provider lorsqu'une API externe l'emploie réellement ; il ne constitue plus l'identité persistée cible de Store/RAW/Config.
|
||||
|
||||
Depuis `0.3.9-pre.006-fix.003`, les profils Mainnet engagés dans Config/Store/Transport utilisent `mainnet`, de même que les tests et exemples runtime associés. KSP ne crée donc pas deux identités persistées pour le même cluster. Les anciennes données N1 RAW portant `mainnet-beta` sont considérées comme expérimentales et peuvent être droppées/recréées ; aucune migration destructive n'est imposée avant finalisation des Jobs/Workers RAW.
|
||||
Depuis `0.3.9-pre.006-fix.003`, les profils Mainnet engagés dans Config/Store/Transport utilisent `mainnet`, de même que les tests et exemples runtime associés. KSP ne crée donc pas deux identités persistées pour le même cluster. Les anciennes données D1 RAW portant `mainnet-beta` sont considérées comme expérimentales et peuvent être droppées/recréées ; aucune migration destructive n'est imposée avant finalisation des Jobs/Workers RAW.
|
||||
|
||||
Les frontières externes restent libres de documenter ou d'accepter un nom provider legacy lorsque nécessaire, sans recopier ce nom dans `RawNetworkId` canonique.
|
||||
|
||||
@@ -237,11 +237,11 @@ une stratégie live + gap repair
|
||||
|
||||
Le détail des RAW persistés reste la responsabilité de Store Desk.
|
||||
|
||||
## CORE
|
||||
## STRUCTURAL
|
||||
|
||||
### Pipeline RAW -> CORE
|
||||
### Pipeline RAW -> STRUCTURAL
|
||||
|
||||
La normalisation CORE est générique Solana :
|
||||
La normalisation STRUCTURAL est générique Solana :
|
||||
|
||||
```text
|
||||
D1 RAW
|
||||
@@ -250,15 +250,15 @@ D1 RAW
|
||||
Solana generic normalizer
|
||||
|
|
||||
v
|
||||
D2 CORE
|
||||
D2 STRUCTURAL
|
||||
```
|
||||
|
||||
Dépendances interdites :
|
||||
|
||||
```text
|
||||
CORE normalizer -X-> ksp-program-api
|
||||
CORE normalizer -X-> ksp-program-lib
|
||||
CORE normalizer -X-> ksp-materializer-api
|
||||
STRUCTURAL normalizer -X-> ksp-program-api
|
||||
STRUCTURAL normalizer -X-> ksp-program-lib
|
||||
STRUCTURAL normalizer -X-> ksp-materializer-api
|
||||
```
|
||||
|
||||
`ksp-interface-lib` peut fournir les wires Solana génériques nécessaires à la structure blockchain.
|
||||
@@ -271,21 +271,21 @@ Un job borné peut rejouer :
|
||||
RAW persisted range
|
||||
|
|
||||
v
|
||||
CORE normalizer
|
||||
STRUCTURAL normalizer
|
||||
|
|
||||
v
|
||||
D2 CORE
|
||||
D2 STRUCTURAL
|
||||
```
|
||||
|
||||
sans redemander les données au réseau.
|
||||
|
||||
### STRUCTURAL worker
|
||||
|
||||
Le STRUCTURAL worker continu peut consommer le backlog RAW nouvellement persisté et produire CORE.
|
||||
Le STRUCTURAL worker continu peut consommer le backlog RAW nouvellement persisté et produire STRUCTURAL.
|
||||
|
||||
Le Store reste source de vérité du backlog ; les notifications ne sont qu'un wake-up.
|
||||
|
||||
## DECODE et SPECIALIZED
|
||||
## DECODED et DOMAIN
|
||||
|
||||
### Introduction par groupe fonctionnel
|
||||
|
||||
@@ -294,7 +294,7 @@ KSP ne crée pas d'abord un unique « worker decoder de tout Solana » puis tous
|
||||
Chaque groupe prioritaire introduit les capacités nécessaires :
|
||||
|
||||
```text
|
||||
CORE inputs du groupe
|
||||
STRUCTURAL inputs du groupe
|
||||
|
|
||||
v
|
||||
Program decoder
|
||||
@@ -303,10 +303,10 @@ Program decoder
|
||||
decoded facts
|
||||
|
|
||||
v
|
||||
generic materialization / DECODE persistence
|
||||
generic materialization / DECODED persistence
|
||||
|
|
||||
v
|
||||
SPECIALIZED projection si utile
|
||||
DOMAIN projection si utile
|
||||
```
|
||||
|
||||
Puis le même groupe avance vers préparation d'exécution, policy, execution et scénarios Devnet.
|
||||
@@ -511,7 +511,7 @@ STRUCTURAL job / STRUCTURAL worker
|
||||
|
||||
Pas de Program API.
|
||||
|
||||
### Groupes DECODE/SPECIALIZED
|
||||
### Groupes DECODED/DOMAIN
|
||||
|
||||
Le composant de composition du groupe peut utiliser :
|
||||
|
||||
@@ -530,5 +530,5 @@ selon les capacités réellement introduites.
|
||||
- politique d'alias externe `mainnet-beta` à matérialiser uniquement aux frontières qui en ont réellement besoin, sans créer une seconde identité Store ;
|
||||
- modèle de claim/lease PostgreSQL pour les futurs processors continus ;
|
||||
- taille de batch et stratégie backpressure des workers de processing ;
|
||||
- découpage des workers DECODE/SPECIALIZED par groupe lorsque les premiers groupes existent ;
|
||||
- découpage des workers DECODED/DOMAIN par groupe lorsque les premiers groupes existent ;
|
||||
- mécanisme IPC des applications de contrôle futures.
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- file: docs/architecture/010-APPS_SERVICES_SCENARIOS_AND_CONTROL.md -->
|
||||
<!-- version: 13 -->
|
||||
<!-- version: 14 -->
|
||||
|
||||
# Applications, services, scenarios et control plane
|
||||
|
||||
@@ -49,7 +49,7 @@ Elle ne doit pas réimplémenter :
|
||||
|
||||
## Applications de validation par couche
|
||||
|
||||
KSP peut ajouter une petite application spécialisée à la fin d'une couche RAW ou CORE lorsque cela permet de valider et exploiter réellement la couche avant de passer à la suivante. Ces applications lisent les contrats KSP et ne recopient pas les processors dans Tauri.
|
||||
KSP peut ajouter une petite application spécialisée à la fin d'une couche RAW ou STRUCTURAL lorsque cela permet de valider et exploiter réellement la couche avant de passer à la suivante. Ces applications lisent les contrats KSP et ne recopient pas les processors dans Tauri.
|
||||
|
||||
À partir des vertical slices Program, les applications restent attachées aux besoins réels : demos de scenarios pour l'exécution et Market Desk pour les projections de marché.
|
||||
|
||||
@@ -198,12 +198,12 @@ Exemples conceptuels :
|
||||
ksp-worker-raw-transaction-ingest-lib # premier runtime worker réutilisable retenu
|
||||
future autonomous raw-ingest binary # seulement si un besoin de service séparé le justifie
|
||||
future STRUCTURAL worker
|
||||
future group-specific DECODE/SPECIALIZED workers when justified
|
||||
future group-specific DECODED/DOMAIN workers when justified
|
||||
```
|
||||
|
||||
Le premier worker RAW est volontairement prévu comme bibliothèque réutilisable afin qu'une Desk ou un futur host puisse le construire sans dupliquer sa logique. Un binaire autonome n'est pas créé par convention seule ; s'il apparaît, il reste un host mince au-dessus de la même bibliothèque et de `ksp-worker-api`.
|
||||
|
||||
RAW reçoit son worker d’ingestion à la fin de sa couche ; CORE reçoit ensuite son STRUCTURAL worker lorsque sa persistence/backlog sont disponibles. Les workers DECODE/SPECIALIZED ne sont plus tous anticipés comme une chaîne globale fixe : leur granularité doit émerger des premiers vertical slices Program.
|
||||
RAW reçoit son worker d’ingestion à la fin de sa couche ; STRUCTURAL reçoit ensuite son STRUCTURAL worker lorsque sa persistence/backlog sont disponibles. Les workers DECODED/DOMAIN ne sont plus tous anticipés comme une chaîne globale fixe : leur granularité doit émerger des premiers vertical slices Program.
|
||||
|
||||
Le binaire, lorsqu'il existe, doit rester mince.
|
||||
|
||||
@@ -247,16 +247,16 @@ transport / acquisition
|
||||
D1 RAW
|
||||
|
|
||||
v
|
||||
D2 CORE
|
||||
D2 STRUCTURAL
|
||||
|
|
||||
v
|
||||
D3 DECODE
|
||||
D3 DECODED
|
||||
|
|
||||
v
|
||||
D4 SPECIALIZED
|
||||
D4 DOMAIN
|
||||
```
|
||||
|
||||
Ce schéma décrit les **frontières de données**, pas quatre workers globaux imposés. RAW et CORE peuvent disposer de workers horizontaux propres à leur couche. À partir de DECODE, la granularité des workers/processors émerge des groupes fonctionnels verticaux réellement introduits ; plusieurs groupes peuvent donc posséder des lifecycle hosts distincts sans qu'un `W3` ou `W4` universel existe.
|
||||
Ce schéma décrit les **frontières de données**, pas quatre workers globaux imposés. RAW et STRUCTURAL peuvent disposer de workers horizontaux propres à leur couche. À partir de DECODED, la granularité des workers/processors émerge des groupes fonctionnels verticaux réellement introduits ; plusieurs groupes peuvent donc posséder des lifecycle hosts distincts sans qu'un `W3` ou `W4` universel existe.
|
||||
|
||||
Les notifications accélèrent le réveil mais ne créent pas une connexion fonctionnelle worker-to-worker.
|
||||
|
||||
@@ -286,7 +286,7 @@ Le data plane transporte/persiste les données Solana et les résultats de proce
|
||||
ksp-onchain-transport-lib
|
||||
|
|
||||
v
|
||||
RAW -> CORE -> DECODE -> SPECIALIZED
|
||||
RAW -> STRUCTURAL -> DECODED -> DOMAIN
|
||||
```
|
||||
|
||||
avec notifications de données persistées comme wake-up.
|
||||
@@ -516,11 +516,11 @@ Une app spécialisée peut éditer une configuration puis demander son applicati
|
||||
|
||||
Après les groupes Meteora/Raydium/Pump/Orca, KSP prévoit une première application spécialisée candidate `ksp-app-market-desk`.
|
||||
|
||||
V1 peut afficher tokens, pools/markets, liquidité, trades/swaps, prix, volumes, OHLC et activité live/récente à partir des projections SPECIALIZED et des contrats KSP. Elle ne dépend pas directement des SDK/protocoles DEX pour reconstruire leurs modèles dans l'UI.
|
||||
V1 peut afficher tokens, pools/markets, liquidité, trades/swaps, prix, volumes, OHLC et activité live/récente à partir des projections DOMAIN et des contrats KSP. Elle ne dépend pas directement des SDK/protocoles DEX pour reconstruire leurs modèles dans l'UI.
|
||||
|
||||
Après Jupiter/OKX, la même application est enrichie avec routes, legs, DEX impliqués, fees/slippage et comparaison quote/execution lorsqu'elle existe.
|
||||
|
||||
Les OHLC sont matérialisés dans SPECIALIZED et consommés par l'application; ils ne sont pas recalculés à partir de tout l'historique lors de chaque rendu.
|
||||
Les OHLC sont matérialisés dans DOMAIN et consommés par l'application; ils ne sont pas recalculés à partir de tout l'historique lors de chaque rendu.
|
||||
|
||||
## Future orchestrator
|
||||
|
||||
@@ -575,7 +575,7 @@ control/application adapters
|
||||
Data plane séparé :
|
||||
|
||||
```text
|
||||
transport -> RAW -> CORE -> DECODE -> SPECIALIZED
|
||||
transport -> RAW -> STRUCTURAL -> DECODED -> DOMAIN
|
||||
```
|
||||
|
||||
Aucun payload de processing n'a besoin de transiter via l'UI/control plane.
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- file: docs/architecture/011-RAW_TRANSACTION_ACQUISITION.md -->
|
||||
<!-- version: 10 -->
|
||||
<!-- version: 11 -->
|
||||
|
||||
# Acquisition et alimentation `RawTransaction`
|
||||
|
||||
@@ -610,7 +610,7 @@ priorités/composition
|
||||
|
||||
Les prix/tiers d'audit ne doivent pas devenir une politique runtime.
|
||||
|
||||
`mainnet` est l'identité réseau durable KSP. `mainnet-beta` reste uniquement un alias de compatibilité/historique ou un libellé externe lorsqu'un provider/API l'emploie. Depuis `0.3.9-pre.006-fix.003`, les profils Config/Store/Transport Mainnet engagés utilisent `mainnet` comme identité logique, et les exemples/tests associés ont été normalisés. Les endpoints publics Solana engagés suivent également la nomenclature Mainnet courante (`https://api.mainnet.solana.com` et `wss://api.mainnet.solana.com`). Aucune migration de données N1 n'est exigée : les données RAW Mainnet encore expérimentales peuvent être droppées/recréées si elles portent l'ancienne identité.
|
||||
`mainnet` est l'identité réseau durable KSP. `mainnet-beta` reste uniquement un alias de compatibilité/historique ou un libellé externe lorsqu'un provider/API l'emploie. Depuis `0.3.9-pre.006-fix.003`, les profils Config/Store/Transport Mainnet engagés utilisent `mainnet` comme identité logique, et les exemples/tests associés ont été normalisés. Les endpoints publics Solana engagés suivent également la nomenclature Mainnet courante (`https://api.mainnet.solana.com` et `wss://api.mainnet.solana.com`). Aucune migration de données D1 n'est exigée : les données RAW Mainnet encore expérimentales peuvent être droppées/recréées si elles portent l'ancienne identité.
|
||||
|
||||
## 13. Normalisation RAW commune sans couplage Job/Worker
|
||||
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- file: docs/plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md -->
|
||||
<!-- version: 96 -->
|
||||
<!-- version: 97 -->
|
||||
|
||||
# Séquence des releases fonctionnelles KSP
|
||||
|
||||
@@ -524,7 +524,7 @@ Metadata HTTP/IPFS/Arweave viendra au premier besoin Metadata réel. SOL/EUR et
|
||||
|
||||
La dependency direction reste strictement `Interface -> Core`; aucun serde/codec générique, `solana-instruction`, runtime réseau ou logging n'est introduit. La façade crate-root est verrouillée par canaris public API, consumer externe, release completeness et dependency firewall. [`../../crates/ksp-interface-lib/README.md`](../../crates/ksp-interface-lib/README.md) et [`../../crates/ksp-interface-lib/USAGE.md`](../../crates/ksp-interface-lib/USAGE.md) deviennent les références durables de cette foundation. Le gate technique final `pre.006` est vert avant réconciliation documentaire.
|
||||
|
||||
Aucune `ksp-interface-api` séparée n'est retenue pour l'instant. Les codecs/layouts spécifiques restent conditionnés à un vertical réel, tandis que les wires génériques d'acquisition/CORE restent reportés à `0.3.2+`.
|
||||
Aucune `ksp-interface-api` séparée n'est retenue pour l'instant. Les codecs/layouts spécifiques restent conditionnés à un vertical réel. La décomposition STRUCTURAL générique reste reportée à la série STRUCTURAL ouverte seulement après fermeture de la couche RAW ; elle n'est plus associée à un ancien numéro `0.3.2+` devenu obsolète.
|
||||
|
||||
### `0.2.14` — Program API foundation
|
||||
|
||||
@@ -552,50 +552,62 @@ Le hardening final verrouille l'inventaire crate-root exact, le passage d'une `P
|
||||
|
||||
Restent explicitement reportés : `ksp-program-lib`, payload canonique D3, registry runtime, identity/version/coverage génériques, autres familles de decoder et `ProgramExecutionPreparer`. Ils seront introduits uniquement par les vertical slices qui démontreront leurs contrats réels.
|
||||
|
||||
## Architecture durable : RAW -> CORE -> DECODE -> SPECIALIZED
|
||||
## Architecture durable : RAW -> STRUCTURAL -> DECODED -> DOMAIN
|
||||
|
||||
La chaîne de données est :
|
||||
|
||||
```text
|
||||
D1 RAW
|
||||
-> D2 CORE
|
||||
-> D3 DECODE
|
||||
-> D4 SPECIALIZED
|
||||
-> D2 STRUCTURAL
|
||||
-> D3 DECODED
|
||||
-> D4 DOMAIN
|
||||
```
|
||||
|
||||
RAW et CORE ne nécessitent aucun decoder Program.
|
||||
RAW et STRUCTURAL ne nécessitent aucun decoder Program.
|
||||
|
||||
`RAW -> CORE` est une normalisation générique Solana ; le premier decoder intervient à `CORE -> DECODE`.
|
||||
`RAW -> STRUCTURAL` est une normalisation générique Solana ; le premier decoder intervient à `STRUCTURAL -> DECODED`.
|
||||
|
||||
## Série `0.3.x` — RAW / acquisition persistée
|
||||
|
||||
Début décidé :
|
||||
La séquence effective a évolué par sizing et validation réels. La référence détaillée reste `ROADMAP.md`; cette synthèse conserve uniquement les frontières fonctionnelles :
|
||||
|
||||
```text
|
||||
0.3.1 ksp-store-api + ksp-store-lib, RAW only
|
||||
0.3.2 ksp-interface-lib, wires génériques acquisition/CORE
|
||||
0.3.3 ksp-job-api + backfill
|
||||
0.3.4 application backfill/RAW
|
||||
0.3.1 ksp-store-api RAW
|
||||
0.3.2 Store runtime + backend PostgreSQL foundation
|
||||
0.3.3 persistence RawTransaction
|
||||
0.3.4 persistence RawAccountState
|
||||
0.3.5 Interface acquisition events
|
||||
0.3.6 ksp-job-api + RawTransaction Backfill
|
||||
0.3.7 ksp-app-backfill-desk
|
||||
0.3.8 ksp-app-store-desk RAW
|
||||
0.3.9 ksp-worker-api + audit acquisition RawTransaction
|
||||
0.3.10 common ksp-raw-transaction-lib + preuves cross-source
|
||||
0.3.11-0.3.14 Worker RAW ingest découpé par responsabilité
|
||||
0.3.15 ksp-app-raw-transaction-ingest-desk
|
||||
0.3.16 Backfill multi-source / multi-stratégie
|
||||
```
|
||||
|
||||
La suite de la série termine la couche RAW avec worker/service live et outils d'exploitation utiles avant l'ouverture de CORE.
|
||||
Cette série ferme la couche RAW et ses outils d'exploitation avant l'ouverture fonctionnelle de STRUCTURAL. Le Worker live RAW reste distinct des jobs historiques et ne constitue pas encore une transformation RAW -> STRUCTURAL.
|
||||
|
||||
`0.3.1` ne doit pas créer par anticipation les modèles/tables DECODE/SPECIALIZED.
|
||||
Aucune release RAW ne crée par anticipation la persistence DECODED/DOMAIN.
|
||||
|
||||
## Série CORE suivante
|
||||
## Série STRUCTURAL suivante
|
||||
|
||||
Objectif : rendre CORE exploitable sans aucun decoder Program :
|
||||
Objectif : rendre la couche STRUCTURAL exploitable sans aucun decoder Program. Elle décompose les entrées RAW réellement décomposables en unités Solana génériques plus fines destinées au décodage ultérieur :
|
||||
|
||||
```text
|
||||
RAW persisted
|
||||
-> Solana generic normalization
|
||||
-> CORE persistence
|
||||
-> RAW->CORE replay/backfill
|
||||
-> STRUCTURAL worker/service
|
||||
-> CORE inspection/control app
|
||||
-> Solana generic structural decomposition
|
||||
-> STRUCTURAL persistence
|
||||
-> RAW -> STRUCTURAL replay/backfill
|
||||
-> STRUCTURAL job borné/rejouable
|
||||
-> STRUCTURAL worker/service continu
|
||||
-> STRUCTURAL inspection/control dans ksp-app-store-desk lorsque pertinent
|
||||
```
|
||||
|
||||
## Séries DECODE/SPECIALIZED/EXECUTION suivantes
|
||||
Le nom de couche historique `CORE` est abandonné. `Core` reste réservé à `ksp-core-lib`, à son domaine fondamental et aux noms propres tels que « Solana Core Programs ».
|
||||
|
||||
## Séries DECODED/DOMAIN/EXECUTION suivantes
|
||||
|
||||
À partir du décodage, KSP progresse par vertical slices complets et non par grandes couches de crates isolées :
|
||||
|
||||
@@ -638,7 +650,7 @@ Après les DEX prioritaires, introduire une petite `ksp-app-market-desk` consomm
|
||||
|
||||
Après Jupiter/OKX, enrichir la même app avec routes, legs, DEX impliqués, fees/slippage et quote/execution lorsque disponible.
|
||||
|
||||
L'app ne réimplémente pas les SDK/protocoles DEX ; elle consomme les faits SPECIALIZED normalisés.
|
||||
L'app ne réimplémente pas les SDK/protocoles DEX ; elle consomme les faits DOMAIN normalisés.
|
||||
|
||||
## Discipline de sizing
|
||||
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- file: docs/plans/031-V0_3_10_RAW_TRANSACTION_INGEST_PLAN.md -->
|
||||
<!-- version: 13 -->
|
||||
<!-- version: 14 -->
|
||||
|
||||
# Plan v0.3.10 — RAW Transaction commune + qualification cross-source
|
||||
|
||||
@@ -1044,7 +1044,7 @@ Statut : réalisés, avec fixes déjà tracés et `pre.006-fix.001` requis pour
|
||||
|
||||
### `pre.007` — gate technique final `0.3.10`
|
||||
|
||||
Statut : **ouvert sur `0.3.10-pre.7`** après gate opérateur entièrement vert de `pre.006-fix.002`.
|
||||
Statut : **fermé**. Le gate opérateur sur `0.3.10-pre.7` est entièrement vert, y compris workspace tests, Clippy strict, suites ciblées et graphes demandés.
|
||||
|
||||
Budget cible : **15–20 min**. Rejouer le workspace complet, Clippy strict, suites common/Transport/Backfill, arbres normal/dev/features pertinents et duplicate tree. Aucun nouveau scope fonctionnel ; tout défaut découvert appartient à une tranche corrective dédiée avant de poursuivre la fermeture.
|
||||
|
||||
@@ -1052,7 +1052,9 @@ Le gate exact de cette tranche ne référence plus `ksp-worker-raw-transaction-i
|
||||
|
||||
### `pre.008` — réconciliation documentaire `0.3.10`
|
||||
|
||||
Budget cible : **10–15 min**. Réconcilier plan, validation, README/USAGE de la common si nécessaire et architecture durable avec le périmètre effectivement livré. Aucun runtime Worker, smoke nouveau, CHANGELOG, ROADMAP ou prompt suivant.
|
||||
Statut : **ouvert sur `0.3.10-pre.8`** après fermeture technique de `pre.007`.
|
||||
|
||||
Budget cible : **10–15 min**. Réconcilier plan, validation, séquence fonctionnelle active, règles/architecture durables et README/USAGE de la common avec le périmètre effectivement livré. Normaliser la couche Store D2 (appelée N2 dans certains plans Store historiques) sous le nom `STRUCTURAL` et éliminer les références actives à l'ancien nom de couche `CORE`, sans renommer `ksp-core-lib`, le domaine Core fondamental ou les traces historiques clôturées. `ksp-raw-transaction-lib` doit recevoir `README.md` et `USAGE.md` puisqu'elle devient une bibliothèque complétée. Aucun runtime Worker, smoke nouveau, CHANGELOG ou prompt suivant. `ROADMAP.md` peut être corrigé uniquement pour la nomenclature durable des couches ; ses statuts de publication restent réservés à `pre.009`.
|
||||
|
||||
### `pre.009` — préparation de publication `0.3.10`
|
||||
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- file: docs/rules/RULES_DEPENDENCIES.md -->
|
||||
<!-- version: 17 -->
|
||||
<!-- version: 18 -->
|
||||
|
||||
# Règles des dépendances KSP
|
||||
|
||||
@@ -100,13 +100,13 @@ Elles complètent les règles Rust générales et le graphe de `docs/architectur
|
||||
## Pipelines spécialisés
|
||||
|
||||
- **DEP-PIPE-001** — KSP ne crée pas de `ksp-pipeline-lib` monolithique.
|
||||
- **DEP-PIPE-002** — Les frontières canoniques de processing sont `RAW -> CORE -> DECODE -> SPECIALIZED`. Une crate pipeline dédiée n'est créée que lorsqu'une logique doit réellement être réutilisée entre plusieurs lifecycle hosts (worker/job/app/test) ; aucune liste globale de quatre crates pipeline n'est imposée par symétrie.
|
||||
- **DEP-PIPE-002** — Les frontières canoniques de processing sont `RAW -> STRUCTURAL -> DECODED -> DOMAIN`. Une crate pipeline dédiée n'est créée que lorsqu'une logique doit réellement être réutilisée entre plusieurs lifecycle hosts (worker/job/app/test) ; aucune liste globale de quatre crates pipeline n'est imposée par symétrie.
|
||||
- **DEP-PIPE-003** — Un pipeline de processing dépend des APIs nécessaires à sa frontière et non des implémentations officielles correspondantes lorsque l'API permet l'injection/composition.
|
||||
- **DEP-PIPE-004** — Les pipelines spécialisés ne dépendent pas de `ksp-worker-api` ou `ksp-job-api`; worker et job possèdent le lifecycle.
|
||||
- **DEP-PIPE-005** — Worker live et job de replay/backfill réutilisent le même pipeline pour une même frontière durable afin d'éviter la duplication de logique.
|
||||
- **DEP-PIPE-006** — Le pipeline raw ingestion peut dépendre des modèles homogènes de `ksp-onchain-transport-lib` et de `ksp-store-api`, mais pas de `ksp-store-lib`.
|
||||
- **DEP-PIPE-007** — La transformation `RAW -> CORE` est Solana-générique et ne dépend ni de `ksp-program-api`, ni de `ksp-program-lib`, ni de `ksp-materializer-api`; les premiers contrats Program interviennent seulement à partir de `CORE -> DECODE`.
|
||||
- **DEP-PIPE-008** — À partir de `CORE -> DECODE`, les pipelines/processors verticaux peuvent dépendre de `ksp-program-api` et de `ksp-materializer-api` selon leur rôle, sans dépendre par défaut des implémentations officielles correspondantes lorsque l'injection/composition suffit. `DECODE -> SPECIALIZED` utilise de même les contrats de matérialisation/projection nécessaires sans imposer une implémentation globale unique.
|
||||
- **DEP-PIPE-007** — La transformation `RAW -> STRUCTURAL` est Solana-générique et ne dépend ni de `ksp-program-api`, ni de `ksp-program-lib`, ni de `ksp-materializer-api`; les premiers contrats Program interviennent seulement à partir de `STRUCTURAL -> DECODED`.
|
||||
- **DEP-PIPE-008** — À partir de `STRUCTURAL -> DECODED`, les pipelines/processors verticaux peuvent dépendre de `ksp-program-api` et de `ksp-materializer-api` selon leur rôle, sans dépendre par défaut des implémentations officielles correspondantes lorsque l'injection/composition suffit. `DECODED -> DOMAIN` utilise de même les contrats de matérialisation/projection nécessaires sans imposer une implémentation globale unique.
|
||||
|
||||
## Worker / Job lifecycle
|
||||
|
||||
@@ -115,7 +115,7 @@ Elles complètent les règles Rust générales et le graphe de `docs/architectur
|
||||
- **DEP-WORKER-003** — La logique réutilisable d'un worker/job dépend en priorité des APIs KSP (`ksp-store-api`, `ksp-program-api`, `ksp-materializer-api`, etc.) et reçoit les implémentations par composition. Le binaire/service mince peut câbler `ksp-store-lib` ou les implémentations officielles nécessaires sans transférer cet ownership à la logique du worker/job.
|
||||
- **DEP-JOB-001** — `ksp-job-api` ne dépend ni de `ksp-worker-api` ni de `ksp-worker-control-lib`.
|
||||
- **DEP-JOB-002** — Un orchestrateur futur peut consommer séparément les APIs/contrôles workers et jobs sans introduire un lifecycle parent commun.
|
||||
- **DEP-JOB-003** — Lorsqu'une même transformation existe en live et en replay, jobs et workers réutilisent la même logique de transformation au lieu de dupliquer `RAW -> CORE`, `CORE -> DECODE` ou `DECODE -> SPECIALIZED`.
|
||||
- **DEP-JOB-003** — Lorsqu'une même transformation existe en live et en replay, jobs et workers réutilisent la même logique de transformation au lieu de dupliquer `RAW -> STRUCTURAL`, `STRUCTURAL -> DECODED` ou `DECODED -> DOMAIN`.
|
||||
|
||||
## Services, applications et control plane
|
||||
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- file: docs/rules/RULES_KSP.md -->
|
||||
<!-- version: 39 -->
|
||||
<!-- version: 40 -->
|
||||
|
||||
# Règles spécifiques à KSP
|
||||
|
||||
@@ -141,7 +141,7 @@
|
||||
- **KSP-WORKER-005** — `ksp-worker-raw-retriever` est le worker d'acquisition raw live/quasi-live. Il ne décode pas, ne matérialise pas et ne réalise pas de replay/backfill historique.
|
||||
- **KSP-WORKER-006** — `ksp-worker-raw-retriever` persiste les données raw puis notifie leur disponibilité selon les contrats de données normalisés.
|
||||
- **KSP-WORKER-007** — `ksp-worker-raw-retriever` doit pouvoir faire évoluer à chaud les listeners et la sélection des données qu'il rapatrie/stocke.
|
||||
- **KSP-WORKER-008** — Les workers de processing ne sont pas figés à l'avance sous une chaîne globale `core -> generic materializer -> domain projector`. RAW et CORE peuvent disposer de workers horizontaux propres à leur couche ; à partir de DECODE, les workers/processors sont introduits au besoin avec chaque groupe fonctionnel vertical afin que décodage, matérialisation, projection spécialisée et validation d'exécution évoluent ensemble.
|
||||
- **KSP-WORKER-008** — Les workers de processing ne sont pas figés à l'avance sous une chaîne globale `structural -> generic materializer -> domain projector`. RAW et STRUCTURAL peuvent disposer de workers horizontaux propres à leur couche ; à partir de DECODED, les workers/processors sont introduits au besoin avec chaque groupe fonctionnel vertical afin que décodage, matérialisation, projection spécialisée et validation d'exécution évoluent ensemble.
|
||||
- **KSP-WORKER-009** — Les workers de processing utilisent notification comme wake-up mais reconstruisent leur backlog depuis le Store.
|
||||
- **KSP-WORKER-010** — `ksp-worker-raw-retriever` distingue une configuration desired et une configuration effective lors des reconfigurations à chaud.
|
||||
- **KSP-WORKER-011** — Un cursor de scan est une optimisation ; les processing outcomes durables constituent la preuve qu'un input a été traité pour un processor/version/capability.
|
||||
@@ -161,7 +161,7 @@
|
||||
- **KSP-JOB-006** — D'autres jobs peuvent être introduits pour metadata, quotes ou autres travaux ponctuels lorsqu'un besoin réel le justifie.
|
||||
- **KSP-JOB-007** — Aucune `ksp-job-control-lib` commune n'est prévue actuellement ; elle ne sera créée que si une duplication concrète entre plusieurs jobs le justifie.
|
||||
- **KSP-JOB-008** — Le contrôle/gouvernance des jobs reste séparé du contrôle des workers.
|
||||
- **KSP-JOB-009** — Aucun inventaire global de jobs de replay DECODE/SPECIALIZED n'est figé à l'avance. `RAW -> CORE` peut introduire un job de replay Core lorsque la couche CORE est ouverte ; à partir de DECODE, les jobs de replay sont introduits avec les groupes/capacités verticaux qui en ont réellement besoin, sans imposer des jobs génériques `generic-materialization` / `domain-projection` pour tout Solana.
|
||||
- **KSP-JOB-009** — Aucun inventaire global de jobs de replay DECODED/DOMAIN n'est figé à l'avance. `RAW -> STRUCTURAL` peut introduire un job de replay STRUCTURAL lorsque la couche STRUCTURAL est ouverte ; à partir de DECODED, les jobs de replay sont introduits avec les groupes/capacités verticaux qui en ont réellement besoin, sans imposer des jobs génériques `generic-materialization` / `domain-projection` pour tout Solana.
|
||||
- **KSP-JOB-010** — Les jobs de replay réutilisent exactement le pipeline spécialisé de la frontière correspondante.
|
||||
- **KSP-JOB-011** — Le backfill conserve un checkpoint de progression dans la source historique en plus des outcomes de persistence D1.
|
||||
- **KSP-JOB-012** — Replay normal/reprise et force replay sont deux intentions distinctes ; un force replay conserve provenance/historique et ne supprime pas silencieusement le résultat courant.
|
||||
@@ -181,7 +181,7 @@
|
||||
## Pipelines et scénarios
|
||||
|
||||
- **KSP-PIPE-001** — KSP ne crée pas de `ksp-pipeline-lib` monolithique.
|
||||
- **KSP-PIPE-002** — Les frontières canoniques de données/processing sont `RAW -> CORE -> DECODE -> SPECIALIZED`. Les pipelines RAW et CORE peuvent être développés horizontalement jusqu'à leur acquisition/persistence/replay/worker/app ; à partir de DECODE, KSP progresse par groupes fonctionnels verticaux et ne pré-déclare pas une chaîne globale de crates pipeline pour tous les protocoles.
|
||||
- **KSP-PIPE-002** — Les frontières canoniques de données/processing sont `RAW -> STRUCTURAL -> DECODED -> DOMAIN`. Les pipelines RAW et STRUCTURAL peuvent être développés horizontalement jusqu'à leur acquisition/persistence/replay/worker/app ; à partir de DECODED, KSP progresse par groupes fonctionnels verticaux et ne pré-déclare pas une chaîne globale de crates pipeline pour tous les protocoles.
|
||||
- **KSP-PIPE-003** — Un pipeline spécialisé contient la logique réutilisable d'une frontière mais aucun lifecycle worker/job.
|
||||
- **KSP-PIPE-004** — Les pipelines utilisent les APIs Program/Materializer/Store lorsque ces frontières doivent être injectables ; les implémentations officielles sont composées par workers/jobs.
|
||||
- **KSP-PIPE-005** — Le traitement est at-least-once avec persistence idempotente et outcomes durables, plutôt qu'une promesse exactly-once distribuée.
|
||||
@@ -262,5 +262,5 @@
|
||||
- **KSP-REL-016** — Une prerelease vise environ 15 à 20 minutes de travail effectif. Le `pre.001` dimensionne aussi la release concrète entière : une release doit pouvoir être ouverte, développée, validée et clôturée dans une seule session de chat. Si cette clôture paraît incertaine, la release est scindée avant l'implémentation fonctionnelle lourde ; une version volontairement répartie sur plusieurs sessions est interdite.
|
||||
- **KSP-TRANSPORT-006** — Pour une surface de transport explicitement ciblée, KSP inventorie et implémente toutes les méthodes/opérations exposées par la documentation normative retenue, sauf impossibilité technique explicitement documentée. L'inventaire couvre aussi les sections officielles séparées `deprecated`/`obsolete` et `unstable`/`experimental` lorsqu'elles existent. Les opérations deprecated/obsolete encore réellement fonctionnelles et unstable/experimental restent utilisables mais émettent un `warn` via `ksp-logging-lib` à chaque utilisation concernée ; leur statut est décrit par une metadata centralisée et non par des warnings dispersés.
|
||||
- **KSP-TRANSPORT-007** — La complétude d'un wrapper de transport standard couvre toute la surface sémantique de requête auditée : paramètres, options de configuration, variantes/overloads courants, formes legacy encore supportées et contraintes déterministes connues. Les formes de réponse pertinentes sont conservées losslessly, y compris les variantes, `null` et omissions significatives. KSP peut canonicaliser des syntaxes strictement équivalentes et conserver des sous-arbres wire riches via `serde_json::Value` tant qu'aucune information n'est perdue ; toute limitation volontaire d'une possibilité normative/runtime supportée doit être explicitement justifiée et documentée.
|
||||
- **KSP-FLOW-001** — La progression durable canonique est `RAW -> CORE -> DECODE -> SPECIALIZED`. RAW et CORE ne nécessitent aucun decoder Program ; le passage RAW -> CORE reste une normalisation générique de la blockchain Solana. À partir de DECODE, KSP progresse verticalement par groupe fonctionnel à travers wire, décodage, matérialisation, projection spécialisée si utile, préparation d'exécution, policy, exécution et scénarios de validation.
|
||||
- **KSP-FLOW-001** — La progression durable canonique est `RAW -> STRUCTURAL -> DECODED -> DOMAIN`. RAW et STRUCTURAL ne nécessitent aucun decoder Program ; le passage RAW -> STRUCTURAL reste une décomposition/normalisation structurelle générique de la blockchain Solana. Le nom de couche historique `CORE` est abandonné pour D2 et ne doit pas être réintroduit ; cette règle ne renomme ni `ksp-core-lib`, ni le domaine Core fondamental, ni les noms propres tels que « Solana Core Programs ». À partir de DECODED, KSP progresse verticalement par groupe fonctionnel à travers wire, décodage, matérialisation, projection spécialisée si utile, préparation d'exécution, policy, exécution et scénarios de validation.
|
||||
- **KSP-FLOW-002** — Un programme ou composant satellite nécessaire à la compréhension, la matérialisation ou l'exécution correcte d'un protocole appartient au groupe de ce protocole. Il n'est pas reporté artificiellement dans une catégorie `trading-adjacent`.
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- file: docs/validation/027-V0_3_10_RAW_TRANSACTION_INGEST.md -->
|
||||
<!-- version: 13 -->
|
||||
<!-- version: 14 -->
|
||||
|
||||
# Validation v0.3.10 — RAW Transaction commune + qualification cross-source
|
||||
|
||||
@@ -1018,7 +1018,7 @@ Le même correctif réconcilie aussi l'architecture durable avec l'extraction co
|
||||
```text
|
||||
ksp-raw-transaction-lib est inventoriée explicitement ;
|
||||
son graphe lower-layer est documenté ;
|
||||
CORE processor / CORE worker deviennent STRUCTURAL job / STRUCTURAL worker ;
|
||||
les anciens libellés `CORE processor` / `CORE worker` sont requalifiés en `STRUCTURAL job` / `STRUCTURAL worker` ;
|
||||
le plan conserve une note de génération séquentielle des prompts 0.3.12 -> 0.3.15.
|
||||
```
|
||||
|
||||
@@ -1042,3 +1042,22 @@ Les smokes réseau opt-in de Transport restent `ignored` conformément à leur p
|
||||
|
||||
Tout défaut découvert ouvre `pre.007-fix.NNN`. Tant que le gate `pre.007` n'est pas entièrement vert, `pre.008` de réconciliation documentaire ne doit pas commencer.
|
||||
|
||||
### 13.13 Gate opérateur `pre.007` et ouverture de `pre.008`
|
||||
|
||||
Le rejeu opérateur communiqué le 8 septembre 2026 sur `0.3.10-pre.7` ferme le gate technique final : audits Rust/Markdown, `cargo check --workspace`, Clippy workspace strict, `cargo test --workspace --all-targets --all-features`, suites ciblées common/Transport/Backfill et graphes Cargo demandés sont exécutés sans échec. Les smokes live opt-in restent `ignored` par conception et ne sont pas requalifiés en preuves réseau.
|
||||
|
||||
`pre.008` est exclusivement documentaire. La nomenclature durable des couches de données Store est réconciliée avec la décision prise lors de l'ouverture Store :
|
||||
|
||||
```text
|
||||
D1 = RAW
|
||||
D2 = STRUCTURAL
|
||||
D3 = DECODED
|
||||
D4 = DOMAIN
|
||||
```
|
||||
|
||||
Les plans Store historiques qui parlent de N1–N4 data sont interprétés selon cette correspondance, mais la documentation durable réserve désormais `D1–D4` aux couches de données afin de ne pas entrer en collision avec les niveaux architecturaux N1–N4 de `002-LAYERS_AND_DEPENDENCIES.md`.
|
||||
|
||||
Le terme historique `CORE` n'est plus un nom de couche D2 Store. Il reste valide lorsqu'il désigne `ksp-core-lib`, le domaine Core fondamental ou un nom propre comme « Solana Core Programs ». Les anciens plans/deltas clôturés restent des traces historiques et ne sont pas réécrits en masse.
|
||||
|
||||
La réconciliation vérifie également la documentation durable de `ksp-raw-transaction-lib` : la crate étant désormais une lower-layer complétée de `0.3.10`, elle doit posséder son `README.md` descriptif et son `USAGE.md` version-neutre conformément aux règles de clôture des bibliothèques KSP.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user