18 KiB
Documentation KSP
Ce fichier est le point d'entrée du répertoire docs/.
Le préfixe 000- est volontaire : la documentation est destinée à devenir volumineuse et cette convention maintient le point d'entrée en première position dans les listings, arbres de fichiers et classements lexicaux usuels. Dans les répertoires documentaires où un ordre explicite est utile, d'autres fichiers prioritaires peuvent utiliser 001-, 002-, etc. ; 000-README.md reste toujours prioritaire. Cette convention ne s'applique pas aux fichiers situés à la racine du dépôt.
Rôle de docs/
Le répertoire contient la documentation durable du projet : règles détaillées, idées à explorer, architecture, spécifications de formats, références, décisions, guides, plans et validations.
Les documents temporaires d'une livraison ne sont pas stockés sous docs/. Ils sont enregistrés sous deltas/ afin de conserver un seul historique de livraison pour l'ensemble du dépôt.
Organisation
docs/
├── 000-README.md
├── IDEAS.md
├── architecture/
│ ├── 000-README.md
│ ├── 001-PROJECT_OBJECTIVES.md
│ ├── 002-LAYERS_AND_DEPENDENCIES.md
│ ├── 003-COMPONENT_CONTRACTS.md
│ ├── 004-COMPONENT_INVENTORY.md
│ ├── 005-DEPENDENCY_GRAPH.md
│ ├── 006-WIRE_AND_PROGRAM.md
│ ├── 007-EXECUTION_AND_POLICY.md
│ ├── 008-DATA_MATERIALIZATION_AND_STORE.md
│ ├── 009-ACQUISITION_WORKERS_AND_JOBS.md
│ └── 010-APPS_SERVICES_SCENARIOS_AND_CONTROL.md
├── formats/
│ ├── 000-README.md
│ ├── KSPWALLET_V1.md
│ └── KSPWALLET_V2.md
├── plans/
│ ├── 000-README.md
│ ├── 001-V0_0_3_PLAN.md
│ ├── 002-FUNCTIONAL_RELEASE_SEQUENCE.md
│ ├── 003-V0_1_1_CORE_FOUNDATION_PLAN.md
│ ├── 004-V0_1_2_LOGGING_FOUNDATION_PLAN.md
│ ├── 005-V0_1_3_CONFIG_FOUNDATION_PLAN.md
│ ├── 006-V0_1_4_CONFIG_DESKTOP_PLAN.md
│ ├── 007-V0_2_0_SERIES_PLANNING.md
│ ├── 008-V0_2_1_ONCHAIN_HTTP_PLAN.md
│ ├── 009-V0_2_2_HTTP_ACCOUNTS_TOKENS_CLUSTER_PLAN.md
│ ├── 010-V0_2_3_HTTP_TRANSACTIONS_PLAN.md
│ ├── 011-V0_2_4_HTTP_BLOCKS_ECONOMICS_PLAN.md
│ ├── 012-V0_2_5_WALLET_FOUNDATION_PLAN.md
│ ├── 013-V0_2_6_WALLET_DESK_PLAN.md
│ ├── 014-V0_2_7_ONCHAIN_WEBSOCKET_PLAN.md
│ ├── 015-V0_2_8_HELIUS_LASERSTREAM_WEBSOCKET_PLAN.md
│ ├── 016-V0_2_9_YELLOWSTONE_GRPC_PLAN.md
│ ├── 017-V0_2_10_ORBITFLARE_YELLOWSTONE_GRPC_PLAN.md
│ ├── 018-V0_2_11_OFFCHAIN_PRICE_TRANSPORT_PLAN.md
│ ├── 019-V0_2_12_SOL_PRICES_DESK_PLAN.md
│ └── 020-V0_2_13_INTERFACE_PLAN.md
├── validation/
│ ├── 000-README.md
│ ├── 001-V0_1_4_CONFIG_DESKTOP.md
│ ├── 002-V0_2_0_SERIES_PLANNING.md
│ ├── 003-V0_2_1_ONCHAIN_HTTP.md
│ ├── 004-V0_2_2_HTTP_ACCOUNTS_TOKENS_CLUSTER.md
│ ├── 005-V0_2_3_KSP_TRANSPORT_007_RETRO_AUDIT.md
│ ├── 006-V0_2_3_HTTP_TRANSACTIONS.md
│ ├── 007-V0_2_4_HTTP_FINAL_COMPLIANCE.md
│ ├── 008-V0_2_5_WALLET_SECURITY_COMPLIANCE.md
│ ├── 009-V0_2_6_WALLET_DESK_COMPLIANCE.md
│ ├── 010-V0_2_7_ONCHAIN_WEBSOCKET.md
│ ├── 011-V0_2_8_HELIUS_LASERSTREAM_WEBSOCKET.md
│ ├── 012-V0_2_9_YELLOWSTONE_GRPC.md
│ ├── 013-V0_2_10_ORBITFLARE_YELLOWSTONE_GRPC.md
│ ├── 014-V0_2_11_OFFCHAIN_PRICE_TRANSPORT.md
│ ├── 015-V0_2_12_SOL_PRICES_DESK.md
│ └── 016-V0_2_13_INTERFACE.md
└── rules/
├── FILE_CONTRACTS.md
├── PROMPT_STRUCTURE.md
├── RULES_DEPENDENCIES.md
├── RULES_DOCUMENTATION.md
├── RULES_GENERAL.md
├── RULES_KSP.md
├── RULES_RUST.md
├── SCENARIO_CONVENTION.md
└── VERSION_WORKFLOW.md
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.
Documents de planification
Le plan historique de la phase fondatrice clôturée est conservé dans 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. 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. 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. 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. 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, avec sa matrice finale validation/001-V0_1_4_CONFIG_DESKTOP.md. Son prompt d'ouverture historique reste ../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, avec sa matrice finale 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. Son gate de sizing et sa matrice exhaustive sont conservés dans plans/008-V0_2_1_ONCHAIN_HTTP_PLAN.md, avec la validation finale 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 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 conserve l'audit et l'implémentation des 22 wrappers typés, tandis que 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 a ouvert la release stable 0.2.3 — HTTP Transactions. Son plan clôturé 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 confirme la complétude des 37 wrappers HTTP typés et 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 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 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 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, 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 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 avant la documentation finale pre.010 ; pre.010 finalise ../crates/ksp-wallet-lib/README.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 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 : 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 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 ; la matrice normative puis finale est conservée dans 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 ouvre 0.2.8 — Helius LaserStream WebSocket. Le plan historique clôturé plans/015-V0_2_8_HELIUS_LASERSTREAM_WEBSOCKET_PLAN.md et la matrice finale 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 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 et 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 et 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 et 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 et ../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 et 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 avec la matrice finale candidate 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 et ../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. 0.2.14 — Program API foundation est réconciliée comme candidate dans plans/021-V0_2_14_PROGRAM_API_PLAN.md avec la matrice finale candidate validation/017-V0_2_14_PROGRAM_API.md : ksp-program-api fournit une façade instruction-only ouverte, ProgramInstructionRecognition, ProgramInstructionDecodeOutcome<Decoded> 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 et ../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.
Spécifications de formats
Les formats durables, interopérables et destinés à être réimplémentables hors de KSP sont indexés depuis formats/000-README.md. .kspwallet V1 reste le format JSON historique stable publié par 0.2.5. .kspwallet V2, publié stable avec 0.2.6, ajoute le wire binaire canonique KSP, le runtime multi-version/default V2 et la migration explicite OWNER-authentifiée V1 -> V2.
IDEAS.md conserve les pistes et questions qui ne sont pas encore des engagements du roadmap ni des décisions architecturales.
Prompts
Les prompts de reprise eux-mêmes sont conservés sous ../prompts/.
Leur contrat de rédaction, de dimensionnement et de cycle de vie est défini dans rules/PROMPT_STRUCTURE.md.
Documents normatifs
Les règles sont indexées depuis ../RULES.md. Aucun document de brainstorming, plan ou delta ne devient normatif uniquement parce qu'il existe dans le dépôt.