Sasedev/khadhroony-solana-project
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
463c82bfcfce0de5fb45eaf70a0e743b1f825a1a
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

9.9 KiB
Raw Blame History

Delta 0.3.6-pre.006 — conversion RAW transaction v1 et provenance observée

Base requise

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 :

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 :

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 :

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 :

hydrate_backfill_candidate

appelle exclusivement :

HttpTransportPool::get_transaction_observed

avec :

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 :

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 :

["<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 :

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

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

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 :

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 :

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é

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