<!-- file: deltas/0.1.1/pre.003.md -->
<!-- version: 1 -->

# Delta `0.1.1-pre.003` — Pubkey + Program IDs

## Statut

Tranche fonctionnelle `0.1.1-pre.003` préparée après validation réussie par le user de `0.1.1-pre.002-fix.001`.

La base utilisateur observée avant ce delta utilise :

```text
workspace.package.version = "0.1.1-pre.2.fix.1"
```

Le présent delta ouvre :

```text
workspace.package.version = "0.1.1-pre.3"
```

## Validation de la base précédente

Le user a exécuté avec succès avant ce delta :

```bash
cargo fmt --all
cargo check --workspace
cargo clippy --workspace --all-targets
cargo test --workspace
```

Les six tests unitaires Error et le test d'intégration public Error passent sans warning dans cette validation.

## Audit Solana/Anza revérifié

Au 2026-08-14 :

- `solana-pubkey 4.3.0` est la version publiée courante observée sur crates.io ;
- son MSRV publié est Rust `1.89.0` ;
- la validation précédente du user expose une génération Clippy `rust-1.94.0`, donc la toolchain observée satisfait ce MSRV ;
- `Pubkey` reste la façade de compatibilité officielle sur l'`Address` Solana actuel ;
- `Pubkey::from_str_const` permet le décodage Base58 compile-time nécessaire à la macro KSP ;
- `solana-sdk-ids` est consulté uniquement comme source d'audit et n'entre pas dans le graphe Cargo KSP.

Sources externes revérifiées pendant cette tranche :

- crates.io / docs.rs pour `solana-pubkey 4.3.0` ;
- `anza-xyz/solana-sdk`, `sdk-ids/src/lib.rs`, pour les identifiants fondamentaux actuellement publiés ;
- SIMD-0204 et la documentation Anza pour le Slashing Program `S1ashing11111111111111111111111111111111111`.

## Dépendance Core

`crates/ksp-core-lib/Cargo.toml` ajoute uniquement :

```toml
solana-pubkey = { version = "4.3.0", default-features = false }
```

Aucun codec wire, client RPC, umbrella SDK ou registre `solana-sdk-ids` n'est ajouté.

`ksp_core_lib::Pubkey` réexporte `solana_pubkey::Pubkey` depuis la façade Core.

## Macro KSP de Program ID

La macro publique :

```text
ksp_core_lib::declare_program_id!
```

possède la chaîne Base58 une seule fois et produit simultanément :

```text
PRGID_*   : &'static str
PRGIDPK_* : Pubkey
```

La représentation typée est construite avec `Pubkey::from_str_const`, sans parsing runtime, `unwrap`, `expect`, `panic` ni opérateur `?`.

La macro ne génère pas de symboles génériques `ID`, `id()` ou `check_id()` et peut donc être utilisée plusieurs fois dans une même crate/module.

## Première surface Program IDs Core

La tranche fixe le premier registre à 18 Program IDs.

Les 17 valeurs de la surface officielle actuelle Anza `solana-sdk-ids` sont possédées localement par KSP :

1. Address Lookup Table ;
2. BPF Loader historique v1 ;
3. BPF Loader v2 ;
4. BPF Loader Upgradeable ;
5. Compute Budget ;
6. Config ;
7. Ed25519 precompile ;
8. Feature ;
9. Loader v4 ;
10. Native Loader ;
11. Secp256k1 precompile ;
12. Secp256r1 precompile ;
13. Stake ;
14. System ;
15. Vote ;
16. ZK ElGamal Proof ;
17. ZK Token Proof.

Le dix-huitième identifiant est :

```text
PRGID_SOLANA_SLASHING = "S1ashing11111111111111111111111111111111111"
```

Son statut de programme enshrined et son adresse sont confirmés séparément par SIMD-0204/Anza ; sa présence ne dépend donc pas de l'ancien registre bot3.

Les sysvars, `StakeConfig`, l'incinerator et les autres well-known accounts restent exclus du registre Program IDs.

## Nomenclature publique

Chaque entrée possède une paire `PRGID_*` / `PRGIDPK_*` au crate-root.

Exemples :

