feat(multisig_add_vault): implement ix, sdk and tests

Author: vovacodes

programs/multisig/src/errors.rs

@@ -48,4 +48,6 @@ pub enum MultisigError {
     NoActions,
     #[msg("Missing account")]
     MissingAccount,
+    #[msg("Invalid `vault_index`")]
+    InvalidVaultIndex,
 }

programs/multisig/src/instructions/multisig_config.rs

@@ -38,6 +38,16 @@ pub struct MultisigSetConfigAuthorityArgs {
     pub memo: Option<String>,
 }
 
+#[derive(AnchorSerialize, AnchorDeserialize)]
+pub struct MultisigAddVaultArgs {
+    /// The next vault index to set as the latest used.
+    /// Must be the current `vault_index + 1`.
+    /// We pass it explicitly to make this instruction idempotent.
+    vault_index: u8,
+    /// Memo isn't used for anything, but is included in `ChangeThreshold` that can later be parsed and indexed.
+    pub memo: Option<String>,
+}
+
 #[derive(Accounts)]
 pub struct MultisigConfig<'info> {
     #[account(
@@ -72,6 +82,9 @@ impl MultisigConfig<'_> {
     }
 
     /// Add a member/key to the multisig and reallocate space if necessary.
+    ///
+    /// NOTE: This instruction must be called only by the `config_authority` if one is set (Controlled Multisig).
+    ///       Uncontrolled Mustisigs should use `config_transaction_create` instead.
     #[access_control(ctx.accounts.validate())]
     pub fn multisig_add_member(ctx: Context<Self>, args: MultisigAddMemberArgs) -> Result<()> {
         let MultisigAddMemberArgs { new_member, .. } = args;
@@ -110,6 +123,9 @@ impl MultisigConfig<'_> {
     }
 
     /// Remove a member/key from the multisig.
+    ///
+    /// NOTE: This instruction must be called only by the `config_authority` if one is set (Controlled Multisig).
+    ///       Uncontrolled Mustisigs should use `config_transaction_create` instead.
     #[access_control(ctx.accounts.validate())]
     pub fn multisig_remove_member(
         ctx: Context<Self>,
@@ -137,6 +153,8 @@ impl MultisigConfig<'_> {
         Ok(())
     }
 
+    /// NOTE: This instruction must be called only by the `config_authority` if one is set (Controlled Multisig).
+    ///       Uncontrolled Mustisigs should use `config_transaction_create` instead.
     #[access_control(ctx.accounts.validate())]
     pub fn multisig_change_threshold(
         ctx: Context<Self>,
@@ -156,6 +174,9 @@ impl MultisigConfig<'_> {
     }
 
     /// Set the `time_lock` config parameter for the multisig.
+    ///
+    /// NOTE: This instruction must be called only by the `config_authority` if one is set (Controlled Multisig).
+    ///       Uncontrolled Mustisigs should use `config_transaction_create` instead.
     #[access_control(ctx.accounts.validate())]
     pub fn multisig_set_time_lock(ctx: Context<Self>, args: MultisigSetTimeLockArgs) -> Result<()> {
         let multisig = &mut ctx.accounts.multisig;
@@ -170,6 +191,9 @@ impl MultisigConfig<'_> {
     }
 
     /// Set the multisig `config_authority`.
+    ///
+    /// NOTE: This instruction must be called only by the `config_authority` if one is set (Controlled Multisig).
+    ///       Uncontrolled Mustisigs should use `config_transaction_create` instead.
     #[access_control(ctx.accounts.validate())]
     pub fn multisig_set_config_authority(
         ctx: Context<Self>,
@@ -185,4 +209,29 @@ impl MultisigConfig<'_> {
 
         Ok(())
     }
+
+    /// Increment the multisig `vault_index`.
+    /// This doesn't actually "add" a new vault, because vaults are derived from the multisig address and index, so technically
+    /// they always exist. This just increments the index so that UIs can show the "used" vaults.
+    ///
+    /// NOTE: This instruction must be called only by the `config_authority` if one is set (Controlled Multisig).
+    ///       Uncontrolled Mustisigs should use `config_transaction_create` instead.
+    #[access_control(ctx.accounts.validate())]
+    pub fn multisig_add_vault(ctx: Context<Self>, args: MultisigAddVaultArgs) -> Result<()> {
+        let multisig = &mut ctx.accounts.multisig;
+
+        require!(
+            args.vault_index == multisig.vault_index + 1,
+            MultisigError::InvalidVaultIndex
+        );
+
+        multisig.vault_index = args.vault_index;
+
+        multisig.invariant()?;
+
+        // NOTE: we don't call `multisig.config_updated` here, because this doesn't
+        // affect the transactions by any means, and really just a UI feature.
+
+        Ok(())
+    }
 }

