khadhroony-bot3/migration/khadhroony-bot2-reference/kb_executor_spl_token_2022/README.md

kb_executor_spl_token_2022

Ce crate construit des plans d’exécution typés pour le programme SPL Token-2022. Il ne diffuse aucune transaction directement : l’orchestration impose simulation, plafonds de coûts, signataires autorisés et validation post-exécution.

Frontière

• Program ID exact : TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb.
• Builders officiels de spl-token-2022-interface.
• Clés publiques exposées par solana_pubkey::Pubkey via les contrats kb_model.
• Batch reste decode-only tant qu’aucun builder officiel n’est publié.
• Les opérations confidentielles restent séparées jusqu’à validation complète des preuves et comptes de contexte.

Transfer Fee

La tranche 0.4.6-pre.043 ajoute les six builders publics officiels :

• initialize_transfer_fee_config ;
• set_transfer_fee ;
• transfer_checked_with_fee ;
• withdraw_withheld_tokens_from_mint ;
• withdraw_withheld_tokens_from_accounts ;
• harvest_withheld_tokens_to_mint.

Les montants restent des chaînes décimales u64. Les basis points sont limités à 10_000. Les listes de comptes sources sont non vides, uniques, ordonnées et limitées à 255 occurrences. Les autorités simples et multisig conservent exactement les metas publiées par l’interface officielle.

Default Account State, Memo Transfer et CPI Guard

La tranche 0.4.6-pre.044 ajoute les six builders publics officiels :

• initialize_default_account_state ;
• update_default_account_state ;
• enable_required_transfer_memos ;
• disable_required_transfer_memos ;
• enable_cpi_guard ;
• disable_cpi_guard.

InitializeDefaultAccountState doit précéder l'initialisation du mint. La mise à jour utilise la freeze authority, simple ou multisig. Memo Transfer et CPI Guard modifient un Token Account et utilisent son owner, simple ou multisig. Les états par défaut sont typés initialized ou frozen; aucune valeur numérique arbitraire n'est acceptée.

Transfer Hook et pointers

La tranche 0.4.6-pre.045 ajoute les huit builders publics officiels :

• initialize_transfer_hook et update_transfer_hook ;
• initialize_metadata_pointer et update_metadata_pointer ;
• initialize_group_pointer et update_group_pointer ;
• initialize_group_member_pointer et update_group_member_pointer.

Les initialisations doivent précéder l'initialisation du mint et acceptent une autorité optionnelle ainsi qu'une cible optionnelle. Les mises à jour utilisent une autorité simple ou multisig et acceptent None pour supprimer explicitement la cible. Les metas et l'ordre des signataires proviennent exclusivement des builders officiels de spl-token-2022-interface.

Sécurité

• simulation obligatoire ;
• dry-run par défaut ;
• plafond de frais positif obligatoire ;
• matérialisation post-exécution requise pour les mutations ;
• aucun calcul de fee implicite : transfer_checked_with_fee exige le montant attendu exact ;
• aucun retrait ou harvest n’invente l’état final, qui doit être relu par le pipeline stateful.

Token Metadata et Token Group

La tranche 0.4.6-pre.046 ajoute les builders officiels des interfaces exécutées sous le Program ID Token-2022 :

• initialisation, mise à jour de champ et suppression de clé Token Metadata ;
• initialisation de groupe, mise à jour de max_size et initialisation de membre ;
• chaînes metadata bornées à 1 024 octets par champ dans le contrat d’exécution ;
• comptes et signataires conservés dans l’ordre publié par les interfaces ;
• aucune confusion avec Metaplex Token Metadata ni avec une implémentation tierce des interfaces.

Les instructions utilisent les discriminateurs SPL des interfaces et non un tag TokenInstruction sur un octet. Le dispatcher reste strictement attaché au Program ID Token-2022 pour cette crate.

Extensions publiques récentes

L’exécuteur construit désormais les opérations officielles ScaledUiAmount, Pausable et PermissionedBurn. Les multiplicateurs Scaled UI sont fournis sous forme de chaîne décimale, puis refusés s’ils ne sont pas strictement positifs, finis et normaux. PermissionedBurn conserve séparément l’autorité dédiée obligatoire et l’owner/delegate simple ou multisig du compte source. Les opérations confidentielles de burn restent hors de cette tranche.

Audit Confidential Transfer

La tranche 0.4.6-pre.048 publie uniquement le contrat audité des opérations confidentielles : inventaire des opérations, ordre exact des preuves, modes instruction_offset et context_state_account, et classification entre builders ne nécessitant que des données publiques et opérations exigeant des entrées cryptographiques générées par l’appelant.

Un offset inline nul est refusé : la valeur wire 0 est réservée au mode compte de contexte. Les instructions Token-2022, les instructions du programme ZK ElGamal Proof et les instructions du registre ElGamal restent trois surfaces techniques distinctes. Aucun chiffrement, déchiffrement, secret ou preuve n’est généré par ce crate.

Confidential Transfer public-data builders