```text
PRGID_SOLANA_SYSTEM
PRGIDPK_SOLANA_SYSTEM

PRGID_SOLANA_LOADER_BPF_V1
PRGIDPK_SOLANA_LOADER_BPF_V1

PRGID_SOLANA_PRECOMPILE_ED25519
PRGIDPK_SOLANA_PRECOMPILE_ED25519

PRGID_SOLANA_SLASHING
PRGIDPK_SOLANA_SLASHING
```

Le suffixe est strictement identique entre les deux représentations.

## Registre canonique

`ProgramIdEntry` porte :

```text
code
name
program_id
pubkey
domain
family
protocol
subfamily
program_version
kind
```

Les axes fonctionnels restent extensibles sous forme de chaînes. Aucun enum central fermé des domaines, familles ou protocoles futurs n'est créé.

`ProgramIdKind` est limité à la classification technique :

```text
Program
Loader
Precompile
EnshrinedProgram
```

La première taxonomie Core utilise :

```text
domain   = solana
protocol = solana

family = runtime
family = consensus
family = loader
family = precompile
family = proof
```

`program_version` reste distinct de `subfamily`. Les BPF loaders v1/v2 et Loader v4 utilisent l'axe version ; la branche BPF utilise séparément `subfamily = bpf`.

## API de recherche et vues

La façade expose :

```text
entries()
program_ids(filter)
native_program_ids()
program_ids_by_domain(...)
program_ids_by_family(...)
program_ids_by_protocol(...)
find_program_id(...)
find_program_pubkey(...)
```

`ProgramIdFilter` peut combiner :

```text
domain
family
protocol
subfamily
program_version
kind
```

Toutes les vues sont construites à partir du registre canonique unique. Elles retournent des iterators paresseux sans dupliquer un tableau statique par catégorie.

Une future fonction `amm_program_ids()` pourra donc devenir une vue `family = amm` sans changement structurel de `ProgramIdEntry`.

## Tests ajoutés

`unit_tests/program_ids.rs` vérifie notamment :

- cohérence texte/`Pubkey` des déclarations ;
- présence exacte des 18 Program IDs Core ;
- unicité des codes, Base58 et `Pubkey` ;
- correspondance de chaque `Pubkey` avec la Base58 KSP ;
- intersection des six axes de filtre ;
- tailles attendues des familles Core actuelles ;
- recherche texte et `Pubkey` ;
- absence de l'incinerator, `StakeConfig` et du Clock sysvar.

`tests/public_api.rs` vérifie en consommateur externe :

- la macro `declare_program_id!` ;
- les constantes `PRGID_*` / `PRGIDPK_*` ;
- `Pubkey` ;
- les vues du registre ;
- les getters de `ProgramIdEntry` ;
- le filtrage public combiné.

## Documentation

`docs/plans/003-V0_1_1_CORE_FOUNDATION_PLAN.md` passe en version documentaire 6 afin de :

- fixer l'inventaire Core à 18 IDs ;
- tracer la vérification du Slashing Program ;
- enregistrer `solana-pubkey 4.3.0` comme dépendance effectivement introduite ;
- fermer la question de MSRV de `pre.003` ;
- fixer `ProgramIdKind` et les retours iterator des vues ;
- compléter l'API publique réellement implémentée.

## Hors scope préservé

Cette tranche n'ajoute toujours pas :

- SPL Token/Token-2022/ATA/Memo ;
- Metaplex ou DEX ;
- well-known accounts ;
- codecs Borsh/Wincode ;
- decoder/executor/IDL ;
- RPC/WS ;
- Wallet ;
- Logging ;
- Config ;
- Store ;
- applications.

## Validations à exécuter sur le dépôt cible

Cette livraison ne déclare aucune validation Cargo non exécutée dans l'environnement de génération.

Après application :

```bash
cargo fmt --all
cargo check --workspace
cargo test --workspace
cargo clippy --workspace --all-targets
cargo tree -p ksp-core-lib
cargo tree -p ksp-core-lib -d
```

Les deux commandes `cargo tree` doivent notamment confirmer l'absence de `solana-sdk-ids` et permettre de contrôler le graphe/features réellement résolus.

## Suite

Si les validations sont propres, la tranche suivante reste :

```text
0.1.1-pre.004 — intégration Core + audits
```