programs/multisig/src/lib.rs

@@ -58,6 +58,19 @@ pub mod multisig {
         MultisigConfig::multisig_set_config_authority(ctx, args)
     }
 
+    /// Increment the multisig `vault_index`.
+    /// This doesn't actually "add" a new vault, because vaults are derived from the multisig address and index, so technically
+    /// they always exist. This just increments the index so that UIs can show the "used" vaults.
+    ///
+    /// NOTE: This instruction must be called only by the `config_authority` if one is set (Controlled Multisig).
+    ///       Uncontrolled Mustisigs should use `config_transaction_create` instead.
+    pub fn multisig_add_vault(
+        ctx: Context<MultisigConfig>,
+        args: MultisigAddVaultArgs,
+    ) -> Result<()> {
+        MultisigConfig::multisig_add_vault(ctx, args)
+    }
+
     /// Create a new config transaction.
     pub fn config_transaction_create(
         ctx: Context<ConfigTransactionCreate>,

sdk/multisig/idl/multisig.json

@@ -241,6 +241,60 @@
         }
       ]
     },
+    {
+      "name": "multisigAddVault",
+      "docs": [
+        "Increment the multisig `vault_index`.",
+        "This doesn't actually \"add\" a new vault, because vaults are derived from the multisig address and index, so technically",
+        "they always exist. This just increments the index so that UIs can show the \"used\" vaults.",
+        "",
+        "NOTE: This instruction must be called only by the `config_authority` if one is set (Controlled Multisig).",
+        "Uncontrolled Mustisigs should use `config_transaction_create` instead."
+      ],
+      "accounts": [
+        {
+          "name": "multisig",
+          "isMut": true,
+          "isSigner": false
+        },
+        {
+          "name": "configAuthority",
+          "isMut": false,
+          "isSigner": true,
+          "docs": [
+            "Multisig `config_authority` that must authorize the configuration change."
+          ]
+        },
+        {
+          "name": "rentPayer",
+          "isMut": true,
+          "isSigner": true,
+          "isOptional": true,
+          "docs": [
+            "The account that will be charged in case the multisig account needs to reallocate space,",
+            "for example when adding a new member.",
+            "This is usually the same as `config_authority`, but can be a different account if needed."
+          ]
+        },
+        {
+          "name": "systemProgram",
+          "isMut": false,
+          "isSigner": false,
+          "isOptional": true,
+          "docs": [
+            "We might need it in case reallocation is needed."
+          ]
+        }
+      ],
+      "args": [
+        {
+          "name": "args",
+          "type": {
+            "defined": "MultisigAddVaultArgs"
+          }
+        }
+      ]
+    },
     {
       "name": "configTransactionCreate",
       "docs": [
@@ -1288,6 +1342,32 @@
         ]
       }
     },
+    {
+      "name": "MultisigAddVaultArgs",
+      "type": {
+        "kind": "struct",
+        "fields": [
+          {
+            "name": "vaultIndex",
+            "docs": [
+              "The next vault index to set as the latest used.",
+              "Must be the current `vault_index + 1`.",
+              "We pass it explicitly to make this instruction idempotent."
+            ],
+            "type": "u8"
+          },
+          {
+            "name": "memo",
+            "docs": [
+              "Memo isn't used for anything, but is included in `ChangeThreshold` that can later be parsed and indexed."
+            ],
+            "type": {
+              "option": "string"
+            }
+          }
+        ]
+      }
+    },
     {
       "name": "MultisigCreateArgs",
       "type": {
@@ -1810,6 +1890,11 @@
       "code": 6022,
       "name": "MissingAccount",
       "msg": "Missing account"
+    },
+    {
+      "code": 6023,
+      "name": "InvalidVaultIndex",
+      "msg": "Invalid `vault_index`"
     }
   ],
   "metadata": {