Sasedev/khadhroony-solana-project
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
c71fb2d8fe75cec8be8b2b348ef699da82d29ea0
khadhroony-solana-project/deltas/0.3.6/pre.006.md
SinuS Von SifriduS 032919fa07 v0.3.6-pre.006
2026-09-01 14:08:53 +02:00

273 lines
9.9 KiB
Markdown
Raw Blame History

<!-- file: deltas/0.3.6/pre.006.md -->
<!-- version: 1 -->
# Delta `0.3.6-pre.006` — conversion RAW transaction v1 et provenance observée
## Base requise
```text
0.3.6-pre.005-fix.001 appliquée
workspace.package.version = 0.3.6-pre.5.fix.1
```
La base opérateur inclut également la synchronisation manuelle des versions d'en-tête omise dans l'archive initiale du fix :
```text
Cargo.toml header 400 -> 401
crates/ksp-job-backfill-lib/src/discovery.rs header 1 -> 2
```
Le gate opérateur fourni pour cette base confirme :
```text
cargo fmt --all PASS
python3 scripts/audit_rust_workspace_rules.py PASS / clean
python3 scripts/audit_markdown_tables.py ... PASS / clean (264 tables / 148 fichiers)
cargo check --workspace PASS
cargo clippy --workspace --all-targets PASS
cargo test -p ksp-job-backfill-lib PASS
unitaires 11 PASS
dependency_boundary 2 PASS
public_api 2 PASS
release_completeness 2 PASS
cargo tree -p ksp-job-backfill-lib --edges normal exécuté
cargo tree -p ksp-job-backfill-lib -e features exécuté
```
## Objectif
Matérialiser exclusivement la tranche `pre.006` du plan 027 : convertir un candidat Backfill déjà découvert en transaction RAW canonique v1 et en observation d'acquisition sûre à partir du chemin Transport observé `getTransaction`, sans encore persister dans Store ni ouvrir le runtime de Job.
L'identité logique reste strictement :
```text
RawTransactionReference = (RawNetworkId, RawTransactionSignature)
```
Provider, endpoint, protocole, méthode Transport et `JobId` ne deviennent jamais une identité de transaction. Ils servent uniquement à caractériser l'acquisition et, lorsqu'une transaction existe, l'identité déterministe de son observation.
## Signature canonique
`BackfillSignature::to_raw_transaction_signature` ajoute le passage de la forme Base58 bornée de `pre.005` vers `RawTransactionSignature` exactement 64 octets.
Le décodeur Base58 est privé, borné et spécialisé pour cette frontière :
- alphabet Base58 Solana exact ;
- exactement 64 octets décodés requis ;
- zéros initiaux `1` conservés ;
- dépassement arithmétique rejeté ;
- aucune dépendance SDK/protocolaire Solana ;
- aucune nouvelle dépendance Base58 externe.
La conversion ne modifie pas l'identité réseau du candidat et rejette avant Transport tout candidat dont le réseau diffère de la requête.
## Hydratation Transport observée
La voie publique :
```text
hydrate_backfill_candidate
```
appelle exclusivement :
```text
HttpTransportPool::get_transaction_observed
```
avec :
```text
encoding = base64
commitment = engagement explicite du Backfill
maxSupportedTransactionVersion = 0
```
Transport reste propriétaire du routage, retry, pacing, cooldown et endpoint victorieux. Job n'introduit aucun second client ni boucle de retry.
Deux outcomes sont distingués :
- `Available(BackfillRawAcquisition)` : transaction présente, RAW v1 et observation construits en mémoire ;
- `Missing(RawTransactionReference)` : JSON RPC `result: null`, aucune provenance ni observation fabriquée.
## RAW transaction v1
Le format KSP figé par la tranche est :
```text
format_id = ksp.solana.raw_transaction
format_version = 1
```
Le payload canonique est du JSON UTF-8 compact déterministe. La forme top-level est construite dans cet ordre :
1. `transaction` ;
2. `meta` si le champ wire n'est pas omitted ;
3. `version` si le champ wire n'est pas omitted ;
4. `transactionIndex` si le champ wire n'est pas omitted.
La transaction est conservée sans décodage métier sous la forme :
```json
["<base64>","base64"]
```
Les objets JSON imbriqués sont canonisés récursivement par tri lexical des clés ; l'ordre des tableaux reste intact. Les états wire `Omitted`, `Null` et `Value` de `meta`, `version` et `transactionIndex` restent distincts.
`slot` et `blockTime` appartiennent aux champs structurés de `RawTransaction` et ne sont pas dupliqués dans le payload. Un `blockTime` négatif ou non représentable dans `RawTimestamp` est une erreur de conversion terminale.
SHA-256 et `byte_len` sont calculés sur les octets canoniques exacts avant construction de `RawPayload`.
Les réponses transactionnelles non Base64 sont rejetées ; Job ne bascule pas vers une interprétation JSON/jsonParsed ou fournisseur.
## Provenance d'acquisition
Une transaction disponible produit `RawAcquisitionProvenance` avec :
- provider réellement victorieux ;
- protocole sûr `solana.http.json_rpc` ;
- méthode `getTransaction` ;
- endpoint sûr réellement victorieux ;
- engagement demandé ;
- `JobId` comme capture session id ;
- origine `Backfill` ;
- timestamp de réception fourni par l'hôte.
Aucun URL, header, secret, body HTTP ou payload fournisseur brut n'est copié dans la provenance.
La clé `RawTransactionObservationKey` utilise SHA-256 avec séparation de domaine et couvre :
- `JobId` ;
- fingerprint du scope ;
- signature RAW 64 octets ;
- provider ;
- endpoint ;
- engagement ;
- version du contrat d'observation.
Même réseau + même signature + endpoint différent représente donc toujours la même transaction logique mais une observation d'acquisition distincte.
## Dépendances
La crate conserve ses dépendances KSP de `pre.005` et ajoute uniquement :
```text
serde_json.workspace = true
```
`serde_json` est déjà centralisé dans `[workspace.dependencies]`. `sha2` reste la primitive SHA-256 déjà présente. Aucune dépendance `bs58`, SDK Solana, Store API/backend, Config, reqwest ou tonic n'est ajoutée.
## Tests matérialisés
La tranche ajoute **8 tests unitaires**, portant le total de `ksp-job-backfill-lib` à **19 unitaires** :
- décodage Base58 exact 64 octets, longueur excessive et overflow ;
- golden payload canonique, longueur, SHA-256 et provenance ;
- distinction omitted/null des champs wire ;
- rejet des transactions non Base64 ;
- block times négatifs ou non représentables ;
- clé d'observation déterministe et sensible à provider/endpoint ;
- mismatch réseau rejeté avant Transport ;
- outcome Missing limité à la référence réseau + signature.
Une canarie publique supplémentaire porte les canaries d'intégration à **7** :
- `dependency_boundary` : 2 ;
- `public_api` : 3 ;
- `release_completeness` : 2.
Les canaries verrouillent en outre l'usage du chemin observé, `base64`, `maxSupportedTransactionVersion = 0`, l'absence de persistance et les firewalls de dépendances.
## Fichiers ajoutés
```text
crates/ksp-job-backfill-lib/src/conversion.rs
crates/ksp-job-backfill-lib/unit_tests/conversion.rs
deltas/0.3.6/pre.006.md
```
## Fichiers modifiés
```text
Cargo.toml
crates/ksp-job-backfill-lib/Cargo.toml
crates/ksp-job-backfill-lib/src/error.rs
crates/ksp-job-backfill-lib/src/lib.rs
crates/ksp-job-backfill-lib/src/request.rs
crates/ksp-job-backfill-lib/tests/dependency_boundary.rs
crates/ksp-job-backfill-lib/tests/public_api.rs
crates/ksp-job-backfill-lib/tests/release_completeness.rs
docs/plans/027-V0_3_6_JOB_API_BACKFILL_PLAN.md
docs/validation/023-V0_3_6_JOB_API_BACKFILL.md
```
## Versions d'en-tête
Tous les fichiers Rust/TOML modifiés par cette tranche incrémentent leur version d'en-tête par rapport à la base opérateur corrigée :
```text
Cargo.toml 401 -> 402
crates/ksp-job-backfill-lib/Cargo.toml 1 -> 2
crates/ksp-job-backfill-lib/src/error.rs 1 -> 2
crates/ksp-job-backfill-lib/src/lib.rs 1 -> 2
crates/ksp-job-backfill-lib/src/request.rs 1 -> 2
crates/ksp-job-backfill-lib/tests/dependency_boundary.rs 1 -> 2
crates/ksp-job-backfill-lib/tests/public_api.rs 1 -> 2
crates/ksp-job-backfill-lib/tests/release_completeness.rs 1 -> 2
```
Les nouveaux fichiers Rust commencent à `version: 1`. Les documents Markdown modifiés incrémentent eux aussi leur en-tête documentaire : plan 027 et validation 023 passent de `9` à `10`.
## Version workspace
La tranche modifie du code Rust et le manifeste runtime de la crate :
```text
workspace.package.version = 0.3.6-pre.6
delivery = 0.3.6-pre.006
commit = v0.3.6-pre.006
```
Aucun tag prerelease.
## Fichiers supprimés
Aucun.
## Frontières conservées
- aucune persistance Store ;
- aucune prélecture Store avant hydratation ;
- aucun checkpoint ou frontier contiguë ;
- aucune concurrence d'hydratation concrète ;
- aucun snapshot Job concret ;
- aucune Config/env ;
- aucun Worker ou exécutable ;
- aucune modification Transport ou Store ;
- aucun endpoint/provider/protocole dans l'identité transactionnelle ;
- aucun README, USAGE, CHANGELOG ou ROADMAP rouvert ;
- aucun code kbot3 copié.
## Validations dans l'environnement d'assemblage
L'environnement d'assemblage exécute les audits statiques du dépôt et les contrôles d'archive. Il ne possède ni `cargo`, ni `rustc`, ni `rustfmt`; le gate Rust de `pre.006` doit donc être rejoué par l'opérateur avant clôture.
## Gate opérateur demandé
```bash
cargo fmt --all
python3 scripts/audit_rust_workspace_rules.py
python3 scripts/audit_markdown_tables.py README.md RULES.md ROADMAP.md CHANGELOG.md docs prompts crates deltas/0.3.6
cargo check --workspace
cargo clippy --workspace --all-targets
cargo test -p ksp-job-backfill-lib
cargo tree -p ksp-job-backfill-lib --edges normal
cargo tree -p ksp-job-backfill-lib -e features
```
Résultat attendu : **19 tests unitaires + 7 canaries d'intégration**, sans persistance Store et avec un graphe normal qui conserve `ksp-store-lib` sans backend imposé.
## Questions ouvertes
Aucune pour `pre.006`. La persistance atomique Store et ses outcomes restent réservés à `pre.007` après gate vert de cette tranche.
Reference in New Issue View Git Blame Copy Permalink