The executor constructs the six Confidential Transfer operations whose complete wire payload is public and requires no caller-generated proof or ciphertext: account approval, public deposit, and the four credit toggles. Initialize/update mint and apply-pending-balance remain deferred because their official data contracts include ElGamal or decryptable-balance material that must be supplied as bounded opaque caller input.

Confidential Transfer — entrées cryptographiques opaques

L’exécuteur accepte désormais les clés publiques ElGamal de 32 octets et les balances déchiffrables de 36 octets sous forme hexadécimale stricte. Il construit InitializeMint, UpdateMint et ApplyPendingBalance avec les builders officiels, sans générer ni dériver de secret.

Configuration confidentielle des comptes

ConfigureConfidentialTransferAccount accepte une balance zéro déchiffrable opaque, un compteur maximal de crédits en attente, une autorité simple ou multisig et une référence PubkeyValidity explicite. Le mode InstructionOffset référence une instruction ZK déjà orchestrée dans la transaction ; le mode ContextStateAccount référence un contexte pré-vérifié. Le crate ne fabrique aucune preuve.

ConfigureConfidentialTransferAccountWithRegistry utilise un compte ElGamal Registry explicite. Le payer de réallocation est optionnel ; lorsqu’il est présent, le builder officiel ajoute le System Program. La cohérence owner/PDA du registre reste un préflight obligatoire avant diffusion.

Confidential Transfer — vidage du compte

EmptyConfidentialTransferAccount construit l’instruction Token-2022 EmptyAccount avec une référence ZeroCiphertext explicite. Le mode InstructionOffset ajoute uniquement le compte Instructions Sysvar et encode l’offset signé non nul ; le mode ContextStateAccount ajoute le compte de contexte readonly et encode l’offset 0. L’autorité owner/delegate simple ou multisig reste ordonnée exactement. Le crate ne génère ni preuve ni donnée secrète.

WithdrawConfidentialTokens construit l’instruction Withdraw avec montant brut, decimals, nouvelle balance déchiffrable opaque et deux preuves ordonnées : CiphertextCommitmentEquality, puis BatchedRangeProofU64. Chaque preuve peut être référencée par offset inline non nul ou par compte context-state ; le compte Instructions Sysvar n’est ajouté qu’une seule fois lorsqu’au moins une preuve est inline.

Transfer confidentiel

TransferConfidentialTokens construit l'instruction Token-2022 ConfidentialTransferExtension::Transfer avec une balance source déchiffrable de 36 octets, deux ciphertexts auditeur ElGamal de 64 octets et trois preuves référencées dans l'ordre officiel : Equality, Grouped Ciphertext Validity à trois handles, puis Range U128. Les preuves peuvent utiliser indépendamment un offset inline non nul ou un compte context-state. Le crate ne génère aucun ciphertext, secret ou preuve.

Audit Transfer With Fee (pre.055)

Le contrat audité fixe le wire 27/13, 169 octets de payload et 171 octets de données d’instruction. Le payload Token-2022 réutilise uniquement SplTokenDecryptableBalance et deux SplTokenElGamalCiphertext. Le ciphertext de frais et les paramètres de frais restent portés par les contextes de preuve, pas par un nouveau champ opaque de l’intent Token-2022.

Transfer confidentiel avec frais

TransferConfidentialTokensWithFee construit l’instruction Token-2022 ConfidentialTransferExtension::TransferWithFee avec cinq références de preuve strictement ordonnées : equality, validité trois handles, percentage with fee, validité deux handles et range U256. Chaque preuve peut être référencée par offset non nul ou par compte context-state. Le crate valide uniquement les entrées opaques fournies ; il ne produit aucune preuve ni donnée secrète.

Confidential Transfer Fee public operations (pre.057)

The executor constructs the four proof-free public operations published by spl-token-2022-interface 3.1.1:

• initialize confidential transfer fee configuration before mint initialization;
• enable harvest to mint;
• disable harvest to mint;
• permissionless harvest of ordered, distinct source accounts to the mint.

The initialization keeps the optional configuration authority and the exact caller-provided 32-byte ElGamal public key. Harvest source lists use the same non-empty, unique and u8-bounded contract as public transfer-fee harvests. No ciphertext is decrypted or synthesized.

• withdraw_confidential_withheld_tokens_from_mint : retrait depuis le Mint avec preuve CiphertextCiphertextEquality inline ou context-state.

Confidential Transfer Fee — retrait multi-comptes (pre.059)

WithdrawConfidentialWithheldTokensFromAccounts construit le retrait direct des frais confidentiels depuis une liste ordonnée de Token Accounts vers un compte destination Confidential Transfer. Le Mint reste readonly, la destination est writable, puis viennent la référence de preuve, l’autorité withdraw-withheld, les signataires multisig et enfin les sources writable.

La liste de sources doit être non vide, unique et limitée à 255 comptes. Le nombre exact est encodé sur u8 dans le payload. La preuve exigée est CiphertextCiphertextEquality, référencée par offset inline non nul ou par compte context-state. Cette opération est sensible au front-running : tout changement d’un withheld ciphertext source entre la génération de la preuve et l’exécution invalide la preuve. Le parcours recommandé pour réduire ce risque reste harvest vers Mint puis retrait depuis le Mint.