diff --git a/Cargo.toml b/Cargo.toml index e60f672..52136ab 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,12 +1,12 @@ # file: Cargo.toml -# version: 480 +# version: 481 [workspace] resolver = "3" members = ["crates/ksp-app-backfill-desk", "crates/ksp-app-config-desk", "crates/ksp-app-solprices-desk", "crates/ksp-app-store-desk", "crates/ksp-app-wallet-desk", "crates/ksp-config-lib", "crates/ksp-core-lib", "crates/ksp-interface-lib", "crates/ksp-job-api", "crates/ksp-job-backfill-lib", "crates/ksp-logging-lib", "crates/ksp-offchain-transport-lib", "crates/ksp-onchain-transport-lib", "crates/ksp-program-api", "crates/ksp-store-api", "crates/ksp-store-lib", "crates/ksp-store-postgres-lib", "crates/ksp-wallet-lib", "crates/ksp-worker-api"] [workspace.package] -version = "0.3.9-pre.3" +version = "0.3.9-pre.4" edition = "2024" license = "MIT" repository = "https://git.sasedev.com/Sasedev/khadhroony-solana-project" diff --git a/deltas/0.3.9/pre.004.md b/deltas/0.3.9/pre.004.md new file mode 100644 index 0000000..1f6a875 --- /dev/null +++ b/deltas/0.3.9/pre.004.md @@ -0,0 +1,60 @@ + + + +# Delta `0.3.9-pre.004` + +## 1. Objet + +Fermer l'audit RAW A après freeze effective de `ksp-worker-api` : Solana standard HTTP/WS, inventaire KSP Transport/Store/Config, taxonomie de capabilities et premiers gaps préparatoires pour `0.3.10`/`0.3.12`. + +Aucun runtime, DTO Transport, Store model, Config profile ou Worker API n'est modifié. + +## 2. Base et version + +Base opérateur : `0.3.9-pre.3`, dont le gate Worker est PASS. + +```text +workspace.package.version = 0.3.9-pre.4 +``` + +## 3. Décisions + +```text +getSignaturesForAddress + getTransaction -> history/catch-up/repair adressé +getBlocks/getBlocksWithLimit + getBlock -> catch-up/gap repair global sous gap provenance +logsSubscribe -> live discovery + hydration +signatureSubscribe -> confirmation ciblée, pas discovery +blockSubscribe -> direct full sous capability explicite, méthode instable +slot/ledger methods -> auxiliaires de continuité +reconnect WS -> jamais assimilé à replay +mainnet-beta -> identité réseau durable canonique +``` + +## 4. Gaps ouverts, non implémentés + +- `get_block_observed` ou équivalent nécessaire si la voie bloc multi-endpoint est admise en V1 ; +- extraction/canonicalisation transaction-par-transaction depuis un bloc à définir ; +- canonicalizer RAW v1 actuellement owned par Backfill à rendre réutilisable sans dépendance Worker -> Job ni duplication ; +- gap repair explicite requis après reconnexion/overflow WS ; +- Config future à exprimer par capabilities/rôles et non enum de protocole ; +- cohérence `mainnet` profile alias / `mainnet-beta` durable à préserver. + +## 5. Fichiers + +| Fichier | Action | Rôle | +|----------------------------------------------------------------|--------|---------------------------------------| +| Cargo.toml | MOD | workspace `0.3.9-pre.4` | +| docs/000-README.md | MOD | indexe l’architecture RAW | +| docs/architecture/000-README.md | MOD | ajoute le document 011 | +| docs/architecture/011-RAW_TRANSACTION_ACQUISITION.md | ADD | audit standard + taxonomie + gaps | +| docs/plans/030-V0_3_9_WORKER_API_RAW_TRANSACTION_AUDIT_PLAN.md | MOD | freeze pre.003 + réalisation pre.004 | +| docs/validation/026-V0_3_9_WORKER_API_RAW_TRANSACTION_AUDIT.md | MOD | preuves opérateur + checklist pre.004 | +| deltas/0.3.9/pre.004.md | ADD | présent delta | + +## 6. Sources externes + +Documentation RPC Solana officielle consultée le 4 septembre 2026. Les liens exacts sont conservés dans `docs/architecture/011-RAW_TRANSACTION_ACQUISITION.md`. Les providers, quotas, Helius, Yellowstone et kbot3 restent réservés à `pre.005`. + +## 7. Gates + +Les audits Python sont exécutés après assemblage. Les gates Cargo de cette tranche restent à exécuter par l'opérateur ; le changement Rust se limite au metadata de version workspace. diff --git a/docs/000-README.md b/docs/000-README.md index b906801..7e98d75 100644 --- a/docs/000-README.md +++ b/docs/000-README.md @@ -1,5 +1,5 @@ - + # Documentation KSP @@ -30,7 +30,8 @@ docs/ │ ├── 007-EXECUTION_AND_POLICY.md │ ├── 008-DATA_MATERIALIZATION_AND_STORE.md │ ├── 009-ACQUISITION_WORKERS_AND_JOBS.md -│ └── 010-APPS_SERVICES_SCENARIOS_AND_CONTROL.md +│ ├── 010-APPS_SERVICES_SCENARIOS_AND_CONTROL.md +│ └── 011-RAW_TRANSACTION_ACQUISITION.md ├── formats/ │ ├── 000-README.md │ ├── KSPWALLET_V1.md @@ -107,6 +108,10 @@ docs/ D'autres sous-répertoires seront ajoutés uniquement lorsque leur rôle aura été décidé, notamment pour les références, décisions, guides et validations. +## Audit d'acquisition RAW Transaction + +La taxonomie durable des rôles d'acquisition `RawTransaction`, les audits datés de protocoles/providers et les gaps préparatoires pour les workers/backfills sont centralisés dans [`architecture/011-RAW_TRANSACTION_ACQUISITION.md`](architecture/011-RAW_TRANSACTION_ACQUISITION.md). + ## Documents de planification Le plan historique de la phase fondatrice clôturée est conservé dans [`plans/001-V0_0_3_PLAN.md`](plans/001-V0_0_3_PLAN.md). La séquence active des premières releases fonctionnelles est définie dans [`plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md`](plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md). Le plan détaillé de la release stable `0.1.1` est conservé comme historique clôturé dans [`plans/003-V0_1_1_CORE_FOUNDATION_PLAN.md`](plans/003-V0_1_1_CORE_FOUNDATION_PLAN.md). Le plan détaillé de la release stable `0.1.2` est conservé comme historique clôturé dans [`plans/004-V0_1_2_LOGGING_FOUNDATION_PLAN.md`](plans/004-V0_1_2_LOGGING_FOUNDATION_PLAN.md). Le plan détaillé de la release stable `0.1.3 — Configuration foundation` est conservé comme historique clôturé dans [`plans/005-V0_1_3_CONFIG_FOUNDATION_PLAN.md`](plans/005-V0_1_3_CONFIG_FOUNDATION_PLAN.md). Le plan détaillé de la release stable `0.1.4 — ksp-app-config-desk` est conservé comme historique clôturé dans [`plans/006-V0_1_4_CONFIG_DESKTOP_PLAN.md`](plans/006-V0_1_4_CONFIG_DESKTOP_PLAN.md), avec sa matrice finale [`validation/001-V0_1_4_CONFIG_DESKTOP.md`](validation/001-V0_1_4_CONFIG_DESKTOP.md). Son prompt d'ouverture historique reste [`../prompts/004-V0_1_4_START_PROMPT.md`](../prompts/004-V0_1_4_START_PROMPT.md). La release stable `0.2.0` clôt l'audit de bot3 et le découpage de la série. Son plan directeur est conservé comme historique clôturé dans [`plans/007-V0_2_0_SERIES_PLANNING.md`](plans/007-V0_2_0_SERIES_PLANNING.md), avec sa matrice finale [`validation/002-V0_2_0_SERIES_PLANNING.md`](validation/002-V0_2_0_SERIES_PLANNING.md). La release stable `0.2.1 — HTTP Solana foundation` a été ouverte par [`../prompts/006-V0_2_1_START_PROMPT.md`](../prompts/006-V0_2_1_START_PROMPT.md). Son gate de sizing et sa matrice exhaustive sont conservés dans [`plans/008-V0_2_1_ONCHAIN_HTTP_PLAN.md`](plans/008-V0_2_1_ONCHAIN_HTTP_PLAN.md), avec la validation finale [`validation/003-V0_2_1_ONCHAIN_HTTP.md`](validation/003-V0_2_1_ONCHAIN_HTTP.md), README/USAGE Transport et le smoke Devnet opt-in de composition Config -> Transport. Le prompt [`../prompts/007-V0_2_2_START_PROMPT.md`](../prompts/007-V0_2_2_START_PROMPT.md) a ouvert la release stable `0.2.2 — HTTP Accounts + Tokens + Cluster`. Son plan clôturé [`plans/009-V0_2_2_HTTP_ACCOUNTS_TOKENS_CLUSTER_PLAN.md`](plans/009-V0_2_2_HTTP_ACCOUNTS_TOKENS_CLUSTER_PLAN.md) conserve l'audit et l'implémentation des 22 wrappers typés, tandis que [`validation/004-V0_2_2_HTTP_ACCOUNTS_TOKENS_CLUSTER.md`](validation/004-V0_2_2_HTTP_ACCOUNTS_TOKENS_CLUSTER.md) enregistre les validations déterministes, les graphes Cargo et les deux smokes Devnet passés avant publication. Le prompt [`../prompts/008-V0_2_3_START_PROMPT.md`](../prompts/008-V0_2_3_START_PROMPT.md) a ouvert la release stable `0.2.3 — HTTP Transactions`. Son plan clôturé [`plans/010-V0_2_3_HTTP_TRANSACTIONS_PLAN.md`](plans/010-V0_2_3_HTTP_TRANSACTIONS_PLAN.md) conserve l'audit et l'implémentation des 11 wrappers ; le réaudit [`validation/005-V0_2_3_KSP_TRANSPORT_007_RETRO_AUDIT.md`](validation/005-V0_2_3_KSP_TRANSPORT_007_RETRO_AUDIT.md) confirme la complétude des 37 wrappers HTTP typés et [`validation/006-V0_2_3_HTTP_TRANSACTIONS.md`](validation/006-V0_2_3_HTTP_TRANSACTIONS.md) enregistre les validations finales, graphes Cargo et deux smokes Devnet passés avant publication. Le prompt [`../prompts/009-V0_2_4_START_PROMPT.md`](../prompts/009-V0_2_4_START_PROMPT.md) a ouvert la release stable `0.2.4 — HTTP Blocks + Economics + compliance HTTP finale`. Son plan clôturé [`plans/011-V0_2_4_HTTP_BLOCKS_ECONOMICS_PLAN.md`](plans/011-V0_2_4_HTTP_BLOCKS_ECONOMICS_PLAN.md) conserve l’implémentation des 15 wrappers et la compliance `52/52 + 14/14`; la matrice finale [`validation/007-V0_2_4_HTTP_FINAL_COMPLIANCE.md`](validation/007-V0_2_4_HTTP_FINAL_COMPLIANCE.md) enregistre le réaudit SIMD/inventaire, les canaries globales et les preuves opérateur avant publication. Le prompt [`../prompts/010-V0_2_5_START_PROMPT.md`](../prompts/010-V0_2_5_START_PROMPT.md), finalisé par `0.2.4-pre.009-fix.001`, ouvre `0.2.5 — Wallet foundation` sur la base stable `v0.2.4`. Son plan historique clôturé [`plans/012-V0_2_5_WALLET_FOUNDATION_PLAN.md`](plans/012-V0_2_5_WALLET_FOUNDATION_PLAN.md) part du gate `pre.001` (héritage, threat model offline, VIEW/OWNER indépendants et niveau B read-only), puis matérialise la crate en `pre.002`, le wire/transcript en `pre.003`, les primitives Argon2id/XChaCha20-Poly1305 en `pre.004`, les payloads/create/open en `pre.005`, la persistence en `pre.006`, l'administration/signature en `pre.007` et les adapters transfer en `pre.008`. `pre.009` ferme l'audit adversarial/interoperability/compliance dans [`validation/008-V0_2_5_WALLET_SECURITY_COMPLIANCE.md`](validation/008-V0_2_5_WALLET_SECURITY_COMPLIANCE.md) avant la documentation finale `pre.010` ; `pre.010` finalise [`../crates/ksp-wallet-lib/README.md`](../crates/ksp-wallet-lib/README.md), [`../crates/ksp-wallet-lib/USAGE.md`](../crates/ksp-wallet-lib/USAGE.md), la spec, les graphes et la matrice ; `pre.010-fix.001`–`fix.003` ferment ensuite la mise à niveau Dalek et la normalisation Rust/audit structurel. `0.2.5-rel.001` publie la release stable et [`../prompts/011-V0_2_6_START_PROMPT.md`](../prompts/011-V0_2_6_START_PROMPT.md) ouvre `0.2.6 — Wallet Desk`. Le gate `0.2.6-pre.001` est conservé dans [`plans/013-V0_2_6_WALLET_DESK_PLAN.md`](plans/013-V0_2_6_WALLET_DESK_PLAN.md) : il réaudite Config Desk et les APIs finales, retient le gabarit desktop, fixe `std.wallet`, la composition Config/Wallet/HTTP/Logging, les secrets `KSP_SECRET_WALLET_PASS_*`, les frontières VIEW/OWNER et la trajectoire de validation. `pre.002`–`pre.014` matérialisent ensuite le shell Tauri, Config Wallet/composite, inventory, create/open, balance HTTP, import/export, metadata, rotations, révocation VIEW forte, compliance et polish desktop. `pre.015` fige le wire binaire `.kspwallet` V2, `pre.016` matérialise les APIs génériques/versionnées et le runtime V2, puis `pre.017` ajoute la migration explicite OWNER-authentifiée V1 -> V2. `pre.018` ferme le runtime Tauri packagé Config/resources et la documentation candidate ; `pre.018-fix.001` corrige le canari d'ownership Config, après quoi le gate workspace et le build final Linux sont verts. `pre.018-fix.002` renforce uniquement le contrat de reprise `0.2.7`. `0.2.6-rel.001` publie cette surface stable et [`../prompts/012-V0_2_7_START_PROMPT.md`](../prompts/012-V0_2_7_START_PROMPT.md) devient le prochain point d'entrée. Le gate `0.2.7-pre.001` ouvre la release WebSocket standard dans [`plans/014-V0_2_7_ONCHAIN_WEBSOCKET_PLAN.md`](plans/014-V0_2_7_ONCHAIN_WEBSOCKET_PLAN.md) ; la matrice normative puis finale est conservée dans [`validation/010-V0_2_7_ONCHAIN_WEBSOCKET.md`](validation/010-V0_2_7_ONCHAIN_WEBSOCKET.md). `0.2.7-pre.014` ferme la candidate technique/documentaire après validation 18/18, smoke WebSocket Devnet et audit du graphe Cargo ; `pre.014-fix.001` renforce uniquement le prompt suivant. `0.2.7-rel.001` publie `0.2.7 — WebSocket Solana standard` stable et [`../prompts/013-V0_2_8_START_PROMPT.md`](../prompts/013-V0_2_8_START_PROMPT.md) ouvre `0.2.8 — Helius LaserStream WebSocket`. Le plan historique clôturé [`plans/015-V0_2_8_HELIUS_LASERSTREAM_WEBSOCKET_PLAN.md`](plans/015-V0_2_8_HELIUS_LASERSTREAM_WEBSOCKET_PLAN.md) et la matrice finale [`validation/011-V0_2_8_HELIUS_LASERSTREAM_WEBSOCKET.md`](validation/011-V0_2_8_HELIUS_LASERSTREAM_WEBSOCKET.md) conservent la release stable `0.2.8 — Helius LaserStream WebSocket` publiée par `rel.001` : protocol `helius_laserstream`, sept familles standard Helius (`account/logs/program/root/signature/slot/slotsUpdates`), extension `transactionSubscribe`/`transactionUnsubscribe`, `block/vote` absents, heartbeat Ping 60 s, Config/secrets redacted, lifecycle adversarial et graphes Cargo finaux validés. [`../prompts/014-V0_2_9_START_PROMPT.md`](../prompts/014-V0_2_9_START_PROMPT.md) devient le contrat actif pour ouvrir Yellowstone gRPC standard/provider-neutral depuis le tag stable `v0.2.8`. La release stable `0.2.9` est conservée dans [`plans/016-V0_2_9_YELLOWSTONE_GRPC_PLAN.md`](plans/016-V0_2_9_YELLOWSTONE_GRPC_PLAN.md) et [`validation/012-V0_2_9_YELLOWSTONE_GRPC.md`](validation/012-V0_2_9_YELLOWSTONE_GRPC.md) : stratégie proto Apache + client KSP/Tonic, moteur N1, standard N2, Config V3, profils PublicNode Mainnet/Testnet authentifiés par `x-token` secret et smoke live `Subscribe` validé sur les deux réseaux. La candidate `0.2.10 — OrbitFlare Yellowstone gRPC` est réconciliée dans [`plans/017-V0_2_10_ORBITFLARE_YELLOWSTONE_GRPC_PLAN.md`](plans/017-V0_2_10_ORBITFLARE_YELLOWSTONE_GRPC_PLAN.md) et [`validation/013-V0_2_10_ORBITFLARE_YELLOWSTONE_GRPC.md`](validation/013-V0_2_10_ORBITFLARE_YELLOWSTONE_GRPC.md) : Devnet `http://devnet.rpc.orbitflare.com:10000`, License Key `ORBIT-*` injectée comme metadata secrète `x-token`, Config Transport V3 inchangée, live `Subscribe -> Slot + Ping` passé, aucun overlay provider et aucun heartbeat supplémentaire. La candidate `0.2.11 — Off-chain price transport` est réconciliée dans [`plans/018-V0_2_11_OFFCHAIN_PRICE_TRANSPORT_PLAN.md`](plans/018-V0_2_11_OFFCHAIN_PRICE_TRANSPORT_PLAN.md) et [`validation/014-V0_2_11_OFFCHAIN_PRICE_TRANSPORT.md`](validation/014-V0_2_11_OFFCHAIN_PRICE_TRANSPORT.md) : SOL/USD V1, huit adapters REST sans SDK provider, décimal exact, registry/availability/rate limits possédés par Off-chain Transport, Config `std.offchain_transport`, refresh individuel/multiple provider-neutral et smoke live keyless final `7/7` après correction CoinMarketCap V2. [`../crates/ksp-offchain-transport-lib/README.md`](../crates/ksp-offchain-transport-lib/README.md) et [`../crates/ksp-offchain-transport-lib/USAGE.md`](../crates/ksp-offchain-transport-lib/USAGE.md) deviennent les références durables ; la future `ksp-app-solprices-desk` reste une HID sans logique provider. La release stable `0.2.12 — SOL Prices Desk + intégration prix Wallet Desk` est conservée dans [`plans/019-V0_2_12_SOL_PRICES_DESK_PLAN.md`](plans/019-V0_2_12_SOL_PRICES_DESK_PLAN.md) et [`validation/015-V0_2_12_SOL_PRICES_DESK.md`](validation/015-V0_2_12_SOL_PRICES_DESK.md) : `ksp-app-solprices-desk` fournit le refresh manuel row/selected/all provider-neutral, états/timestamps exacts et diagnostics sûrs sur ports 1434/1435 ; Wallet Desk réutilise `MarketPriceService::refresh_all` pendant le refresh balance pour afficher une moyenne SOL/USD consumer-owned et l'équivalent USD exact, sans provider concret ni fallback Off-chain. Les gates finaux workspace/live et les trois builds Tauri Linux sont verts avant publication. `0.2.13 — Interface / wire foundation` est réconciliée comme candidate dans [`plans/020-V0_2_13_INTERFACE_PLAN.md`](plans/020-V0_2_13_INTERFACE_PLAN.md) avec la matrice finale candidate [`validation/016-V0_2_13_INTERFACE.md`](validation/016-V0_2_13_INTERFACE.md) : `ksp-interface-lib` expose le `Pubkey` Core, `ProgramAccountMeta` et `ProgramInstruction`, bornés à `255` account metas et `10_240` bytes de data, avec façade crate-root exacte, diagnostics bornés, consumer externe et firewall `Interface -> Core` validés. Le gate technique final `pre.006` est intégralement vert ; [`../crates/ksp-interface-lib/README.md`](../crates/ksp-interface-lib/README.md) et [`../crates/ksp-interface-lib/USAGE.md`](../crates/ksp-interface-lib/USAGE.md) deviennent les références durables avant préparation de publication. Le prompt d’ouverture historique reste [`../prompts/018-V0_2_13_START_PROMPT.md`](../prompts/018-V0_2_13_START_PROMPT.md). `0.2.14 — Program API foundation` est réconciliée comme candidate dans [`plans/021-V0_2_14_PROGRAM_API_PLAN.md`](plans/021-V0_2_14_PROGRAM_API_PLAN.md) avec la matrice finale candidate [`validation/017-V0_2_14_PROGRAM_API.md`](validation/017-V0_2_14_PROGRAM_API.md) : `ksp-program-api` fournit une façade instruction-only ouverte, `ProgramInstructionRecognition`, `ProgramInstructionDecodeOutcome` et `ProgramInstructionDecoder`, avec output associé possédé par l’implémentation, Program Pubkeys opaques/non enregistrés acceptés, canari externe et firewall `Program API -> Core + Interface`. Le gate technique final `pre.006` est intégralement vert ; [`../crates/ksp-program-api/README.md`](../crates/ksp-program-api/README.md) et [`../crates/ksp-program-api/USAGE.md`](../crates/ksp-program-api/USAGE.md) deviennent les références durables avant préparation de publication. Le prompt d’ouverture historique reste [`../prompts/019-V0_2_14_START_PROMPT.md`](../prompts/019-V0_2_14_START_PROMPT.md). `0.3.1 — Store API RAW foundation` est réconciliée comme candidate dans [`plans/022-V0_3_1_STORE_RAW_PLAN.md`](plans/022-V0_3_1_STORE_RAW_PLAN.md) avec la matrice [`validation/018-V0_3_1_STORE_RAW.md`](validation/018-V0_3_1_STORE_RAW.md) : `ksp-store-api` reste Core-only et backend-agnostic, expose les modèles RAW transaction/account et observations, queries cursorisées, outcomes, capabilities fines et lifecycle de rétention/tombstone, sans backend runtime, PostgreSQL, processing ledger ni N2/N3/N4. Le gate `pre.008` a été reconstruit après `cargo clean` et validé sur le workspace complet et les trois builds Tauri ; `pre.009` réconcilie la documentation durable avant la préparation de publication `pre.010`. `0.3.2 — Store/PostgreSQL runtime foundation` est réconciliée comme candidate dans [`plans/023-V0_3_2_STORE_POSTGRES_FOUNDATION_PLAN.md`](plans/023-V0_3_2_STORE_POSTGRES_FOUNDATION_PLAN.md) avec la matrice finale [`validation/019-V0_3_2_STORE_POSTGRES_FOUNDATION.md`](validation/019-V0_3_2_STORE_POSTGRES_FOUNDATION.md) : `ksp-store-lib` fournit la façade runtime backend-neutral, `ksp-store-postgres-lib` possède le backend physique tokio-postgres/Deadpool/Rustls et les migrations metadata-only, tandis que `std.store` sélectionne des targets PostgreSQL séparés par réseau. Le gate technique `pre.010` valide workspace, graphes, trois builds Tauri et la fondation PostgreSQL réelle sur un serveur major 17 ; [`../crates/ksp-store-lib/README.md`](../crates/ksp-store-lib/README.md), [`../crates/ksp-store-lib/USAGE.md`](../crates/ksp-store-lib/USAGE.md), [`../crates/ksp-store-postgres-lib/README.md`](../crates/ksp-store-postgres-lib/README.md) et [`../crates/ksp-store-postgres-lib/USAGE.md`](../crates/ksp-store-postgres-lib/USAGE.md) deviennent les références durables avant la lane de publication. `0.3.3 — Store/PostgreSQL RawTransaction vertical slice` est réconciliée comme candidate dans [`plans/024-V0_3_3_STORE_POSTGRES_RAW_TRANSACTION_PLAN.md`](plans/024-V0_3_3_STORE_POSTGRES_RAW_TRANSACTION_PLAN.md) avec la matrice finale [`validation/020-V0_3_3_STORE_POSTGRES_RAW_TRANSACTION.md`](validation/020-V0_3_3_STORE_POSTGRES_RAW_TRANSACTION.md) : les six capabilities `RawTransaction*` sont implémentées côté backend et façade, V001 matérialise canonical/observations/archive avec binding réseau, navigation keyset et rétention atomique, et le gate final rejoue le workspace complet ainsi que le live PostgreSQL 17. `RawAccountState` physique reste réservé à `0.3.4`. `0.3.4 — Store/PostgreSQL RawAccountState` est conservée dans [`plans/025-V0_3_4_STORE_POSTGRES_RAW_ACCOUNT_PLAN.md`](plans/025-V0_3_4_STORE_POSTGRES_RAW_ACCOUNT_PLAN.md) et [`validation/021-V0_3_4_STORE_POSTGRES_RAW_ACCOUNT.md`](validation/021-V0_3_4_STORE_POSTGRES_RAW_ACCOUNT.md) ; elle complète la surface RAW backend/façade à dix capabilities. `0.3.5 — Interface acquisition events` est conservée dans [`plans/026-V0_3_5_INTERFACE_ACQUISITION_EVENTS_PLAN.md`](plans/026-V0_3_5_INTERFACE_ACQUISITION_EVENTS_PLAN.md) et [`validation/022-V0_3_5_INTERFACE_ACQUISITION_EVENTS.md`](validation/022-V0_3_5_INTERFACE_ACQUISITION_EVENTS.md) ; elle ajoute les faits passifs provider-neutral de slot et d'exécution de transaction sans déplacer l'ownership Transport/Store. La candidate `0.3.6 — Job API + RAW transaction backfill` est réconciliée dans [`plans/027-V0_3_6_JOB_API_BACKFILL_PLAN.md`](plans/027-V0_3_6_JOB_API_BACKFILL_PLAN.md) avec [`validation/023-V0_3_6_JOB_API_BACKFILL.md`](validation/023-V0_3_6_JOB_API_BACKFILL.md) : `ksp-job-api` reste Core-only et runtime-neutral, tandis que `ksp-job-backfill-lib` fournit le premier runtime historique borné vers RAW via Transport observé + façade Store, avec provenance, idempotence, concurrence bornée, frontier/checkpoint contigus, annulation et snapshots latest-value. [`../crates/ksp-job-api/README.md`](../crates/ksp-job-api/README.md), [`../crates/ksp-job-api/USAGE.md`](../crates/ksp-job-api/USAGE.md), [`../crates/ksp-job-backfill-lib/README.md`](../crates/ksp-job-backfill-lib/README.md) et [`../crates/ksp-job-backfill-lib/USAGE.md`](../crates/ksp-job-backfill-lib/USAGE.md) deviennent les références de crate durables. La candidate `0.3.7 — Backfill Desk` est réconciliée dans [`plans/028-V0_3_7_BACKFILL_DESK_PLAN.md`](plans/028-V0_3_7_BACKFILL_DESK_PLAN.md) avec [`validation/024-V0_3_7_BACKFILL_DESK.md`](validation/024-V0_3_7_BACKFILL_DESK.md) : `ksp-app-backfill-desk` compose Config, HTTP Transport, Store et le runtime Backfill pour Start/monitoring/Cancel/Resume in-session, conserve checkpoint et ressources physiques côté Rust, et fournit un autocomplete libre alimenté par le registre Program IDs de Core. [`../crates/ksp-app-backfill-desk/README.md`](../crates/ksp-app-backfill-desk/README.md) et [`../crates/ksp-app-backfill-desk/USAGE.md`](../crates/ksp-app-backfill-desk/USAGE.md) deviennent les références applicatives durables. La candidate `0.3.8 — Store Desk V1 RAW` est réconciliée dans [`plans/029-V0_3_8_STORE_DESK_PLAN.md`](plans/029-V0_3_8_STORE_DESK_PLAN.md) avec [`validation/025-V0_3_8_STORE_DESK.md`](validation/025-V0_3_8_STORE_DESK.md) : `ksp-app-store-desk` compose Config, Logging et la façade `ksp-store-lib` pour l'inspection read-only des RAW Transactions/Accounts et de leurs observations, avec DataTables server-side, counts exacts, détails bornés et séparation stricte entre inspection random-access et pagination cursor/keyset machine. [`../crates/ksp-app-store-desk/README.md`](../crates/ksp-app-store-desk/README.md) et [`../crates/ksp-app-store-desk/USAGE.md`](../crates/ksp-app-store-desk/USAGE.md) deviennent les références applicatives durables. diff --git a/docs/architecture/000-README.md b/docs/architecture/000-README.md index f2ea09f..2c98531 100644 --- a/docs/architecture/000-README.md +++ b/docs/architecture/000-README.md @@ -1,5 +1,5 @@ - + # Architecture KSP @@ -27,5 +27,6 @@ Ils ne remplacent ni `ROADMAP.md`, ni les plans de version, ni les deltas. 8. [`008-DATA_MATERIALIZATION_AND_STORE.md`](008-DATA_MATERIALIZATION_AND_STORE.md) — niveaux durables D1–D4, Materialization, Store PostgreSQL de référence, provenance, idempotence, replay et notifications de données persistées ; 9. [`009-ACQUISITION_WORKERS_AND_JOBS.md`](009-ACQUISITION_WORKERS_AND_JOBS.md) — pipelines spécialisés, workers live, jobs de backfill/replay, backlog, claim/lease, reprise, concurrence et mécanisme de notification de référence ; 10. [`010-APPS_SERVICES_SCENARIOS_AND_CONTROL.md`](010-APPS_SERVICES_SCENARIOS_AND_CONTROL.md) — apps spécialisées, workers autonomes et need-driven, control plane, scenarios réutilisables, demos desktop et frontières IPC/orchestration. +11. [`011-RAW_TRANSACTION_ACQUISITION.md`](011-RAW_TRANSACTION_ACQUISITION.md) — taxonomie durable d'acquisition `RawTransaction`, audits datés des voies Solana/providers, convergence Store et handoff Worker/Backfill. `004-COMPONENT_INVENTORY.md` et `005-DEPENDENCY_GRAPH.md` sont maintenus ensemble : une évolution du graphe qui change le propriétaire d'une responsabilité doit corriger l'inventaire au lieu de laisser deux descriptions contradictoires. diff --git a/docs/architecture/011-RAW_TRANSACTION_ACQUISITION.md b/docs/architecture/011-RAW_TRANSACTION_ACQUISITION.md new file mode 100644 index 0000000..bcf7140 --- /dev/null +++ b/docs/architecture/011-RAW_TRANSACTION_ACQUISITION.md @@ -0,0 +1,269 @@ + + + +# Acquisition RAW Transaction + +## 1. Rôle + +Ce document est l'owner durable de la taxonomie d'acquisition `RawTransaction` de KSP. Il sépare volontairement : + +- les invariants durables de convergence vers Store ; +- les rôles/capabilities d'acquisition ; +- les audits datés de protocoles/providers ; +- les gaps à transmettre aux releases d'implémentation. + +Il ne définit ni un endpoint secret, ni un quota provider figé, ni une configuration utilisateur. Les disponibilités et limites externes sont réauditées à la date indiquée dans chaque section d'audit. + +## 2. Invariants durables + +La convergence RAW reste indépendante de la source : + +```text +identité canonique transaction = (network, signature) +contenu canonique = source-independent +acquisition utile = RawTransactionObservation distincte +provider/protocole/endpoint = provenance, jamais identité transactionnelle +même identité + même contenu = idempotence +même identité + contenu divergent = conflit explicite +``` + +Une source n'est admise pour persister un `RawTransaction` que si KSP peut reconstruire le payload canonique complet attendu par Store. Un signal incomplet reste une discovery et doit être hydraté par une autre capability. + +## 3. Taxonomie de rôles + +| Rôle | Responsabilité | Exemple standard actuel | +|-------------------------|-----------------------------------------------------------|------------------------------------------------------------------| +| `live_direct_full` | transaction/bloc complet reçu directement | WS blockSubscribe aujourd’hui ; autres sources en pre.005 | +| `live_discovery` | référence/signature reçue puis hydration séparée | WS logsSubscribe | +| `targeted_confirmation` | signature déjà connue surveillée jusqu’au commitment | WS signatureSubscribe | +| `history_discovery` | énumération de références historiques | HTTP getSignaturesForAddress ; HTTP getBlocks/getBlocksWithLimit | +| `hydration` | récupération de transaction complète depuis une référence | HTTP getTransaction | +| `gap_boundary` | détermination d’une fenêtre ou d’une limite de rétention | getSlot/getFirstAvailableBlock/minimumLedgerSlot | +| `gap_repair` | réacquisition explicite après perte de continuité | HTTP bloc ou adresse selon le scope disponible | + +Ces rôles sont orthogonaux au protocole. Une stratégie concrète peut combiner plusieurs rôles et plusieurs transports ; la configuration future ne doit pas réduire le modèle à `Http | WebSocket | Grpc`. + +## 4. Audit daté A — Solana standard + +Audit effectué le **4 septembre 2026** à partir de la documentation RPC Solana courante et de la surface KSP `0.3.9-pre.3`. + +### 4.1 Matrice fonctionnelle + +| Voie | Capability | RAW complet | Temporalité utile | Décision | État KSP | +|------------------------------------------------------|------------------------------------|----------------------------------|-----------------------------------------|------------------------|-----------------------------------------------------------------------------------| +| HTTP `getSignaturesForAddress` + `getTransaction` | discovery adresse + hydration | non / oui | historique, catch-up, repair ciblé | ADMIS | déjà utilisé par Backfill ; `getTransaction` observé conserve provider + endpoint | +| HTTP `getBlocks` / `getBlocksWithLimit` + `getBlock` | discovery slots/blocs + extraction | non / oui | catch-up global, gap repair, historique | ADMIS SOUS GAP | `getBlock` typé existe mais pas de variante observée | +| HTTP `getSlot` | borne haute selon commitment | non | pilotage catch-up / gap | AUXILIAIRE | surface typée KSP disponible | +| HTTP `getFirstAvailableBlock` | borne basse des blocs conservés | non | admission historique / diagnostic | AUXILIAIRE | surface typée KSP disponible | +| HTTP `minimumLedgerSlot` | borne basse ledger du nœud | non | diagnostic de rétention/provider | AUXILIAIRE | surface typée KSP disponible | +| WS `logsSubscribe` | discovery live par logs | non | live + signal de gap | ADMIS | hydration `getTransaction` obligatoire pour RAW complet | +| WS `signatureSubscribe` | suivi d’une signature déjà connue | non | confirmation/repair ciblé | SECONDAIRE | one-shot ; ne découvre pas un flux de transactions | +| WS `blockSubscribe` | bloc live contenant transactions | oui si `transactionDetails=full` | live / catch-up très court | ADMIS SOUS CONTRAINTES | méthode Solana instable + activation validator requise | +| WS `slotSubscribe` | signal slot/parent/root | non | détection/pilotage de gap | AUXILIAIRE | stable mais ne transporte aucune transaction | +| WS `slotsUpdatesSubscribe` | lifecycle détaillé de slot | non | diagnostic de continuité | OPTIONNEL | méthode Solana instable ; pas une source RAW directe | + +### 4.2 HTTP adresse : discovery + hydration + +`getSignaturesForAddress` retourne des signatures confirmées associées à une adresse, ordonnées du plus récent au plus ancien, avec `before`, `until`, `limit`, `commitment` et `minContextSlot`. La discovery est donc naturellement **adressée** : elle ne constitue pas une discovery globale de toutes les transactions du réseau. + +`getTransaction` retourne ensuite la transaction confirmée complète ou `null`. Pour KSP, cette combinaison est la référence actuelle du Backfill et reste admise pour : + +```text +historique adressé +catch-up adressé +repair ciblé +hydration d'un signal WS qui connaît déjà la signature +``` + +Elle n'est pas retenue comme source live globale par polling. + +### 4.3 HTTP bloc : scan global par slots + +`getBlocks` et `getBlocksWithLimit` énumèrent des slots confirmés ; la documentation courante borne leurs ranges/limits à 500 000. `getBlock` peut retourner les transactions complètes du bloc avec `confirmed` ou `finalized` et les options de détail/encodage. + +Cette famille est admise comme stratégie potentielle de : + +```text +catch-up global par slots +gap repair global +historique lorsque le provider conserve la plage demandée +``` + +Elle n'est pas équivalente à `getSignaturesForAddress` : la discovery est par slot/bloc et l'hydration est un conteneur de plusieurs transactions. Le worker doit extraire chaque transaction, reconstruire son identité `(network, signature)` et produire une observation propre à chaque acquisition durable. + +### 4.4 Bornes de continuité HTTP + +`getSlot`, `getFirstAvailableBlock` et `minimumLedgerSlot` ne produisent aucune transaction. Ils servent à décider si un gap est encore réparable sur un endpoint et à borner un scan : + +```text +getSlot -> borne haute selon commitment +getFirstAvailableBlock -> premier bloc confirmé encore disponible +minimumLedgerSlot -> plus ancien slot encore présent dans le ledger du nœud +``` + +Ces méthodes ne prouvent pas à elles seules qu'une transaction précise est disponible ; elles sont des primitives d'admission/diagnostic. + +### 4.5 WS logsSubscribe : discovery live + +`logsSubscribe` peut écouter `all`, `allWithVotes` ou les transactions mentionnant **un seul** pubkey par appel. La notification KSP contient le contexte de slot, la signature, l'erreur nullable et les logs ordonnés. + +Cette notification n'est pas un `RawTransaction` complet. Elle est admise comme **live discovery** : + +```text +logsSubscribe notification + -> signature + slot + -> getTransaction observed + -> normalisation RAW + -> persistence transaction + observation +``` + +Le filtre `mentions` limité à une adresse par subscription implique que la surveillance de nombreux programmes/comptes consomme plusieurs subscriptions, sauf utilisation de `all`/`allWithVotes` avec filtrage côté consumer. + +### 4.6 WS signatureSubscribe : confirmation ciblée + +`signatureSubscribe` surveille une signature déjà connue et s'arrête automatiquement après la notification terminale au commitment demandé. Il ne découvre donc aucune nouvelle transaction. + +Décision : **capability secondaire** pour confirmation/repair ciblé, jamais source principale d'ingestion. Une hydration reste nécessaire pour persister le RAW complet. + +### 4.7 WS blockSubscribe : direct full sous contraintes + +`blockSubscribe` peut fournir les blocs `confirmed`/`finalized`, filtrés par `all` ou par `mentionsAccountOrProgram`. Avec `transactionDetails=full`, il peut transporter directement les transactions nécessaires à la normalisation RAW. + +La méthode reste toutefois documentée comme **instable** par Solana et n'est disponible que si le validator active explicitement la block subscription ainsi que l'historique transactionnel requis. KSP doit donc la traiter comme capability annoncée/testée par endpoint, pas comme propriété universelle de tout endpoint WS standard. + +### 4.8 slotSubscribe et slotsUpdatesSubscribe + +`slotSubscribe` fournit slot/parent/root et peut aider le worker à détecter que la chaîne avance. `slotsUpdatesSubscribe` fournit un lifecycle de slot plus détaillé, mais reste officiellement instable. + +Aucune de ces voies ne transporte une transaction. Elles restent auxiliaires pour continuité/diagnostic et ne justifient jamais une observation Store `RawTransaction` seules. + +### 4.9 Reconnect, ordering et gaps + +Le protocole standard ne transforme pas une reconnexion en replay des notifications perdues. KSP Transport sait resouscrire les subscriptions logiques après reconnexion et expose un compteur de gaps de continuité, mais cela ne prouve pas quels slots/transactions ont été manqués. + +Invariants de composition retenus : + +```text +reconnect WS != replay +duplicate notification = acceptable et dédupliquée par identité/contenu/observation +gap détecté = déclenche une stratégie de repair distincte +repair = HTTP slot/block ou HTTP adresse selon le scope connu +``` + +## 5. Inventaire KSP existant + +### 5.1 Transport + +| Surface KSP | Disponible | Filtres / entrée | Provenance / remarque | +|------------------------------------------------------------------|---------------|-----------------------------------------|--------------------------------------------------------------| +| `get_signatures_for_address` | oui | adresse + before/until/limit/commitment | aucune observation durable nécessaire pour la discovery | +| `get_transaction_observed` | oui | signature + config | provider + endpoint gagnant sûrs | +| `get_blocks` / `get_blocks_with_limit` | oui | range/limit + commitment | discovery de slots uniquement | +| `get_block` | oui | slot + config | GAP : pas de provider/endpoint gagnant observé | +| `get_slot` / `get_first_available_block` / `minimum_ledger_slot` | oui | bornes de continuité | auxiliaires, sans payload RAW | +| `logs_subscribe` | oui | all / allWithVotes / mentions(1 pubkey) | session snapshot fournit endpoint/provider/cluster/protocole | +| `signature_subscribe` | oui | signature connue + commitment | one-shot, terminal côté serveur | +| `block_subscribe` | oui, instable | all / mentionsAccountOrProgram + config | session snapshot fournit provenance de session | +| `slot_subscribe` / `slots_updates_subscribe` | oui | aucun filtre | signaux de continuité uniquement | + +Le runtime WS possède déjà des queues bornées. Une overflow d'une subscription lente est terminale pour cette subscription plutôt que de créer un backlog non borné. Le worker devra traiter cette terminaison comme une cause potentielle de gap et réparer avant de déclarer la continuité retrouvée. + +### 5.2 Store + +Store possède déjà les invariants nécessaires à la convergence multi-source : + +```text +RawTransactionReference = network + signature +RawTransaction = reference + slot + block_time + payload canonique +RawTransactionObservation +RawAcquisitionProvenance +RawTransactionWrite::persist_raw_transaction_acquisition +RawTransactionObservationWrite::record_raw_transaction_observation +``` + +`RawAcquisitionProvenance` sait déjà conserver de manière sûre : provider, protocole, méthode, origin, endpoint logique, commitment, filter id, capture session id, timestamps et hash/taille du payload source. Aucun DTO Transport ne doit être persistant directement. + +### 5.3 Normalisation RAW actuelle + +Le premier canonicalizer RAW v1 est actuellement implémenté dans `ksp-job-backfill-lib::conversion` autour de `getTransaction` observé. Cette implémentation a démontré le format, le hash canonique, la provenance et la persistence du vertical slice Backfill, mais son ownership Job n'est pas réutilisable comme dépendance du futur Worker. + +Décision de cette tranche : **ne pas copier** cette logique dans `0.3.10`. Le handoff final devra choisir une ownership commune ou une extraction compatible avec les frontières de dépendances. + +### 5.4 Config et réseaux + +| Profil | Cluster Transport | Surfaces standard | État | +|-------------------------|-------------------|---------------------------|------------------------------------| +| `devnet_public` | devnet | HTTP + WS standard | déjà présent | +| `mainnet_public` | mainnet-beta | HTTP + WS standard | déjà présent | +| `mainnet_backfill_pool` | mainnet-beta | HTTP pool + WS standard | déjà présent ; rôles backfill HTTP | +| `publicnode_mainnet` | mainnet-beta | HTTP + WS standard + gRPC | gRPC traité en pre.005 | +| `publicnode_testnet` | testnet | HTTP + WS standard + gRPC | gRPC traité en pre.005 | + +Les URLs et secrets restent exclusivement Config-owned. `0.3.9` n'ajoute aucun endpoint ni secret. + +#### Canonicalisation Mainnet + +L'audit interne montre une distinction existante : + +```text +profile/composite id : mainnet +network / cluster : mainnet-beta +``` + +`std.store.json` et `std.transport.json` utilisent déjà `mainnet-beta` comme identité réseau/cluster. Quelques exemples/tests de Backfill utilisent encore `RawNetworkId("mainnet")` comme valeur synthétique. Pour l'ingestion durable, la direction retenue est de conserver **`mainnet-beta` comme identité réseau canonique** et de réserver `mainnet` aux identifiants de profil/UI lorsque nécessaire. Aucune migration n'est effectuée en `pre.004`. + +### 5.5 Interface passive + +`ksp-interface-lib` possède `TransactionExecutionEvent` et `SlotLifecycleEvent`, utiles lorsque plusieurs producers/consumers partagent exactement ces faits passifs. Ils ne remplacent ni les DTOs Transport riches ni `RawTransaction`/`RawTransactionObservation` et ne doivent pas être utilisés comme conteneurs d'acquisition génériques. + +## 6. Gaps préparatoires identifiés en pre.004 + +| ID | Owner futur | Gap / décision à matérialiser | Release cible | Motif | +|-------|-------------------------|---------------------------------------------------------------------------------------------------------------|-----------------|---------------------------------------------------------------------------------------------------------------------| +| TR-A | Transport | ajouter une voie observée pour `getBlock` si le scan bloc est admis en V1 | 0.3.10 | nécessaire pour provider/endpoint exacts dans `RawTransactionObservation` avec pool multi-endpoint | +| TR-B | Transport/ingest | définir l’extraction déterministe transaction-par-transaction depuis `SolanaConfirmedBlock` | 0.3.10 | le DTO bloc existe, la conversion RAW transactionnelle commune n’existe pas encore | +| RAW-A | Architecture/code owner | sortir la normalisation RAW v1 de l’enfermement Backfill sans duplication | 0.3.10 | la logique canonique actuelle vit dans `ksp-job-backfill-lib::conversion` | +| REC-A | Worker ingest | associer reconnect WS à une stratégie explicite de gap repair | 0.3.10 | resubscribe != replay ; `continuity_gap_count` n’identifie pas les transactions manquées | +| CFG-A | Config/composition | exprimer des rôles/capabilities d’acquisition, pas un simple enum HTTP/WS/gRPC | 0.3.10 | les profils existent déjà mais le rôle ingest multi-source n’est pas matérialisé | +| NET-A | Naming | retenir `mainnet-beta` comme identité réseau durable/configurée et `mainnet` seulement comme profile/UI alias | 0.3.10 / 0.3.12 | Store + Transport Config utilisent déjà `mainnet-beta`; quelques exemples/tests Backfill utilisent encore `mainnet` | + +Ces gaps sont des entrées de handoff. `pre.004` ne les implémente pas. + +## 7. Sources externes de l'audit daté + +Consultées le 4 septembre 2026 : + +| Source Solana | URL | +|-------------------------|-------------------------------------------------------------| +| getSignaturesForAddress | https://solana.com/docs/rpc/http/getsignaturesforaddress | +| getTransaction | https://solana.com/docs/rpc/http/gettransaction | +| getBlocks | https://solana.com/docs/rpc/http/getblocks | +| getBlocksWithLimit | https://solana.com/docs/rpc/http/getblockswithlimit | +| getBlock | https://solana.com/docs/rpc/http/getblock | +| getSlot | https://solana.com/docs/rpc/http/getslot | +| getFirstAvailableBlock | https://solana.com/docs/rpc/http/getfirstavailableblock | +| minimumLedgerSlot | https://solana.com/docs/rpc/http/minimumledgerslot | +| logsSubscribe | https://solana.com/docs/rpc/websocket/logssubscribe | +| signatureSubscribe | https://solana.com/docs/rpc/websocket/signaturesubscribe | +| blockSubscribe | https://solana.com/docs/rpc/websocket/blocksubscribe | +| slotSubscribe | https://solana.com/docs/rpc/websocket/slotsubscribe | +| slotsUpdatesSubscribe | https://solana.com/docs/rpc/websocket/slotsupdatessubscribe | + +Les quotas, tiers provider et capacités Helius/Yellowstone ne sont volontairement pas documentés ici ; ils appartiennent à l'audit `pre.005`. + +## 8. État après pre.004 + +Décisions fermées pour le standard Solana : + +```text +HTTP address discovery + hydration = admis historique/catch-up/repair +HTTP block scan = admis sous gap de provenance observée +WS logsSubscribe = admis comme live discovery + hydration +WS signatureSubscribe = secondaire, signature déjà connue +WS blockSubscribe = admis sous capability explicite et instabilité +slot/ledger methods = auxiliaires de continuité +reconnect WS = jamais considéré comme replay +mainnet-beta = identité réseau canonique à préserver +``` + +Restent ouverts pour `pre.005`/`pre.006` : Helius, Yellowstone, autres providers, replay provider-specific, quotas/tier, stratégie multi-source V1 exacte et décision finale d'ownership du canonicalizer RAW. diff --git a/docs/plans/030-V0_3_9_WORKER_API_RAW_TRANSACTION_AUDIT_PLAN.md b/docs/plans/030-V0_3_9_WORKER_API_RAW_TRANSACTION_AUDIT_PLAN.md index 5e71547..dc84fad 100644 --- a/docs/plans/030-V0_3_9_WORKER_API_RAW_TRANSACTION_AUDIT_PLAN.md +++ b/docs/plans/030-V0_3_9_WORKER_API_RAW_TRANSACTION_AUDIT_PLAN.md @@ -1,5 +1,5 @@ - + # Plan v0.3.9 — Worker API générique + audit RAW Transaction @@ -575,15 +575,15 @@ Le champ tuple de `WorkerSnapshotSequence` reste privé. L'`impl crate::WorkerSn ### `pre.003` — hardening, races, object-safety, impl externe et freeze -**Statut : réalisé ; gate opérateur demandé avant freeze effective.** +**Statut : réalisé ; gate opérateur PASS, Worker API effectivement frozen.** -Budget cible : **15-20 min**. La production API de `pre.002` reste inchangée : aucun nouveau type, module runtime ou edge de dépendance n'est nécessaire. La tranche ferme le hardening par preuves externes et adversariales : immutabilité terminale sous tous les mutateurs, trois ordres stop/fault, redaction hostile, stop cross-thread, `Send + Sync`, object-safety, implémentation std-only de `WorkerSnapshotSource`, coalescing latest-value pour listeners indépendants/lents, late-listener resync, rétention du snapshot terminal, inventaires exacts de modules/exports et firewall runtime/domain. `README.md` et `USAGE.md` durables sont créés pour la bibliothèque désormais fonctionnellement complète ; leur dernière réconciliation reste réservée à `pre.008`. Sortie : Worker API matériellement fermée, freeze effective dès validation du gate Cargo opérateur, avant tout audit RAW provider. +Budget cible : **15-20 min**. La production API de `pre.002` reste inchangée : aucun nouveau type, module runtime ou edge de dépendance n'est nécessaire. La tranche ferme le hardening par preuves externes et adversariales : immutabilité terminale sous tous les mutateurs, trois ordres stop/fault, redaction hostile, stop cross-thread, `Send + Sync`, object-safety, implémentation std-only de `WorkerSnapshotSource`, coalescing latest-value pour listeners indépendants/lents, late-listener resync, rétention du snapshot terminal, inventaires exacts de modules/exports et firewall runtime/domain. `README.md` et `USAGE.md` durables sont créés pour la bibliothèque désormais fonctionnellement complète ; leur dernière réconciliation reste réservée à `pre.008`. Sortie : Worker API matériellement fermée. Le gate opérateur exécuté le 4 septembre 2026 est PASS : audits propres, workspace check/clippy `-D warnings`, 32 tests Worker + doc-tests et deux arbres Cargo propres. La Worker API est donc effectivement frozen avant l'audit RAW détaillé. ### `pre.004` — audit RAW A : Solana standard + KSP Transport/Store/Config -**Statut : prévu.** +**Statut : réalisé ; audit documentaire daté, aucun runtime modifié.** -Budget cible : **15-20 min**. Auditer les voies standard Solana et l’inventaire KSP existant afin d’établir les capabilities, rôles et gaps internes nécessaires à la suite. +Budget cible : **15-20 min**. Le document durable `docs/architecture/011-RAW_TRANSACTION_ACQUISITION.md` est créé et ouvre l'audit daté du 4 septembre 2026. Les voies standard sont classifiées en capabilities orthogonales : discovery adressée + hydration HTTP, scan bloc HTTP, live discovery `logsSubscribe`, confirmation ciblée `signatureSubscribe`, direct full `blockSubscribe` sous capability explicite, et primitives slot/ledger auxiliaires. L'inventaire KSP confirme Store/provenance et Config déjà suffisants pour plusieurs voies, mais identifie notamment l'absence de `get_block_observed`, l'ownership Backfill actuelle du canonicalizer RAW v1, le besoin de gap repair explicite après reconnect WS et la canonicalisation durable `mainnet-beta`. Aucun gap n'est implémenté dans cette tranche. ### `pre.005` — audit RAW B : Helius, Yellowstone/providers + kbot3 fonctionnel diff --git a/docs/validation/026-V0_3_9_WORKER_API_RAW_TRANSACTION_AUDIT.md b/docs/validation/026-V0_3_9_WORKER_API_RAW_TRANSACTION_AUDIT.md index a046a7f..eb3a2e2 100644 --- a/docs/validation/026-V0_3_9_WORKER_API_RAW_TRANSACTION_AUDIT.md +++ b/docs/validation/026-V0_3_9_WORKER_API_RAW_TRANSACTION_AUDIT.md @@ -1,5 +1,5 @@ - + # Validation v0.3.9 — Worker API + audit RAW Transaction @@ -145,8 +145,8 @@ Les cases cochées de cette sous-section attestent la matérialisation de la sur - [X] `crates/ksp-worker-api/README.md` descriptif durable ajouté. - [X] `crates/ksp-worker-api/USAGE.md` version-neutral ajouté avec exemples identity/lifecycle/health/activity/stop/snapshot/source/sequence. - [X] Audits Python d'assemblage : Rust clean, export completeness 0, KSP workspace clean, Markdown clean (320 tables / 736 fichiers). -- [ ] Gate Cargo opérateur `pre.003` exécuté. -- [ ] Worker API déclarée effectivement frozen avant tout audit RAW détaillé ; cette case se ferme uniquement après le gate Cargo opérateur. +- [X] Gate Cargo opérateur `pre.003` exécuté : audits clean, `cargo check --workspace` PASS, Clippy `-D warnings` PASS, 13 unit + 4 dependency + 2 public API + 4 completeness + 6 hardening + 3 snapshot source PASS, doc-tests PASS. +- [X] Worker API déclarée effectivement frozen avant tout audit RAW détaillé. ## 5. Threat model à fermer @@ -163,7 +163,7 @@ Les cases cochées de cette sous-section attestent la matérialisation de la sur - [X] Health/lifecycle séparés. - [X] Fausse notion de completion/progress Worker interdite. - [X] Runtime ownership reste hors API. -- [ ] Canaries Rust correspondantes exécutées après matérialisation. +- [X] Canaries Rust correspondantes exécutées après matérialisation. ## 6. Audit RAW Transaction post-freeze @@ -171,15 +171,15 @@ Aucun item ci-dessous n’est déclaré exécuté en `pre.001`. ### `pre.004` — Solana standard + KSP -- [ ] Réaudit Solana JSON-RPC HTTP primaire. -- [ ] Réaudit Solana WebSocket primaire. -- [ ] Capabilities KSP Transport réellement publiques inventoriées. -- [ ] Store RAW identity/content/provenance réconfirmés. -- [ ] Config/secrets/network descriptors inventoriés pour handoff uniquement. -- [ ] HTTP discovery/hydration roles classifiés. -- [ ] WS logs/signature/block roles classifiés. -- [ ] Live/catch-up/gap-repair/history applicability documentée. -- [ ] `mainnet` / `mainnet-beta` audit interne commencé sans migration. +- [X] Réaudit Solana JSON-RPC HTTP primaire. +- [X] Réaudit Solana WebSocket primaire. +- [X] Capabilities KSP Transport réellement publiques inventoriées. +- [X] Store RAW identity/content/provenance réconfirmés. +- [X] Config/secrets/network descriptors inventoriés pour handoff uniquement. +- [X] HTTP discovery/hydration roles classifiés. +- [X] WS logs/signature/block roles classifiés. +- [X] Live/catch-up/gap-repair/history applicability documentée. +- [X] `mainnet` / `mainnet-beta` audit interne commencé sans migration ; `mainnet-beta` retenu comme identité durable. ### `pre.005` — providers + kbot3 historique @@ -205,7 +205,7 @@ Aucun item ci-dessous n’est déclaré exécuté en `pre.001`. - [ ] Réutilisation unique `KSP_SECRET_HELIUS_API_KEY` confirmée. - [ ] Stratégie compatible `mainnet` / `mainnet-beta` conclue. - [ ] Applicability `0.3.12` Backfill indiquée par source/méthode. -- [ ] `docs/architecture/011-RAW_TRANSACTION_ACQUISITION.md` créé comme owner de l’audit. +- [X] `docs/architecture/011-RAW_TRANSACTION_ACQUISITION.md` créé dès `pre.004` comme owner durable, à enrichir en `pre.005`/`pre.006`. ## 7. Couloirs de fermeture @@ -248,10 +248,10 @@ Aucun item ci-dessous n’est déclaré exécuté en `pre.001`. La livraison initiale `pre.001` avait conservé `workspace.package.version = 0.3.8` en suivant l’exception du prompt 028. Cette exception est supplantée par la règle normative `VER-ID-009`. -Après matérialisation de `pre.003`, l’état courant est : +Après l'audit standard `pre.004`, l'état courant est : ```text -workspace.package.version = 0.3.9-pre.3 +workspace.package.version = 0.3.9-pre.4 ``` -`pre.002` reste la tranche non-fix `0.3.9-pre.2`. Les correctifs de conformité/compilation portent successivement `0.3.9-pre.2.fix.1` puis `0.3.9-pre.2.fix.2` conformément à `VER-ID-007` et `VER-ID-010`. `pre.003` reprend ensuite la séquence prerelease normale avec `0.3.9-pre.3`. L'état précédent `0.3.9-pre.1.fix.2` reste documenté dans `pre.001-fix.002`. +`pre.002` reste la tranche non-fix `0.3.9-pre.2`. Les correctifs de conformité/compilation portent successivement `0.3.9-pre.2.fix.1` puis `0.3.9-pre.2.fix.2` conformément à `VER-ID-007` et `VER-ID-010`. `pre.003` reprend ensuite la séquence prerelease normale avec `0.3.9-pre.3`; son gate opérateur est PASS et freeze Worker API. `pre.004` poursuit avec `0.3.9-pre.4` sans changement runtime, uniquement l'audit standard Solana/KSP et la création de l'owner durable d'acquisition. L'état précédent `0.3.9-pre.1.fix.2` reste documenté dans `pre.001-fix.002`.