khadhroony-solana-project/deltas/0.2.8/pre.005.md

<!-- file: deltas/0.2.8/pre.005.md -->
<!-- version: 1 -->

# Delta `0.2.8-pre.005` — contrat typed Helius `transactionSubscribe`

## 1. Objet

Cette tranche matérialise le contrat de requête Helius LaserStream WebSocket `transactionSubscribe` : filtres, options, `tokenAccounts`, validations déterministes, acknowledgement numérique et wire `transactionUnsubscribe`.

Elle ne publie volontairement **pas encore** de handle live transaction : `transactionNotification`, le registry actor, les remaps de remote IDs et les races reconnect/unsubscribe doivent arriver atomiquement en `pre.006` afin de ne jamais exposer un abonnement public incapable de livrer correctement ses notifications.

Le checkpoint opérateur de `pre.004-fix.002` est intégralement vert.

Version workspace :

```text
0.2.8-pre.5
```

Livraison / commit attendu :

```text
0.2.8-pre.005
v0.2.8-pre.005
```

Aucun tag prerelease.

## 2. Audit Helius courant verrouillé

La documentation Helius relue le 2026-08-23 confirme pour `transactionSubscribe` :

```text
filter.vote                  bool optionnel
filter.failed                bool optionnel
filter.signature             signature exacte optionnelle
filter.accountInclude        liste OR, <= 50_000 adresses
filter.accountExclude        liste d'exclusion, <= 50_000 adresses
filter.accountRequired       liste AND, <= 50_000 adresses
filter.tokenAccounts         none | balanceChanged | all

options.commitment           processed | confirmed | finalized
options.encoding             base58 | base64 | jsonParsed
options.transactionDetails   full | signatures | accounts | none
options.showRewards          bool optionnel
options.maxSupportedTransactionVersion
                             requis pour transactionDetails = accounts | full

subscribe result             integer subscription id
unsubscribe params           [subscriptionId]
unsubscribe result           bool
late notifications           possibles brièvement après unsubscribe
```

`tokenAccounts = none` est équivalent à l'omission du champ. `balanceChanged` et `all` étendent le matching d'un `accountInclude` wallet aux token accounts qu'il possède selon les règles Helius documentées.

## 3. Contrat public typed

Nouveau module ciblé :

```text
crates/ksp-onchain-transport-lib/src/ws_helius_transactions.rs
```

Il publie depuis le crate-root :

```text
HeliusTokenAccountsFilter
HeliusTransactionSubscribeEncoding
HeliusTransactionSubscribeFilter
HeliusTransactionSubscribeOptions
HeliusTransactionSubscribeRequest
```

Le contrat réutilise les types KSP existants lorsqu'ils sont wire-identiques :

```text
commitment          -> SolanaCommitment
transactionDetails  -> SolanaTransactionDetails
account filters     -> ksp_core_lib::Pubkey
```

Aucun DTO Solana commun n'est recopié sous un nom Helius sans nécessité wire.

## 4. Sémantique des filtres et options

`HeliusTransactionSubscribeFilter` conserve explicitement la différence entre :

```text
champ omis
liste présente mais vide []
liste présente avec valeurs
```

pour `accountInclude`, `accountExclude` et `accountRequired`.

Chaque liste est validée indépendamment avec la limite Helius :

```text
0 ..= 50_000  accepté
50_001         rejeté avant I/O
```

Les erreurs déterministes n'incluent aucune signature ni adresse du filtre ; elles transportent uniquement le nom du champ et les cardinalités sûres.

`HeliusTransactionSubscribeOptions` impose avant I/O :

```text
transactionDetails = full      -> maxSupportedTransactionVersion requis
transactionDetails = accounts  -> maxSupportedTransactionVersion requis
transactionDetails = signatures -> version optionnelle
transactionDetails = none       -> version optionnelle
```

La distinction suivante est préservée sur le wire :

```text
options = None           -> params = [filter]
options = Some(default)  -> params = [filter, {}]
```

## 5. Wire subscribe/unsubscribe préparé

Les helpers crate-private préparés pour l'intégration actor de `pre.006` verrouillent :

```text
transactionSubscribe
transactionUnsubscribe
subscribe result integer -> u64
unsubscribe params        -> [remote_subscription_id]
unsubscribe result        -> bool
```

