285 lines
8.4 KiB
Markdown
285 lines
8.4 KiB
Markdown
<!-- file: deltas/0.2.9/pre.011.md -->
|
|
<!-- version: 1 -->
|
|
|
|
# Delta `0.2.9-pre.011` — Config Transport V3 + PublicNode Mainnet + consolidation documentaire
|
|
|
|
## 1. Base et version
|
|
|
|
Base immédiate :
|
|
|
|
```text
|
|
0.2.9-pre.010-fix.001
|
|
Cargo workspace = 0.2.9-pre.10.fix.1
|
|
```
|
|
|
|
Version candidate :
|
|
|
|
```text
|
|
0.2.9-pre.011
|
|
Cargo workspace = 0.2.9-pre.11
|
|
```
|
|
|
|
Le gate opérateur fourni pour `pre.010-fix.001` est entièrement vert : fmt/audit/check/Clippy sans warning, Transport 383 unit + 49 public API + 43 release-completeness + 4 doctests, dependency canary 3/3 et `cargo test --workspace` PASS.
|
|
|
|
## 2. Objet
|
|
|
|
Cette tranche matérialise la frontière Config décidée par `pre.001` puis différée jusqu'après le lifecycle/reconnect Yellowstone :
|
|
|
|
```text
|
|
std.transport V3
|
|
Config -> YellowstoneGrpcTransportSettings
|
|
provider et protocol distincts
|
|
metadata publique et secrète avec provenance contrôlée
|
|
premier profil PublicNode Mainnet standard
|
|
backward V1/V2 strict
|
|
```
|
|
|
|
Elle profite aussi du changement de phase de la release pour remettre le plan `016` et la validation `012` dans un état maintenable. Les détails historiques ne sont pas supprimés : ils restent dans les deltas immuables `deltas/0.2.9/`.
|
|
|
|
## 3. Config Transport V3
|
|
|
|
### 3.1 Schema
|
|
|
|
`config/schemas/std.transport.schema.json` devient `urn:ksp:schema:std.transport:v3` et conserve trois branches strictes :
|
|
|
|
```text
|
|
V1 = HTTP-only
|
|
V2 = HTTP + WebSocket
|
|
V3 = HTTP + WebSocket + Yellowstone gRPC optionnel par profil
|
|
```
|
|
|
|
V3 ajoute :
|
|
|
|
```text
|
|
grpc_defaults
|
|
grpc_endpoints[]?
|
|
```
|
|
|
|
`grpc_defaults` mappe uniquement des knobs déjà possédés par `YellowstoneGrpcSessionSettings` : timeouts, reconnect, channel capacities et max message sizes. Les bounds des filtres Subscribe restent un contrat Transport et ne sont pas transformés en configuration arbitraire.
|
|
|
|
Chaque endpoint gRPC contient :
|
|
|
|
```text
|
|
name
|
|
enabled
|
|
provider
|
|
cluster
|
|
protocol = solana_yellowstone
|
|
url
|
|
metadata[]?
|
|
secret_metadata[]?
|
|
session?
|
|
```
|
|
|
|
### 3.2 Mapping Config -> Transport
|
|
|
|
`ResolvedTransportConfig` ajoute :
|
|
|
|
```text
|
|
grpc_settings()
|
|
into_all_transport_settings()
|
|
```
|
|
|
|
L'accesseur historique suivant est volontairement inchangé :
|
|
|
|
```text
|
|
into_transport_settings() -> (HttpTransportSettings, Option<WsTransportSettings>)
|
|
```
|
|
|
|
Cela évite une rupture source silencieuse des consumers V2.
|
|
|
|
V1 et V2 retournent toujours `None` pour gRPC. Un profil V3 qui n'a pas de `grpc_endpoints` retourne également `None` au lieu d'inventer un Transport gRPC vide.
|
|
|
|
### 3.3 Protocol vs provider
|
|
|
|
Config exige actuellement :
|
|
|
|
```text
|
|
protocol = solana_yellowstone
|
|
```
|
|
|
|
Le champ `provider` reste descriptif et mappe vers `YellowstoneGrpcProviderName`.
|
|
|
|
Donc :
|
|
|
|
```text
|
|
PublicNode != protocole
|
|
PublicNode != nouvelle façade Transport
|
|
PublicNode = environnement d'exécution du standard Yellowstone
|
|
```
|
|
|
|
Toute future divergence provider doit rester un delta N3 explicite.
|
|
|
|
### 3.4 Metadata et provenance
|
|
|
|
Deux classes sont matérialisées :
|
|
|
|
```text
|
|
metadata
|
|
secret_metadata
|
|
```
|
|
|
|
Règles avant mapping :
|
|
|
|
```text
|
|
metadata + provenance KSP_SECRET_*/KSPB_SECRET_* -> reject
|
|
secret_metadata sans provenance secret -> reject
|
|
secret_metadata + provenance non-secret env -> reject
|
|
secret_metadata + provenance secret -> accept
|
|
```
|
|
|
|
Les segments littéraux autour d'un placeholder secret restent permis. Config possède la provenance et la projection sûre ; Transport reçoit ensuite seulement les `YellowstoneGrpcMetadataEntry` déjà classifiées.
|
|
|
|
Aucun nom d'environnement n'est lu dans Transport.
|
|
|
|
## 4. Profil PublicNode Mainnet
|
|
|
|
La surface publique réauditée le 2026-08-24 confirme Yellowstone gRPC Solana Mainnet et affiche :
|
|
|
|
```text
|
|
solana-yellowstone-grpc.publicnode.com:443
|
|
```
|
|
|
|
`YellowstoneGrpcEndpointUrl` exige une URL `http/https`; le document Config représente donc ce même endpoint TLS comme `https://solana-yellowstone-grpc.publicnode.com:443`.
|
|
|
|
Le document committé ajoute :
|
|
|
|
```text
|
|
profile_id = publicnode_mainnet
|
|
provider = publicnode
|
|
cluster = mainnet-beta
|
|
protocol = solana_yellowstone
|
|
metadata = aucune
|
|
```
|
|
|
|
Le profil générique `mainnet_public` reste distinct et ne reçoit pas implicitement un endpoint PublicNode.
|
|
|
|
PublicNode expose également Solana Testnet gRPC, mais le hostname exact n'a pas été obtenu depuis une source suffisamment autoritative/indexable pendant cette tranche. Aucun endpoint supposé n'est versionné. `pre.012` réaudite cette valeur avant tout profil/smoke Testnet.
|
|
|
|
## 5. Tests ajoutés/étendus
|
|
|
|
La fixture V3 couvre :
|
|
|
|
```text
|
|
mapping gRPC valide
|
|
merge grpc_defaults + session overrides
|
|
metadata publique issue de KSP_PUBLIC_*
|
|
secret_metadata issue de KSP_SECRET_*
|
|
safe_value avec segment secret redacted
|
|
rejet public <- secret
|
|
rejet secret <- public
|
|
```
|
|
|
|
Le config committé couvre le profil `publicnode_mainnet` et vérifie la construction d'un `YellowstoneGrpcTransportSettings` valide sans URL dans son `Debug`.
|
|
|
|
Le canari public API inclut les nouveaux accessors sans supprimer les anciens.
|
|
|
|
## 6. Consolidation plan/validation
|
|
|
|
`docs/plans/016-V0_2_9_YELLOWSTONE_GRPC_PLAN.md` et `docs/validation/012-V0_2_9_YELLOWSTONE_GRPC.md` sont réorganisés autour de :
|
|
|
|
```text
|
|
état courant
|
|
scope/architecture stabilisés
|
|
matrices protocole encore normatives
|
|
Config V3
|
|
PublicNode
|
|
lifecycle/replay
|
|
historique compact des gates fermés
|
|
forecast restant
|
|
critères de clôture
|
|
```
|
|
|
|
Les longues sections append-only propres à chaque prerelease sont remplacées par une table compacte renvoyant aux deltas immuables. Aucun delta historique n'est modifié.
|
|
|
|
Les tableaux Markdown sont reformattés selon la convention JetBrains RustRover utilisée dans le workspace : largeur calculée sur la cellule la plus large et un espace de padding autour du contenu.
|
|
|
|
## 7. Documentation Config synchronisée
|
|
|
|
La README et l'USAGE de `ksp-config-lib`, ainsi que les commentaires du registre, sont mis à jour pour ne plus présenter `std.transport` comme un document uniquement V2 HTTP + WebSocket.
|
|
|
|
La documentation finale spécifique Transport/Yellowstone reste un gate de `pre.012`.
|
|
|
|
## 8. Fichiers modifiés/ajoutés
|
|
|
|
```text
|
|
Cargo.toml
|
|
config/std.transport.json
|
|
config/schemas/std.transport.schema.json
|
|
crates/ksp-config-lib/README.md
|
|
crates/ksp-config-lib/USAGE.md
|
|
crates/ksp-config-lib/src/lib.rs
|
|
crates/ksp-config-lib/src/registry.rs
|
|
crates/ksp-config-lib/src/transport.rs
|
|
crates/ksp-config-lib/tests/public_api.rs
|
|
crates/ksp-config-lib/unit_tests/transport.rs
|
|
crates/ksp-config-lib/unit_tests/fixtures_v3/std.transport.json
|
|
docs/plans/016-V0_2_9_YELLOWSTONE_GRPC_PLAN.md
|
|
docs/validation/012-V0_2_9_YELLOWSTONE_GRPC.md
|
|
deltas/0.2.9/pre.011.md
|
|
```
|
|
|
|
Aucune dépendance Cargo n'est ajoutée ou modifiée.
|
|
|
|
## 9. Validation source disponible avant livraison
|
|
|
|
Exécuté dans l'environnement de préparation :
|
|
|
|
```text
|
|
python3 scripts/audit_rust_workspace_rules.py
|
|
General Rust rule audit: clean
|
|
Rust export completeness audit: 0 candidate(s)
|
|
KSP workspace Rust rule audit: clean
|
|
|
|
JSON Schema Draft 2020-12 meta-validation: PASS
|
|
config/std.transport.json against V3 schema: PASS
|
|
fixture V2 against V3 schema: PASS
|
|
fixture V1 against V3 schema: PASS
|
|
fixture V3 against V3 schema: PASS
|
|
```
|
|
|
|
Cargo/Rustfmt ne sont pas disponibles dans l'environnement de préparation. Aucune compilation ou test Cargo n'est donc déclaré réussi pour `pre.011` avant gate opérateur.
|
|
|
|
## 10. Gate opérateur requis
|
|
|
|
```bash
|
|
cargo fmt --all
|
|
python3 scripts/audit_rust_workspace_rules.py
|
|
cargo check --workspace
|
|
cargo clippy --workspace --all-targets
|
|
cargo test -p ksp-config-lib
|
|
cargo test -p ksp-config-lib --test public_api
|
|
cargo test -p ksp-config-lib --test ownership
|
|
cargo test -p ksp-onchain-transport-lib
|
|
cargo test -p ksp-core-lib --test workspace_dependencies
|
|
cargo test --workspace
|
|
```
|
|
|
|
Attentes de candidate :
|
|
|
|
```text
|
|
Config unit 113 attendus (110 baseline + 3 V3)
|
|
Config public API 15 attendus
|
|
Config ownership 5 attendus
|
|
Transport unit >= 383
|
|
Transport public API >= 49
|
|
Transport completeness >= 43
|
|
Transport doctests 4
|
|
workspace dependencies 3
|
|
Clippy aucun warning
|
|
workspace PASS
|
|
```
|
|
|
|
Ces valeurs ne deviennent des résultats qu'après exécution opérateur.
|
|
|
|
## 11. Suite
|
|
|
|
Après fermeture de `pre.011` :
|
|
|
|
```text
|
|
pre.012 PublicNode live + Testnet endpoint re-audit + compliance finale + cargo graphs + docs/prompt suivant
|
|
rel.001 publication stable stricte
|
|
```
|
|
|
|
Si `pre.012` ne peut pas fermer proprement tous les gates dans une seule tranche, continuer avec `pre.013+` plutôt que compacter artificiellement la clôture.
|