From 19242f892ccf031e9f56577f4d00865ca3f18bac Mon Sep 17 00:00:00 2001
From: febo <febo@anza.xyz>
Date: Thu, 28 May 2026 11:58:40 +0100
Subject: [PATCH 01/10] Comment for I-02

---
 pinocchio/interface/src/instruction.rs | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/pinocchio/interface/src/instruction.rs b/pinocchio/interface/src/instruction.rs
index 01865cdf..57e48238 100644
--- a/pinocchio/interface/src/instruction.rs
+++ b/pinocchio/interface/src/instruction.rs
@@ -53,7 +53,13 @@ pub enum TokenInstruction {
     /// Multisignature accounts can used in place of any single owner/delegate
     /// accounts in any token instruction that require an owner/delegate to be
     /// present.  The variant field represents the number of signers (M)
-    /// required to validate this multisignature account.
+    /// required to validate this multisignature account. This number must be
+    /// less than or equal to the number of signers provided in the accounts
+    /// list, otherwise the multisignature account will be unusable.
+    ///
+    /// Note that M is not validated to be less than or equal to the number of
+    /// signers provided in the accounts list, so it is the caller's
+    /// responsibility to ensure a valid M value is provided.
     ///
     /// The [`TokenInstruction::InitializeMultisig`] instruction requires no
     /// signers and MUST be included within the same Transaction as the

From 5a6c35bfbb70e9af29d9139da8b574bdcfdb0f6e Mon Sep 17 00:00:00 2001
From: febo <febo@anza.xyz>
Date: Thu, 28 May 2026 11:59:31 +0100
Subject: [PATCH 02/10] Comment for I-04

---
 pinocchio/interface/src/instruction.rs | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/pinocchio/interface/src/instruction.rs b/pinocchio/interface/src/instruction.rs
index 57e48238..d5c26e6d 100644
--- a/pinocchio/interface/src/instruction.rs
+++ b/pinocchio/interface/src/instruction.rs
@@ -61,6 +61,11 @@ pub enum TokenInstruction {
     /// signers provided in the accounts list, so it is the caller's
     /// responsibility to ensure a valid M value is provided.
     ///
+    /// Duplicate signer accounts are not rejected. The caller must ensure each
+    /// signer is unique and appears only once in the accounts list, otherwise
+    /// a repeated signer can count more than once and effectively lower the
+    /// configured M threshold.
+    ///
     /// The [`TokenInstruction::InitializeMultisig`] instruction requires no
     /// signers and MUST be included within the same Transaction as the
     /// system program's `CreateAccount` instruction that creates the

From a043404ea6acccba94fe3a7d9b72d96abb737950 Mon Sep 17 00:00:00 2001
From: febo <febo@anza.xyz>
Date: Thu, 28 May 2026 13:46:01 +0100
Subject: [PATCH 03/10] Comment for I-06 and I-07

---
 pinocchio/interface/src/state/account.rs | 4 ++++
 pinocchio/interface/src/state/mint.rs    | 4 ++++
 pinocchio/interface/src/state/mod.rs     | 9 +++++++++
 3 files changed, 17 insertions(+)

diff --git a/pinocchio/interface/src/state/account.rs b/pinocchio/interface/src/state/account.rs
index 853f0a8b..ba6f5873 100644
--- a/pinocchio/interface/src/state/account.rs
+++ b/pinocchio/interface/src/state/account.rs
@@ -15,6 +15,10 @@ pub const INCINERATOR_ID: Pubkey =
 const SYSTEM_PROGRAM_ID: Pubkey = pinocchio_pubkey::pubkey!("11111111111111111111111111111111");
 
 /// Internal representation of a token account data.
+///
+/// Note that when loading an `Account` from bytes, this implementation does not
+/// check the validity of `COption` fields, since the trailing 3 bytes are ignored.
+/// As a result, it is possible to load an `Account` with invalid `COption` values.
 #[repr(C)]
 pub struct Account {
     /// The mint associated with this account
diff --git a/pinocchio/interface/src/state/mint.rs b/pinocchio/interface/src/state/mint.rs
index ba72d09e..d51e53fb 100644
--- a/pinocchio/interface/src/state/mint.rs
+++ b/pinocchio/interface/src/state/mint.rs
@@ -4,6 +4,10 @@ use {
 };
 
 /// Internal representation of a mint data.
+///
+/// Note that when loading a `Mint` from bytes, this implementation does not
+/// check the validity of `COption` fields, since the trailing 3 bytes are ignored.
+/// As a result, it is possible to load a `Mint` with invalid `COption` values.
 #[repr(C)]
 pub struct Mint {
     /// Optional authority used to mint new tokens. The mint authority may only
diff --git a/pinocchio/interface/src/state/mod.rs b/pinocchio/interface/src/state/mod.rs
index d04131d3..663bde4b 100644
--- a/pinocchio/interface/src/state/mod.rs
+++ b/pinocchio/interface/src/state/mod.rs
@@ -9,6 +9,15 @@ pub mod mint;
 pub mod multisig;
 
 /// Type alias for fields represented as `COption`.
+///
+/// Note that only the first byte of the 4-byte array is used to
+/// represent the `Option` discriminant, while the remaining 3 bytes
+/// are padding to ensure alignment. The program does not modify
+/// these padding bytes and leaves them as `0`.
+///
+/// Reading a `COption` value with nonzero trailing padding bytes
+/// does not result in an error, since they are ignored in this
+/// implementation.
 pub type COption<T> = ([u8; 4], T);
 
 /// Marker trait for types that can be cast from a raw pointer.

From 903fa9117d786373c51438f92ab8ecbdf088f342 Mon Sep 17 00:00:00 2001
From: febo <febo@anza.xyz>
Date: Thu, 28 May 2026 14:12:29 +0100
Subject: [PATCH 04/10] Comment for I-08

---
 pinocchio/interface/src/instruction.rs | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/pinocchio/interface/src/instruction.rs b/pinocchio/interface/src/instruction.rs
index d5c26e6d..0db38ce5 100644
--- a/pinocchio/interface/src/instruction.rs
+++ b/pinocchio/interface/src/instruction.rs
@@ -131,6 +131,8 @@ pub enum TokenInstruction {
 
     /// Revokes the delegate's authority.
     ///
+    /// Note that a delegate can revoke its own delegation.
+    ///
     /// Accounts expected by this instruction:
     ///
     ///   * Single owner

From 33be5f80918ba74ced81048c163f09546a9fcb84 Mon Sep 17 00:00:00 2001
From: febo <febo@anza.xyz>
Date: Thu, 28 May 2026 14:23:56 +0100
Subject: [PATCH 05/10] Comment for I-09

---
 pinocchio/interface/src/instruction.rs | 45 ++++++++++++++++++++++++++
 1 file changed, 45 insertions(+)

diff --git a/pinocchio/interface/src/instruction.rs b/pinocchio/interface/src/instruction.rs
index 0db38ce5..811d2c65 100644
--- a/pinocchio/interface/src/instruction.rs
+++ b/pinocchio/interface/src/instruction.rs
@@ -90,6 +90,9 @@ pub enum TokenInstruction {
     /// amounts of SOL and Tokens will be transferred to the destination
     /// account.
     ///
+    /// This instruction accepts multisignature accounts owned by either
+    /// the Token or Token-2022 programs.
+    ///
     /// Accounts expected by this instruction:
     ///
     ///   * Single owner/delegate
@@ -111,6 +114,9 @@ pub enum TokenInstruction {
     /// Approves a delegate.  A delegate is given the authority over tokens on
     /// behalf of the source account's owner.
     ///
+    /// This instruction accepts multisignature accounts owned by either
+    /// the Token or Token-2022 programs.
+    ///
     /// Accounts expected by this instruction:
     ///
     ///   * Single owner
@@ -133,6 +139,9 @@ pub enum TokenInstruction {
     ///
     /// Note that a delegate can revoke its own delegation.
     ///
+    /// This instruction accepts multisignature accounts owned by either
+    /// the Token or Token-2022 programs.
+    ///
     /// Accounts expected by this instruction:
     ///
     ///   * Single owner
@@ -150,6 +159,9 @@ pub enum TokenInstruction {
     /// Note that when setting a new account owner authority on a native
     /// token account, the current close authority (if any) will be removed.
     ///
+    /// This instruction accepts multisignature accounts owned by either
+    /// the Token or Token-2022 programs.
+    ///
     /// Accounts expected by this instruction:
     ///
     ///   * Single authority
@@ -170,6 +182,9 @@ pub enum TokenInstruction {
     /// Mints new tokens to an account.  The native mint does not support
     /// minting.
     ///
+    /// This instruction accepts multisignature accounts owned by either
+    /// the Token or Token-2022 programs.
+    ///
     /// Accounts expected by this instruction:
     ///
     ///   * Single authority
@@ -191,6 +206,9 @@ pub enum TokenInstruction {
     /// Burns tokens by removing them from an account.  `Burn` does not support
     /// accounts associated with the native mint, use `CloseAccount` instead.
     ///
+    /// This instruction accepts multisignature accounts owned by either
+    /// the Token or Token-2022 programs.
+    ///
     /// Accounts expected by this instruction:
     ///
     ///   * Single owner/delegate
@@ -212,6 +230,9 @@ pub enum TokenInstruction {
     /// Close an account by transferring all its SOL to the destination account.
     /// Non-native accounts may only be closed if its token amount is zero.
     ///
+    /// This instruction accepts multisignature accounts owned by either
+    /// the Token or Token-2022 programs.
+    ///
     /// Accounts expected by this instruction:
     ///
     ///   * Single owner
@@ -229,6 +250,9 @@ pub enum TokenInstruction {
     /// Freeze an Initialized account using the Mint's `freeze_authority` (if
     /// set).
     ///
+    /// This instruction accepts multisignature accounts owned by either
+    /// the Token or Token-2022 programs.
+    ///
     /// Accounts expected by this instruction:
     ///
     ///   * Single owner
@@ -245,6 +269,9 @@ pub enum TokenInstruction {
 
     /// Thaw a Frozen account using the Mint's `freeze_authority` (if set).
     ///
+    /// This instruction accepts multisignature accounts owned by either
+    /// the Token or Token-2022 programs.
+    ///
     /// Accounts expected by this instruction:
     ///
     ///   * Single owner
@@ -268,6 +295,9 @@ pub enum TokenInstruction {
     /// decimals value is checked by the caller.  This may be useful when
     /// creating transactions offline or within a hardware wallet.
     ///
+    /// This instruction accepts multisignature accounts owned by either
+    /// the Token or Token-2022 programs.
+    ///
     /// Accounts expected by this instruction:
     ///
     ///   * Single owner/delegate
@@ -297,6 +327,9 @@ pub enum TokenInstruction {
     /// decimals value is checked by the caller.  This may be useful when
     /// creating transactions offline or within a hardware wallet.
     ///
+    /// This instruction accepts multisignature accounts owned by either
+    /// the Token or Token-2022 programs.
+    ///
     /// Accounts expected by this instruction:
     ///
     ///   * Single owner
@@ -326,6 +359,9 @@ pub enum TokenInstruction {
     /// decimals value is checked by the caller.  This may be useful when
     /// creating transactions offline or within a hardware wallet.
     ///
+    /// This instruction accepts multisignature accounts owned by either
+    /// the Token or Token-2022 programs.
+    ///
     /// Accounts expected by this instruction:
     ///
     ///   * Single authority
@@ -354,6 +390,9 @@ pub enum TokenInstruction {
     /// by the caller. This may be useful when creating transactions offline or
     /// within a hardware wallet.
     ///
+    /// This instruction accepts multisignature accounts owned by either
+    /// the Token or Token-2022 programs.
+    ///
     /// Accounts expected by this instruction:
     ///
     ///   * Single owner/delegate
@@ -513,6 +552,9 @@ pub enum TokenInstruction {
     /// owned account by sending them to any other account, leaving behind only
     /// lamports for rent exemption.
     ///
+    /// This instruction accepts multisignature accounts owned by either
+    /// the Token or Token-2022 programs.
+    ///
     /// Accounts expected by this instruction:
     ///
     ///   * Single owner/delegate
@@ -531,6 +573,9 @@ pub enum TokenInstruction {
     ///
     /// This is useful to unwrap lamports from a wrapped SOL account.
     ///
+    /// This instruction accepts multisignature accounts owned by either
+    /// the Token or Token-2022 programs.
+    ///
     /// Accounts expected by this instruction:
     ///
     ///   * Single owner/delegate

From 48164e9ec8f5dd8c934a6a20b1a0d8104a50cba0 Mon Sep 17 00:00:00 2001
From: febo <febo@anza.xyz>
Date: Thu, 28 May 2026 14:40:47 +0100
Subject: [PATCH 06/10] Comment for I-10

---
 pinocchio/interface/src/instruction.rs | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/pinocchio/interface/src/instruction.rs b/pinocchio/interface/src/instruction.rs
index 811d2c65..e3b3be54 100644
--- a/pinocchio/interface/src/instruction.rs
+++ b/pinocchio/interface/src/instruction.rs
@@ -436,6 +436,11 @@ pub enum TokenInstruction {
     /// `system_instruction::transfer` to move lamports to a wrapped token
     /// account, and needs to have its token `amount` field updated.
     ///
+    /// The rent-exempt reserve is recomputed by the instruction using the Rent
+    /// sysvar, retrieved either through the syscall or passed as an extra account.
+    /// As a result, the token `amount` field value can increase or decrease
+    /// according to the rent-exempt reserve requirement.
+    ///
     /// Accounts expected by this instruction:
     ///
     ///   * Using runtime Rent sysvar

From 1093baaaa42f4d25a3c0b7880a13c6529de296fd Mon Sep 17 00:00:00 2001
From: febo <febo@anza.xyz>
Date: Thu, 28 May 2026 15:18:23 +0100
Subject: [PATCH 07/10] Comment for I-11

---
 pinocchio/interface/src/instruction.rs | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/pinocchio/interface/src/instruction.rs b/pinocchio/interface/src/instruction.rs
index e3b3be54..f1978936 100644
--- a/pinocchio/interface/src/instruction.rs
+++ b/pinocchio/interface/src/instruction.rs
@@ -544,6 +544,9 @@ pub enum TokenInstruction {
     /// Return data can be fetched using `sol_get_return_data` and deserializing
     /// the return data as a little-endian `u64`.
     ///
+    /// Note that the length of `ui_amount` is limited to `257` digits
+    /// (characters), including digits after the decimal point.
+    ///
     /// Accounts expected by this instruction:
     ///
     ///   0. `[]` The mint to calculate for.

From 93a95aa5e60aa3fc650b25c1054191fa47d4147a Mon Sep 17 00:00:00 2001
From: febo <febo@anza.xyz>
Date: Thu, 28 May 2026 15:21:21 +0100
Subject: [PATCH 08/10] Comment for I-12

---
 pinocchio/interface/src/instruction.rs | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/pinocchio/interface/src/instruction.rs b/pinocchio/interface/src/instruction.rs
index f1978936..8b9fb19b 100644
--- a/pinocchio/interface/src/instruction.rs
+++ b/pinocchio/interface/src/instruction.rs
@@ -512,7 +512,9 @@ pub enum TokenInstruction {
     /// before [`TokenInstruction::InitializeAccount`].
     ///
     /// No-ops in this version of the program, but is included for compatibility
-    /// with the Associated Token Account program.
+    /// with the Associated Token Account program. Note that when the instruction
+    /// is executed as part of a [`TokenInstruction::Batch`], the account must
+    /// be owned by the Token program.
     ///
     /// Accounts expected by this instruction:
     ///

From c805d6d95aa2c6aefe01dfe771be2724aba94d51 Mon Sep 17 00:00:00 2001
From: febo <febo@anza.xyz>
Date: Thu, 28 May 2026 15:35:09 +0100
Subject: [PATCH 09/10] Fix formatting

---
 pinocchio/interface/src/instruction.rs   | 12 ++++++------
 pinocchio/interface/src/state/account.rs |  5 +++--
 pinocchio/interface/src/state/mint.rs    |  5 +++--
 3 files changed, 12 insertions(+), 10 deletions(-)

diff --git a/pinocchio/interface/src/instruction.rs b/pinocchio/interface/src/instruction.rs
index 8b9fb19b..1dfc4330 100644
--- a/pinocchio/interface/src/instruction.rs
+++ b/pinocchio/interface/src/instruction.rs
@@ -437,9 +437,9 @@ pub enum TokenInstruction {
     /// account, and needs to have its token `amount` field updated.
     ///
     /// The rent-exempt reserve is recomputed by the instruction using the Rent
-    /// sysvar, retrieved either through the syscall or passed as an extra account.
-    /// As a result, the token `amount` field value can increase or decrease
-    /// according to the rent-exempt reserve requirement.
+    /// sysvar, retrieved either through the syscall or passed as an extra
+    /// account. As a result, the token `amount` field value can increase or
+    /// decrease according to the rent-exempt reserve requirement.
     ///
     /// Accounts expected by this instruction:
     ///
@@ -512,9 +512,9 @@ pub enum TokenInstruction {
     /// before [`TokenInstruction::InitializeAccount`].
     ///
     /// No-ops in this version of the program, but is included for compatibility
-    /// with the Associated Token Account program. Note that when the instruction
-    /// is executed as part of a [`TokenInstruction::Batch`], the account must
-    /// be owned by the Token program.
+    /// with the Associated Token Account program. Note that when the
+    /// instruction is executed as part of a [`TokenInstruction::Batch`],
+    /// the account must be owned by the Token program.
     ///
     /// Accounts expected by this instruction:
     ///
diff --git a/pinocchio/interface/src/state/account.rs b/pinocchio/interface/src/state/account.rs
index ba6f5873..05fd3e92 100644
--- a/pinocchio/interface/src/state/account.rs
+++ b/pinocchio/interface/src/state/account.rs
@@ -17,8 +17,9 @@ const SYSTEM_PROGRAM_ID: Pubkey = pinocchio_pubkey::pubkey!("1111111111111111111
 /// Internal representation of a token account data.
 ///
 /// Note that when loading an `Account` from bytes, this implementation does not
-/// check the validity of `COption` fields, since the trailing 3 bytes are ignored.
-/// As a result, it is possible to load an `Account` with invalid `COption` values.
+/// check the validity of `COption` fields, since the trailing 3 bytes are
+/// ignored. As a result, it is possible to load an `Account` with invalid
+/// `COption` values.
 #[repr(C)]
 pub struct Account {
     /// The mint associated with this account
diff --git a/pinocchio/interface/src/state/mint.rs b/pinocchio/interface/src/state/mint.rs
index d51e53fb..0c5afd10 100644
--- a/pinocchio/interface/src/state/mint.rs
+++ b/pinocchio/interface/src/state/mint.rs
@@ -6,8 +6,9 @@ use {
 /// Internal representation of a mint data.
 ///
 /// Note that when loading a `Mint` from bytes, this implementation does not
-/// check the validity of `COption` fields, since the trailing 3 bytes are ignored.
-/// As a result, it is possible to load a `Mint` with invalid `COption` values.
+/// check the validity of `COption` fields, since the trailing 3 bytes are
+/// ignored. As a result, it is possible to load a `Mint` with invalid `COption`
+/// values.
 #[repr(C)]
 pub struct Mint {
     /// Optional authority used to mint new tokens. The mint authority may only

From 953ed0aa5a599ce85efebfca8a3ed54cccb7440e Mon Sep 17 00:00:00 2001
From: febo <febo@anza.xyz>
Date: Thu, 28 May 2026 15:35:27 +0100
Subject: [PATCH 10/10] Add syscall keyword

---
 scripts/solana.dic | 1 +
 1 file changed, 1 insertion(+)

diff --git a/scripts/solana.dic b/scripts/solana.dic
index 62a3ad8e..9f3c5776 100644
--- a/scripts/solana.dic
+++ b/scripts/solana.dic
@@ -50,3 +50,4 @@ APY
 codama
 autogenerated
 sdk
+syscall