Les décodeurs refusent les formes de réponse d'un type différent au lieu de les coercer.

Ces helpers restent crate-private : aucun raw provider-extension API public n'est introduit.

## 6. Réutilisation du moteur physique

Une fixture locale passe réellement :

```text
HeliusLaserStreamWsSession
  -> physical_session() crate-private
  -> WsSession::execute_json_rpc
  -> actor/socket unique existant
  -> transactionSubscribe
  -> transactionUnsubscribe
```

Elle vérifie les méthodes, params, acknowledgements et résultat d'unsubscribe exacts contre un peer WebSocket local.

Aucun second :

```text
actor
socket
pending map
reconnect loop
subscription engine
```

n'est ajouté.

## 7. Sécurité et surface différée

`Debug` pour le filtre/requête expose seulement des indicateurs, modes et cardinalités ; il ne rend ni la signature exacte ni les valeurs des comptes filtrés.

`HeliusLaserStreamWsSession` n'expose toujours pas :

```text
pub async fn transaction_subscribe(...)
```

Cette absence est verrouillée par release-completeness. Le handle live arrive en `pre.006` avec :

```text
transactionNotification
registry local/remote
reconnect + resubscribe
unsubscribe races
late notifications
backpressure ciblée
```

Le heartbeat Helius reste réservé à `pre.007`.

## 8. Canaries et non-régressions

Les nouveaux tests couvrent :

```text
strings wire exactes tokenAccounts/encoding
serialization complète filtre/options
omission vs [] explicite
borne 50_000 / rejet 50_001 pour les trois listes
règle conditionnelle maxSupportedTransactionVersion
ack subscribe numérique strict
wire/result unsubscribe strict
Debug sans signature/adresses
round-trip local via actor physique partagé
public API des nouveaux types
absence du live handle avant pre.006
```

Les surfaces acquises restent inchangées :

```text
SolanaStandardWsSession       9 familles standard
HeliusLaserStreamWsSession    6 familles standard supportées
HTTP                          52 current + 14 historiques
Config Helius                 mainnet + devnet, secret/redaction/provenance validés
```

Aucune nouvelle dépendance Rust n'est ajoutée.

## 9. Preuve opérateur héritée

Le checkpoint `pre.004-fix.002` fourni le 2026-08-23 est intégralement vert :

```text
cargo fmt --all                                OK
python3 scripts/audit_rust_workspace_rules.py  clean
cargo check --workspace                        OK
cargo clippy --workspace --all-targets         OK
cargo test -p ksp-config-lib                   OK 110/110 + ownership/public API
cargo test -p ksp-onchain-transport-lib        OK 314 unit + 38 public + 26 completeness + 4 doctests
cargo test --workspace                         OK
```

`pre.004`, `pre.004-fix.001` et `pre.004-fix.002` sont donc `DONE` avant cette tranche.

## 10. Fichiers de la livraison

Nouveaux :

```text
crates/ksp-onchain-transport-lib/src/ws_helius_transactions.rs
crates/ksp-onchain-transport-lib/unit_tests/ws_helius_transactions.rs
deltas/0.2.8/pre.005.md
```

Modifiés :

```text
Cargo.toml
crates/ksp-onchain-transport-lib/src/lib.rs
crates/ksp-onchain-transport-lib/src/ws_protocol_session.rs
crates/ksp-onchain-transport-lib/tests/public_api.rs
crates/ksp-onchain-transport-lib/tests/release_completeness.rs
docs/plans/015-V0_2_8_HELIUS_LASERSTREAM_WEBSOCKET_PLAN.md
docs/validation/011-V0_2_8_HELIUS_LASERSTREAM_WEBSOCKET.md
```

Aucun fichier Config, schema, `.env`, README/USAGE, ROADMAP ou CHANGELOG n'est modifié.

## 11. Validation de préparation et gate opérateur

Validation statique disponible dans le sandbox 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
```

Le sandbox ne fournit pas Cargo/rustfmt ; la tranche reste donc `PREPARED` jusqu'au checkpoint opérateur suivant :

```bash
cargo fmt --all
python3 scripts/audit_rust_workspace_rules.py
cargo check --workspace
cargo clippy --workspace --all-targets
cargo test -p ksp-onchain-transport-lib
cargo test --workspace
```