23 KiB
Prompt de démarrage 0.3.13 — WS standard / Helius / HTTP live + convergence multi-source du Worker RawTransaction
1. Identité de la release et base exacte requise
Ouvrir uniquement 0.3.13 depuis la release stable/taggée :
v0.3.12
La base de travail fournie par l'opérateur est autoritaire sur les souvenirs, snippets, anciennes archives et deltas intermédiaires. Avant toute modification, vérifier au minimum :
workspace.package.version = 0.3.12
deltas/0.3.12/rel.001.md présent
crates/ksp-worker-raw-transaction-ingest-lib présent avec source Yellowstone productive
ksp-worker-raw-transaction-ingest-lib -> ksp-onchain-transport-lib matérialisé
ksp-worker-raw-transaction-ingest-lib sans dépendance Config/Job/backend Store direct
ksp-raw-transaction-lib présent comme Common RAW source-neutral
ksp-store-lib reste la seule façade Store du Worker
moteur WS standard/Helius existant dans ksp-onchain-transport-lib
getTransaction/getBlock observed existants dans ksp-onchain-transport-lib
Release ouverte :
0.3.13
Première livraison attendue :
0.3.13-pre.001
pre.001 est obligatoirement un gate de lecture + audit interne/externe + brainstorming + sizing + planification. Il ne commence pas directement les sources WS/Helius/HTTP polling ni la transformation de RawTransactionIngestRuntimeResources en collection multi-source. Si le périmètre réel n'est pas clôturable dans une seule session ou si une tranche paraît dépasser environ 15–20 minutes de travail effectif, rescinder avant l'implémentation lourde.
2. Mission et résultat attendu
2.1 Mission de 0.3.13
Étendre la verticale 0.3.12 avec les voies live complémentaires déjà qualifiées par l'architecture :
WS standard logsSubscribe + hydration HTTP
WS standard blockSubscribe
Helius transactionSubscribe + hydration HTTP
HTTP live polling par slots/blocs
convergence simultanée multi-source vers le pipeline central existant
observations multiples pour une même RawTransaction
coalescence/déduplication bornée avant hydration/admission
content conflict explicite si une même identité produit un contenu canonique divergent
backpressure et source health sous concurrence multi-source
Le résultat visé est un Worker capable de superviser plusieurs sources live indépendantes sans second actor Transport, sans lire Config lui-même et sans transformer la convergence en stratégie first-provider-wins silencieuse.
2.2 Pipeline durable à préserver
Toutes les sources convergent vers le même cœur :
source live
-> signal ou matériau source/protocole
-> hydration si le RAW complet n'est pas prouvé
-> ksp-raw-transaction-lib
-> RawTransaction + RawTransactionObservation
-> admission centrale Worker
-> ksp-store-lib
Décisions déjà acquises :
logsSubscribe -> discovery/signature -> getTransaction hydration
Helius transactionSubscribe -> matériau riche mais hydration tant que blockTime/version manquent
blockSubscribe full/base64 -> RAW-direct uniquement sur le sous-ensemble déjà prouvé par fixtures
HTTP polling -> getSlot/bornes -> getBlock observed -> transactions -> Common RAW
même identité + même contenu -> idempotence + observations distinctes utiles
même identité + contenu divergent -> content conflict explicite
Aucune source ne doit contourner Common RAW ou la façade Store.
3. Sources de vérité internes obligatoires — ordre de lecture
3.1 Gouvernance générale
Lire intégralement, dans cet ordre :
RULES.md
ROADMAP.md
CHANGELOG.md
docs/000-README.md
docs/rules/RULES_GENERAL.md
docs/rules/RULES_KSP.md
docs/rules/RULES_RUST.md
docs/rules/RULES_DEPENDENCIES.md
docs/rules/RULES_DOCUMENTATION.md
docs/rules/FILE_CONTRACTS.md
docs/rules/VERSION_WORKFLOW.md
docs/rules/PROMPT_STRUCTURE.md
Le prompt complète ces règles ; il ne les remplace pas.
Rappels Rust bloquants :
Rust 2024
unsafe interdit
unwrap / expect / panic interdits selon les règles KSP
? interdit en production
retours explicites ; clippy::implicit_return deny
#![warn(missing_docs)]
#![deny(unreachable_pub)]
#![forbid(unsafe_code)]
pas de pub mod
pub/pub(crate) partagés reexportés jusqu'à la crate root
accès partagés via crate::Item, y compris intra-crate
item strictement module-local => private
unit tests sous unit_tests/
integration tests sous tests/
Après toute modification Rust :
cargo fmt --all
python3 scripts/audit_rust_workspace_rules.py
cargo check --workspace
cargo clippy --workspace --all-targets
Pour tout Markdown touché :
python3 scripts/audit_markdown_tables.py README.md RULES.md ROADMAP.md CHANGELOG.md docs prompts crates deltas
Une commande non exécutée n'est jamais déclarée PASS.
3.2 Handoff stable 0.3.12
Lire intégralement :
docs/plans/033-V0_3_12_YELLOWSTONE_HYDRATION_CONTINUITY_PLAN.md
docs/validation/029-V0_3_12_YELLOWSTONE_HYDRATION_CONTINUITY.md
crates/ksp-worker-raw-transaction-ingest-lib/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/
crates/ksp-worker-raw-transaction-ingest-lib/tests/
crates/ksp-worker-raw-transaction-ingest-lib/unit_tests/
La verticale Yellowstone/hydration/frontier est une base à préserver, pas un prototype à remplacer.
3.3 Architecture RAW et convergence
Lire intégralement :
docs/architecture/004-COMPONENT_INVENTORY.md
docs/architecture/005-DEPENDENCY_GRAPH.md
docs/architecture/009-ACQUISITION_WORKERS_AND_JOBS.md
docs/architecture/011-RAW_TRANSACTION_ACQUISITION.md
crates/ksp-raw-transaction-lib/README.md
crates/ksp-raw-transaction-lib/USAGE.md
crates/ksp-store-api/src/
crates/ksp-store-lib/src/
Porter une attention particulière à :
observations multiples ≠ identité RawTransaction
même identité + contenu divergent = conflit explicite
capabilities orthogonales aux producteurs
WS logsSubscribe
WS blockSubscribe
Helius transactionSubscribe
HTTP getSlot/getBlock live polling
provenance observed
reconnect WS != replay adressable
continuité multi-source finale encore reportée à 0.3.14
3.4 Transport WS / HTTP / Helius existant
Lire au minimum :
crates/ksp-onchain-transport-lib/Cargo.toml
crates/ksp-onchain-transport-lib/README.md
crates/ksp-onchain-transport-lib/USAGE.md
crates/ksp-onchain-transport-lib/src/ws_*.rs
crates/ksp-onchain-transport-lib/src/rpc_transactions.rs
crates/ksp-onchain-transport-lib/src/rpc_blocks.rs
crates/ksp-onchain-transport-lib/src/http_*.rs
crates/ksp-onchain-transport-lib/tests/
Réutiliser les sessions/actors Transport existants. Il est interdit de recréer dans le Worker :
nouveau socket WebSocket bas niveau
client Helius parallèle
client reqwest direct
reconnect/resubscribe actor concurrent
SDK provider
3.5 Config et secrets
Lire :
crates/ksp-config-lib/src/transport.rs
config/transport*.json
config/schema/*transport*.json
.env.example
Config reste le seul propriétaire des endpoints, profils, capabilities et secrets. En particulier, si Helius est activé pour cette release, réutiliser exclusivement le secret Config déjà défini pour Helius ; le Worker ne lit jamais l'environnement et ne reçoit jamais une clé API comme payload métier.
4. Sources externes normatives et fraîcheur à réauditer
Au début de pre.001, réauditer les surfaces courantes à partir des sources primaires réellement actuelles :
Solana RPC/WebSocket documentation
logsSubscribe
blockSubscribe
getSlot / getBlocks / getBlocksWithLimit / getBlock
commitment et maxSupportedTransactionVersion
Helius documentation officielle
transactionSubscribe
filtres/options réellement supportés
Mainnet/Devnet disponibles
tier/quota/rate limits actuels
champs blockTime/version réellement présents ou absents
crates/projets primaires réellement concernés
versions stables courantes
features nécessaires
Ne pas figer dans le plan une limite provider historique sans la revalider. Une différence entre documentation externe actuelle et surface KSP existante devient un point d'audit explicite, pas une permission de contourner Transport.
5. État validé à préserver
0.3.12 fournit déjà :
Worker concret start/stop + supervisor
admission centrale mpsc bornée
persistence Store atomique/idempotente
Common RAW Legacy/V0/V1
une source Yellowstone caller-composed
Transaction / TransactionStatus / Block -> hydration transactionnelle
BlockMeta / Slot -> continuity-only
coalescence bornée network/signature/commitment
getTransaction observed
processing frontier run-local
source state Active/Reconnecting/Closing/Closed/Failed
compteurs reconnect/replay-attempt/continuity-gap
fault sur gap de rétention prouvé
shutdown borné + abort/join
cross-layer dependency/security canaries
Frontières non négociables :
Worker -> Config interdit
Worker -> Job Backfill interdit
Worker -> backend Store physique interdit
Transport -> Common RAW interdit
Common RAW -> Transport interdit
pas d'URL/token/provider payload dans snapshot/debug/error
pas de checkpoint persistant de processing frontier
pas de campagne historique arbitraire dans le Worker
Le gate 0.3.12 a aussi prouvé live HTTP Devnet et WebSocket Devnet keyless ; il n'a pas prouvé live Yellowstone ni un Worker end-to-end avec Store. Ne pas transformer ces non-preuves en hypothèses acquises.
6. Décisions acquises et questions réellement ouvertes
6.1 Décisions acquises
une RawTransaction est identifiée par (network, signature)
la provenance appartient aux observations, pas à l'identité canonique
plusieurs sources peuvent produire plusieurs observations du même RAW
content conflict reste terminal/explicite, jamais first-provider-wins silencieux
logsSubscribe nécessite hydration
Helius transactionSubscribe nécessite hydration tant que son enveloppe reste incomplète pour RAW v1
blockSubscribe direct reste limité au sous-ensemble réellement qualifié
HTTP polling est une source live valide s'il suit uniquement le frontier du run courant
WS reconnect/resubscribe n'est pas un replay adressable
repair de gap multi-source final appartient à 0.3.14
6.2 Questions à fermer par pre.001
forme exacte de RawTransactionIngestRuntimeResources multi-source
identité/source key interne commune aux sources live
activation simultanée vs priorités/fallback : sémantique exacte
coalescence cross-source avant ou après hydration selon matériau disponible
comment conserver plusieurs observations sans dupliquer la canonicalisation
blockSubscribe : sous-ensembles Legacy/V0/V1 réellement directs aujourd'hui
HTTP polling : borne initiale, cadence, slot skip et ownership du timer
source health individuel vs agrégation Worker publique
limites exactes de pending/coalescence par source et globales
Helius : profils/tier réellement testables avec les comptes opérateur disponibles
Aucune de ces questions ne doit être tranchée par un ajout opportuniste pendant le codage.
7. Objectifs/livrables et hors périmètre
7.1 Livrables cibles
Sous réserve du sizing pre.001 :
contrat runtime resources réellement multi-source et borné
source WS logsSubscribe productive + hydration
source WS blockSubscribe productive
source Helius transactionSubscribe productive + hydration
source HTTP live block polling productive
convergence vers la même admission/persistence centrale
coalescence et observation semantics cross-source
source health/backpressure/faults cohérents
fixtures déterministes cross-source
smokes live uniquement lorsqu'ils sont réellement accessibles
README/USAGE/architecture réconciliés à la fin
7.2 Hors périmètre 0.3.13
gap repair multi-source complet
replay historique arbitraire
appel automatique au Backfill
checkpoint durable Worker
source archive/historical provider
EARLY/pre-execution/shreds
nouveau SDK provider
nouveau backend Store ou migration Store
nouvelle Desk d'ingestion
extension du Job Backfill
Ces éléments appartiennent à 0.3.14+ ou 0.3.16 selon la roadmap.
8. Contraintes sécurité/API/architecture spécifiques
La convergence multi-source doit rester bornée :
aucune Vec/Map de pending non bornée
aucun task spawn non détenu
aucun retry loop Worker redondant avec Transport
aucune queue par provider sans borne explicite
aucun drop silencieux sous saturation
aucun changement de source qui efface une provenance déjà acquise
La sémantique de conflit reste :
même identité + même canonical RAW
-> idempotence
-> observation supplémentaire si sa clé est distincte
même identité + canonical RAW divergent
-> content conflict explicite
-> arrêt/fault selon contrat Worker existant
Le tracing ne doit jamais inclure :
signature brute
transaction/meta bytes
logs provider
URL endpoint
API key/x-token
filtres Helius sensibles
remote error text non borné
Toute surface publique ajoutée doit être justifiée par un consumer réel. Préférer les types privés/crate-private et les snapshots source-neutral aux DTO provider-specific publics.
9. Première mission pre.001 — audit/sizing obligatoire
pre.001 doit produire avant toute implémentation lourde :
- vérification exacte de la base stable
v0.3.12et dedeltas/0.3.12/rel.001.md; - lecture complète des sources internes listées ci-dessus ;
- inventaire exact des acteurs/sessions/facades WS standard, Helius et HTTP existants ;
- audit externe courant Solana/Helius et versions de crates réellement concernées ;
- matrice par source : signal/material, RAW-direct ou hydration, provenance, reconnect, network, tier/preuve live ;
- architecture cible de
RawTransactionIngestRuntimeResourcesmulti-source sans Worker -> Config ; - stratégie de source identity, source lifecycle et agrégation health ;
- stratégie de coalescence cross-source et de production d'observations multiples ;
- stratégie HTTP polling live bornée depuis le démarrage du run, sans campagne historique ;
- threat model : duplicate storms, source skew, provider disagreement, hydration fanout, reconnect storms, polling drift, slow Store, stop/fault concurrent ;
- inventaire des smokes réellement accessibles avec les ressources opérateur ;
- graphes Cargo/features cibles et éventuels changements Config strictement nécessaires ;
- sizing de chaque tranche sous le budget 15–20 minutes ;
- décision explicite : maintien de
0.3.13ou rescission avant codage ; - création du plan et de la validation de release.
Documents attendus :
docs/plans/034-V0_3_13_MULTI_SOURCE_LIVE_CONVERGENCE_PLAN.md
docs/validation/030-V0_3_13_MULTI_SOURCE_LIVE_CONVERGENCE.md
Critère de sortie : chaque source retenue et la convergence doivent avoir un contrat d'entrée/sortie, des bornes, une stratégie de preuve et un propriétaire de retry/reconnect clairement identifiés avant pre.002.
10. Prévision souple initiale des prereleases
Cette prévision est un point de départ à recalibrer par pre.001.
pre.001 — audit / brainstorming / sizing
Base stable, audit WS/Helius/HTTP courant, matrice de matériau/hydration, architecture multi-source, threat model, smokes, graphes, plan/validation et décision de maintien/rescission.
pre.002 — contrat runtime resources multi-source
Généraliser la composition caller-owned vers plusieurs sources bornées, avec identité interne/source lifecycle minimale, sans brancher encore toutes les voies live.
pre.003 — WS standard logsSubscribe + hydration
Brancher la discovery signature/logs via la façade Transport existante et fermer logs -> getTransaction observed -> Common RAW sans recopier l'actor WS.
pre.004 — WS standard blockSubscribe
Brancher les blocs full/base64 et utiliser RAW-direct uniquement pour les versions réellement qualifiées ; hydration/fault explicite ailleurs.
pre.005 — Helius transactionSubscribe
Réutiliser la surface Transport Helius existante, appliquer l'hydration nécessaire et les profils Config réellement justifiés sans SDK ni secret dans le Worker.
pre.006 — HTTP live block polling
Suivre le réseau depuis une borne de run explicite, récupérer les blocs observed et projeter leurs transactions vers le pipeline central avec cadence/bornes/stop déterministes.
pre.007 — supervision/source inventory multi-source
Faire coexister plusieurs sources dans le supervisor, avec ownership clair des tasks, stop/fault et source health sans modifier la sémantique Worker globale arbitrairement.
pre.008 — convergence et observations multiples
Fermer la déduplication/coalescence cross-source et la conservation de provenances/observations distinctes pour une même identité canonique.
pre.009 — conflits, backpressure et fairness
Durcir disagreement cross-source, content conflict, saturation globale/par source, fairness minimale et absence de fanout d'hydration non borné.
pre.010 — snapshots/health multi-source
Projeter uniquement les dimensions source-neutral réellement utiles : activité, source failures, backpressure et état agrégé sans exposer provider material.
pre.011 — races/shutdown hardening
Stop/fault pendant connect/resubscribe/hydration/polling/persistence, sources lentes, tasks orphelines, counters et ordre terminal.
pre.012 — completeness/security cross-layer
Canaris Transport -> Worker -> Common RAW -> Store, inventaires API/dépendances, redaction, Legacy/V0/V1 et non-régression Yellowstone.
pre.013 — gate technique/live
Workspace complet, Clippy strict, suites ciblées, graphes/duplicates et smokes réellement accessibles. Aucun nouveau scope.
pre.014 — réconciliation documentaire
README/USAGE, plan, validation et architectures/références réellement affectées. Pas de CHANGELOG/ROADMAP/prompt suivant.
pre.015 — préparation publication
Prompt 0.3.14, CHANGELOG, ROADMAP et fichiers mécaniques uniquement.
rel.001
Publication stable mécanique après gate validé.
Le forecast peut être allongé par des fixes/tranches dédiées ; il ne doit jamais être compressé en mélangeant les responsabilités de fermeture.
11. Versionnement, deltas, commits et tags
Règles obligatoires :
livraison prerelease : 0.3.13-pre.NNN
Cargo : 0.3.13-pre.N
fix : 0.3.13-pre.N.fix.M
delta : deltas/0.3.13/pre.NNN.md ou pre.NNN-fix.NNN.md
commit : v0.3.13-pre.NNN[-fix.NNN]
tag prerelease : aucun
tag stable final : v0.3.13 seulement après rel.001 validée
Toute prerelease non-fix synchronise workspace.package.version, même documentaire. Une correction strictement doc-only portée par un fix ne bump pas la version Cargo racine. Tout fichier modifié incrémente son header de version selon les règles du dépôt.
Les archives d'échange restent des deltas minimaux.
12. Procédure d'application et validation opérateur
Après application d'un delta technique :
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
Puis exécuter les tests ciblés de la tranche. Si un gate devient rouge, produire un fix strictement rattaché à la responsabilité fautive avant d'avancer.
Aucune commande non exécutée ne peut être déclarée PASS.
13. Validations Rust / Transport / Config / live / graphes pertinentes
Selon les couches modifiées :
cargo test -p ksp-worker-raw-transaction-ingest-lib
cargo test -p ksp-onchain-transport-lib
cargo test -p ksp-raw-transaction-lib
cargo test -p ksp-store-api
cargo test -p ksp-store-lib --no-default-features
Si Config/profils Helius sont modifiés :
cargo test -p ksp-config-lib
Graphes à maintenir/auditer :
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
À la fermeture technique :
cargo test --workspace --all-targets --all-features
Smokes live possibles, uniquement après audit pre.001 et lorsqu'ils sont réellement configurés :
Solana HTTP Devnet
Solana WS Devnet
Helius transactionSubscribe si credential/tier disponible
provider WS/blockSubscribe réellement accessible
HTTP polling live sur réseau de test approprié
Un smoke indisponible est NON EXÉCUTÉ, pas PASS. Aucun secret n'est écrit dans une commande persistée, un log, un delta ou un fichier source.
14. Critères de clôture de 0.3.13
La release peut se fermer lorsque :
base Yellowstone 0.3.12 non régressée
runtime resources supporte les sources retenues de manière bornée
logsSubscribe + hydration productif
blockSubscribe productif sur les versions réellement qualifiées
Helius transactionSubscribe productif si retenu/accessible par pre.001
HTTP live polling productif et run-local
sources simultanées convergent vers la même admission/persistence
observations multiples conservées sans dupliquer l'identité RawTransaction
content conflict reste explicite
coalescence/hydration fanout/backpressure bornés
aucun second actor/client Transport dans le Worker
aucun Worker -> Config/Job/backend physique
retry/reconnect restent possédés par la couche appropriée
shutdown/fault multi-source sans tâches orphelines
diagnostics redacted
fixtures/canaris cross-layer verts
smokes accessibles exécutés ou impossibilité qualifiée
gates workspace/clippy/tests/trees verts
documentation réconciliée
prompt 0.3.14 produit dans la dernière prerelease
15. Release suivante envisagée
0.3.14 doit reprendre uniquement après publication stable de 0.3.13 et fermer le gap repair/hardening multi-source :
replay natif lorsqu'il est réellement adressable
source redondante comme preuve/couverture de gap
scan HTTP blocs pour réparation
hydration des références manquantes
unresolved gaps explicitement observables
politiques degraded/unhealthy/faulted
shutdown pendant repair
smokes provider accessibles
EARLY uniquement si réellement prouvé et encore justifié
0.3.14 ne doit toujours pas transformer le Worker en moteur de campagne historique paramétrée ; le Backfill reste indépendant.
16. Instruction d'ouverture
Au début de la prochaine session :
- vérifier que la base correspond exactement au tag stable
v0.3.12et quedeltas/0.3.12/rel.001.mdest présent ; - lire les règles, le handoff
0.3.12, l'architecture RAW acquisition et les sources Worker/Transport/Common/Store/Config avant toute modification ; - réauditer les surfaces Solana WS, Helius et HTTP actuelles ainsi que les tiers/versions réellement concernés ;
- produire
0.3.13-pre.001avec matrice source/material/hydration, architecture multi-source, threat model, sizing, plan034et validation030; - ne pas généraliser runtime resources, ne pas brancher
logsSubscribe/blockSubscribe/Helius, ne pas ajouter de polling et ne pas modifier Config avant fermeture de ce gate ; - rescinder
0.3.13immédiatement si le périmètre réel n'est pas clôturable dans une seule session.