269 lines
9.5 KiB
Markdown
269 lines
9.5 KiB
Markdown
<!-- file: deltas/0.3.13/pre.005.md -->
|
|
<!-- version: 1 -->
|
|
|
|
# Delta 0.3.13-pre.005 — Helius transactionSubscribe + hydration Common RAW
|
|
|
|
## Base requise
|
|
|
|
```text
|
|
livraison précédente : 0.3.13-pre.004-fix.001
|
|
Cargo base : 0.3.13-pre.4.fix.1
|
|
delta base : deltas/0.3.13/pre.004-fix.001.md
|
|
archive delta base : ksp-general-0.3.13-pre.004-fix.001.zip
|
|
```
|
|
|
|
Le gate opérateur reçu le 10 septembre 2026 sur cette base est vert pour toutes les commandes exécutées : `cargo fmt`, `cargo fmt --check`, audits Rust/Markdown, `cargo check --workspace`, Clippy strict et toutes les suites de `ksp-worker-raw-transaction-ingest-lib` (`79` unit, `4` cross-layer, `11` dependency-boundary, `18` hardening, `12` public-api, `4` release-completeness, `0` doc-test). Cette exécution ne contenait pas le test Transport ni les commandes `cargo tree`; ils ne sont donc pas déclarés PASS pour ce gate précis.
|
|
|
|
## Objectif
|
|
|
|
Ajouter la source Helius WebSocket prévue par la tranche sans dupliquer le chemin Common RAW :
|
|
|
|
```text
|
|
Helius LaserStream transactionSubscribe
|
|
-> Full + Base64 + maxSupportedTransactionVersion=1 + showRewards=false
|
|
-> projection privée signature + slot + transactionIndex
|
|
-> coordinateur d'hydration source-neutral existant
|
|
-> HTTP getTransaction observed
|
|
-> Common RAW canonique
|
|
-> admission centrale Worker
|
|
-> Store
|
|
```
|
|
|
|
Le nested payload transaction Helius n'est pas utilisé comme RAW-direct. Il reste possédé par Transport et n'est jamais copié dans le signal Worker.
|
|
|
|
## Version
|
|
|
|
```text
|
|
livraison : 0.3.13-pre.005
|
|
workspace.package.version : 0.3.13-pre.5
|
|
archive : ksp-general-0.3.13-pre.005.zip
|
|
```
|
|
|
|
`Cargo.toml` passe de la version de fichier `547` à `548`.
|
|
|
|
## Source Helius Transaction
|
|
|
|
Nouvelle surface publique Worker :
|
|
|
|
```text
|
|
RawTransactionIngestHeliusTransactionSource
|
|
RawTransactionIngestRuntimeResources::from_helius_transaction_source
|
|
RawTransactionIngestRuntimeResources::try_push_helius_transaction_source
|
|
```
|
|
|
|
Construction caller-composed :
|
|
|
|
```text
|
|
WsEndpointSettings kind helius_laserstream
|
|
HeliusTransactionSubscribeFilter
|
|
SolanaCommitment Confirmed ou Finalized
|
|
HttpTransportPool
|
|
HttpRoleName d'hydration
|
|
```
|
|
|
|
La construction est sans I/O. Elle refuse un endpoint invalide ou non Helius LaserStream, `Processed`, un réseau/provenance non représentable et l'absence d'une route HTTP `getTransaction` compatible sur le même réseau.
|
|
|
|
Au runtime, la source réutilise exclusivement les façades Transport existantes :
|
|
|
|
```text
|
|
HeliusLaserStreamWsSession::connect
|
|
HeliusLaserStreamWsSession::transaction_subscribe
|
|
HttpTransportPool::get_transaction_observed via le coordinateur commun
|
|
```
|
|
|
|
Aucun client WebSocket direct, SDK Helius, `reqwest`, `tokio-tungstenite`, backend Store ou accès Config n'est ajouté au Worker.
|
|
|
|
## Requête Helius qualifiée
|
|
|
|
La requête Worker est fixée à :
|
|
|
|
```text
|
|
commitment = Confirmed | Finalized
|
|
encoding = Base64
|
|
transactionDetails = Full
|
|
showRewards = false
|
|
maxSupportedTransactionVersion = 1
|
|
```
|
|
|
|
Une notification productive doit être `HeliusTransactionNotification::Full`. Une forme `Signature`, `Unknown` ou future malgré la requête `Full` devient `source.helius_transaction_notification_unqualified`; elle n'est jamais convertie en succès silencieux.
|
|
|
|
## Projection et hydration
|
|
|
|
Le signal privé issu d'une notification `Full` conserve seulement :
|
|
|
|
```text
|
|
network
|
|
signature
|
|
slot
|
|
transactionIndex
|
|
safe route identity
|
|
private filter fingerprint
|
|
commitment via hydration context
|
|
```
|
|
|
|
Le nested champ `transaction` de la notification Helius n'est pas lu par `project_helius_transaction_signal` et n'est pas copié dans Worker. La construction Common RAW reste donc unique : `getTransaction observed` en Base64 avec `maxSupportedTransactionVersion = 1`, puis canonicalisation/admission existantes.
|
|
|
|
Le coordinateur d'hydration reste borné et source-neutral :
|
|
|
|
```text
|
|
in-flight hydration <= persistence_concurrency
|
|
pending source signals <= admission_queue_capacity
|
|
coalescence key = network + signature + commitment
|
|
```
|
|
|
|
Cette voie converge avec Yellowstone et Standard Logs au lieu d'introduire un second moteur HTTP.
|
|
|
|
## Identité logique, redaction et secrets
|
|
|
|
Le `source_key` Helius est dérivé de :
|
|
|
|
```text
|
|
domain KSP live-source v1
|
|
family = helius_transaction
|
|
network
|
|
safe provider identity
|
|
safe endpoint identity
|
|
commitment
|
|
private normalized Helius filter fingerprint
|
|
SHA-256 -> [u8; 32]
|
|
```
|
|
|
|
L'empreinte privée couvre `vote`, `failed`, signature exacte, listes `accountInclude`/`accountExclude`/`accountRequired` et `tokenAccounts`. Les listes de pubkeys sont triées avant hash afin que leur ordre ne crée pas artificiellement deux identités logiques. Le rôle/pool HTTP d'hydration reste exclu du `source_key`.
|
|
|
|
Les URLs et credentials restent encapsulés par les settings Transport privés utilisés pour ouvrir les connexions ; ils ne sont exposés ni par l'API publique ni par `Debug`. Les valeurs de signature/pubkeys du filtre et les octets de `source_key` ne sont pas rendus dans les diagnostics Worker.
|
|
|
|
Les profils Config Helius et `KSP_SECRET_HELIUS_API_KEY` existaient déjà avant cette tranche. Aucun changement Config, `.env`, entitlement, quota, prix ou tier provider n'est codé dans Worker.
|
|
|
|
## Activation runtime
|
|
|
|
Le contrat reste volontairement mono-source avant `pre.007` :
|
|
|
|
```text
|
|
1 source Yellowstone : productif
|
|
1 source Standard Logs : productif
|
|
1 source Standard Block : productif
|
|
1 source Helius Transaction : productif
|
|
2..32 sources : composition validable
|
|
start 2..32 : runtime_resources.multi_source_activation_pending avant spawn
|
|
```
|
|
|
|
Aucune source configurée n'est silencieusement ignorée.
|
|
|
|
## Preuves ajoutées
|
|
|
|
Unit tests Worker :
|
|
|
|
```text
|
|
validation protocole/commitment/route HTTP Helius
|
|
requête fixe Full/Base64/maxV1/showRewards=false
|
|
source_key filter-sensitive, order-normalized et hydration-role-neutral
|
|
Debug redacted : signature/pubkeys/URL/API key/source-key absents
|
|
projection Full -> signature/slot/index uniquement
|
|
Helius reference -> un getTransaction observed -> Common RAW exact
|
|
provenance helius_ws_http + transaction_get_transaction
|
|
rejet transactionnel d'une identité Helius dupliquée
|
|
```
|
|
|
|
Canaris externes :
|
|
|
|
```text
|
|
public_api : construction/from/push depuis crate root sans escape hatch des ressources internes
|
|
dependency_boundary : façades Transport Helius + un seul getTransaction commun
|
|
hardening : nested payload non copié, secrets/redaction et absence de tier provider
|
|
release_completeness : export et canaris pre.005 obligatoires
|
|
```
|
|
|
|
## Documentation corrigée
|
|
|
|
La documentation Worker est mise à jour pour inclure la source Helius et la convergence d'hydration. Une mention héritée de `README.md` qui classait encore `blockSubscribe` et Helius parmi les sources hors périmètre est supprimée ; `USAGE.md` reste volontairement version-neutral.
|
|
|
|
## Fichiers modifiés
|
|
|
|
```text
|
|
Cargo.toml
|
|
crates/ksp-worker-raw-transaction-ingest-lib/README.md
|
|
crates/ksp-worker-raw-transaction-ingest-lib/USAGE.md
|
|
crates/ksp-worker-raw-transaction-ingest-lib/src/lib.rs
|
|
crates/ksp-worker-raw-transaction-ingest-lib/src/runtime_resources.rs
|
|
crates/ksp-worker-raw-transaction-ingest-lib/tests/dependency_boundary.rs
|
|
crates/ksp-worker-raw-transaction-ingest-lib/tests/hardening.rs
|
|
crates/ksp-worker-raw-transaction-ingest-lib/tests/public_api.rs
|
|
crates/ksp-worker-raw-transaction-ingest-lib/tests/release_completeness.rs
|
|
crates/ksp-worker-raw-transaction-ingest-lib/unit_tests/runtime_resources.rs
|
|
docs/plans/034-V0_3_13_MULTI_SOURCE_LIVE_CONVERGENCE_PLAN.md
|
|
docs/validation/030-V0_3_13_MULTI_SOURCE_LIVE_CONVERGENCE.md
|
|
```
|
|
|
|
## Fichiers ajoutés
|
|
|
|
```text
|
|
deltas/0.3.13/pre.005.md
|
|
```
|
|
|
|
## Fichiers supprimés
|
|
|
|
```text
|
|
aucun
|
|
```
|
|
|
|
## Non-claims
|
|
|
|
`pre.005` ne prétend pas :
|
|
|
|
```text
|
|
supervision simultanée de plusieurs sources
|
|
HTTP live block polling
|
|
RAW-direct depuis le nested payload Helius
|
|
SDK Helius dans Worker
|
|
secret/API key lu directement par Worker
|
|
nouveau profil Config Helius
|
|
entitlement/tier/quota/prix provider codé
|
|
modification de ksp-onchain-transport-lib
|
|
nouvelle dépendance externe
|
|
```
|
|
|
|
## Validation dans l'environnement d'assemblage
|
|
|
|
Le toolchain Rust/Cargo/Rustfmt n'est pas disponible dans l'environnement d'assemblage. Les commandes Cargo post-`pre.005` restent donc `NON EXÉCUTÉ LOCAL`. Les audits statiques KSP, le scan des identifiants normatifs et le contrôle exhaustif du diff sont exécutés avant packaging.
|
|
|
|
## Gate opérateur requis avant pre.006
|
|
|
|
```bash
|
|
cargo fmt --all
|
|
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
|
|
cargo test -p ksp-onchain-transport-lib
|
|
cargo test -p ksp-worker-raw-transaction-ingest-lib
|
|
cargo tree -p ksp-worker-raw-transaction-ingest-lib --edges normal
|
|
cargo tree -p ksp-worker-raw-transaction-ingest-lib -e features
|
|
cargo tree --duplicates
|
|
```
|
|
|
|
`pre.006` ne doit pas commencer si ce gate révèle une anomalie.
|
|
|
|
## Résultats statiques finaux de l'assemblage
|
|
|
|
```text
|
|
General Rust rule audit: clean
|
|
Rust export completeness audit: 0 candidate(s)
|
|
KSP workspace Rust rule audit: clean
|
|
Markdown table audit: clean (340 tables, 837 files)
|
|
Normative rule definitions: 489
|
|
Unique normative IDs: 489
|
|
Duplicates: 0
|
|
```
|
|
|
|
## Contrôle exhaustif avant packaging
|
|
|
|
```text
|
|
12 fichiers existants modifiés
|
|
1 fichier ajouté
|
|
0 fichier supprimé
|
|
12/12 headers de fichiers existants incrémentés exactement de +1
|
|
Cargo.toml : version workspace uniquement hors header
|
|
aucune dépendance ajoutée/modifiée/supprimée
|
|
```
|