Feat: Optional Positional Accounts

.github/workflows/no-cashing-tests.yaml

@@ -81,6 +81,8 @@ jobs:
       fail-fast: false
       matrix:
         node:
+          - path: tests/optional/
+            name: optional.so
           - path: tests/events/
             name: events.so
           - path: examples/tutorial/basic-4/
@@ -124,6 +126,10 @@ jobs:
       - run: chmod +x ~/.cargo/bin/anchor
 
       - uses: actions/download-artifact@v3
+        with:
+          name: optional.so
+          path: tests/optional/target/deploy/
+      - uses: actions/download-artifact@v2
         with:
           name: events.so
           path: tests/events/target/deploy/
@@ -289,6 +295,8 @@ jobs:
             path: tests/cpi-returns
           - cmd: cd tests/multiple-suites && anchor test --skip-lint && npx tsc --noEmit
             path: tests/multiple-suites
+          - cmd: cd tests/optional && anchor test --skip-lint && npx tsc --noEmit
+            path: tests/optional
           - cmd: cd tests/multiple-suites-run-single && anchor test --skip-lint --run tests/should-run && npx tsc --noEmit
             path: tests/multiple-suites-run-single
           - cmd: cd tests/pda-derivation && anchor test --skip-lint && npx tsc --noEmit

.github/workflows/tests.yaml

@@ -139,6 +139,8 @@ jobs:
       fail-fast: false
       matrix:
         node:
+          - path: tests/optional/
+            name: optional.so
           - path: tests/events/
             name: events.so
           - path: examples/tutorial/basic-4/
@@ -182,6 +184,10 @@ jobs:
       - run: chmod +x ~/.cargo/bin/anchor
 
       - uses: actions/download-artifact@v3
+        with:
+          name: optional.so
+          path: tests/optional/target/deploy/
+      - uses: actions/download-artifact@v2
         with:
           name: events.so
           path: tests/events/target/deploy/
@@ -403,6 +409,8 @@ jobs:
             path: tests/multiple-suites
           - cmd: cd tests/multiple-suites-run-single && anchor test --skip-lint --run tests/should-run && npx tsc --noEmit
             path: tests/multiple-suites-run-single
+          - cmd: cd tests/optional && anchor test --skip-lint && npx tsc --noEmit
+            path: tests/optional
           - cmd: cd tests/pda-derivation && anchor test --skip-lint && npx tsc --noEmit
             path: tests/pda-derivation
           - cmd: cd tests/relations-derivation && anchor test --skip-lint && npx tsc --noEmit

client/example/Cargo.toml

@@ -12,6 +12,7 @@ anchor-client = { path = "../", features = ["debug"] }
 basic-2 = { path = "../../examples/tutorial/basic-2/programs/basic-2", features = ["no-entrypoint"] }
 basic-4 = { path = "../../examples/tutorial/basic-4/programs/basic-4", features = ["no-entrypoint"] }
 composite = { path = "../../tests/composite/programs/composite", features = ["no-entrypoint"] }
+optional = { path = "../../tests/optional/programs/optional", features = ["no-entrypoint"] }
 events = { path = "../../tests/events/programs/events", features = ["no-entrypoint"] }
 shellexpand = "2.1.0"
 anyhow = "1.0.32"

client/example/run-test.sh

@@ -26,6 +26,7 @@ main() {
     local basic_2_pid="Fg6PaFpoGXkYsidMpWTK6W2BeZ7FEfcYkg476zPFsLnS"
     local basic_4_pid="CwrqeMj2U8tFr1Rhkgwc84tpAsqbt9pTt2a4taoTADPr"
     local events_pid="2dhGsWUzy5YKUsjZdLHLmkNpUDAXkNa9MYWsPc4Ziqzy"
+    local optional_pid="FNqz6pqLAwvMSds2FYjR4nKV3moVpPNtvkfGFrqLKrgG"
 
     #
     # Bootup validator.
@@ -35,13 +36,14 @@ main() {
 				--bpf-program $basic_2_pid ../../examples/tutorial/basic-2/target/deploy/basic_2.so \
 				--bpf-program $basic_4_pid ../../examples/tutorial/basic-4/target/deploy/basic_4.so \
 				--bpf-program $events_pid ../../tests/events/target/deploy/events.so \
+				--bpf-program $optional_pid ../../tests/optional/target/deploy/optional.so \
 				> test-validator.log &
     sleep 5
 
     #
     # Run Test.
     #
-    cargo run -- --composite-pid $composite_pid --basic-2-pid $basic_2_pid --basic-4-pid $basic_4_pid --events-pid $events_pid
+    cargo run -- --composite-pid $composite_pid --basic-2-pid $basic_2_pid --basic-4-pid $basic_4_pid --events-pid $events_pid --optional-pid $optional_pid
 }
 
 cleanup() {

client/example/src/main.rs

@@ -12,6 +12,8 @@ use basic_2::instruction as basic_2_instruction;
 use basic_2::Counter;
 use events::instruction as events_instruction;
 use events::MyEvent;
+use optional::accounts::Initialize as OptionalInitialize;
+use optional::instruction as optional_instruction;
 // The `accounts` and `instructions` modules are generated by the framework.
 use basic_4::accounts as basic_4_accounts;
 use basic_4::basic_4::Counter as CounterState;
@@ -21,6 +23,7 @@ use clap::Parser;
 use composite::accounts::{Bar, CompositeUpdate, Foo, Initialize};
 use composite::instruction as composite_instruction;
 use composite::{DummyA, DummyB};
+use optional::account::{DataAccount, DataPda};
 use std::rc::Rc;
 use std::time::Duration;
 
@@ -34,6 +37,8 @@ pub struct Opts {
     basic_4_pid: Pubkey,
     #[clap(long)]
     events_pid: Pubkey,
+    #[clap(long)]
+    optional_pid: Pubkey,
 }
 
 // This example assumes a local validator is running with the programs
@@ -58,6 +63,7 @@ fn main() -> Result<()> {
     basic_2(&client, opts.basic_2_pid)?;
     basic_4(&client, opts.basic_4_pid)?;
     events(&client, opts.events_pid)?;
+    optional(&client, opts.optional_pid)?;
 
     // Success.
     Ok(())
@@ -226,3 +232,61 @@ pub fn basic_4(client: &Client, pid: Pubkey) -> Result<()> {
 
     Ok(())
 }
+
+// Runs a client for tests/optional.
+//
+// Make sure to run a localnet with the program deploy to run this example.
+fn optional(client: &Client, pid: Pubkey) -> Result<()> {
+    // Program client.
+    let program = client.program(pid);
+
+    // `Initialize` parameters.
+    let data_account_keypair = Keypair::new();
+
+    let data_account_key = data_account_keypair.pubkey();
+
+    let data_pda_seeds = &[DataPda::PREFIX.as_ref(), data_account_key.as_ref()];
+    let data_pda_key = Pubkey::find_program_address(data_pda_seeds, &pid).0;
+    let required_keypair = Keypair::new();
+    let value: u64 = 10;
+
+    // Build and send a transaction.
+
+    program
+        .request()
+        .instruction(system_instruction::create_account(
+            &program.payer(),
+            &required_keypair.pubkey(),
+            program
+                .rpc()
+                .get_minimum_balance_for_rent_exemption(DataAccount::LEN)?,
+            DataAccount::LEN as u64,
+            &program.id(),
+        ))
+        .signer(&data_account_keypair)
+        .signer(&required_keypair)
+        .accounts(OptionalInitialize {
+            payer: Some(program.payer()),
+            required: required_keypair.pubkey(),
+            system_program: Some(system_program::id()),
+            optional_account: Some(data_account_keypair.pubkey()),
+            optional_pda: None,
+        })
+        .args(optional_instruction::Initialize { value, key: pid })
+        .send()
+        .unwrap();
+
+    // Assert the transaction worked.
+    let required: DataAccount = program.account(required_keypair.pubkey())?;
+    assert_eq!(required.data, 0);
+
+    let optional_pda = program.account::<DataPda>(data_pda_key);
+    assert!(optional_pda.is_err());
+
+    let optional_account: DataAccount = program.account(data_account_keypair.pubkey())?;
+    assert_eq!(optional_account.data, value * 2);
+
+    println!("Optional success!");
+
+    Ok(())
+}

lang/Cargo.toml

@@ -9,6 +9,7 @@ license = "Apache-2.0"
 description = "Solana Sealevel eDSL"
 
 [features]
+allow-missing-optionals = ["anchor-derive-accounts/allow-missing-optionals"]
 init-if-needed = ["anchor-derive-accounts/init-if-needed"]
 derive = []
 default = []

lang/derive/accounts/Cargo.toml

@@ -12,6 +12,7 @@ edition = "2021"
 proc-macro = true
 
 [features]
+allow-missing-optionals = ["anchor-syn/allow-missing-optionals"]
 init-if-needed = ["anchor-syn/init-if-needed"]
 default = []
 anchor-debug = ["anchor-syn/anchor-debug"]

lang/src/accounts/mod.rs

@@ -13,6 +13,7 @@ pub mod cpi_state;
 #[doc(hidden)]
 #[allow(deprecated)]
 pub mod loader;
+pub mod option;
 pub mod program;
 #[doc(hidden)]
 #[allow(deprecated)]

lang/src/accounts/option.rs

@@ -0,0 +1,84 @@
+//! Option<T> type for optional accounts.
+//!
+//! # Example
+//! ```ignore
+//! #[derive(Accounts)]
+//! pub struct Example {
+//!     pub my_acc: Option<Account<'info, MyData>>
+//! }
+//! ```
+
+use std::collections::{BTreeMap, BTreeSet};
+
+use solana_program::account_info::AccountInfo;
+use solana_program::instruction::AccountMeta;
+use solana_program::pubkey::Pubkey;
+
+use crate::{
+    error::ErrorCode, Accounts, AccountsClose, AccountsExit, Result, ToAccountInfos, ToAccountMetas,
+};
+
+impl<'info, T: Accounts<'info>> Accounts<'info> for Option<T> {
+    fn try_accounts(
+        program_id: &Pubkey,
+        accounts: &mut &[AccountInfo<'info>],
+        ix_data: &[u8],
+        bumps: &mut BTreeMap<String, u8>,
+        reallocs: &mut BTreeSet<Pubkey>,
+    ) -> Result<Self> {
+        if accounts.is_empty() {
+            return if cfg!(feature = "allow-missing-optionals") {
+                // We don't care if accounts is empty (when this feature is active),
+                // so if that's the case we return None. This allows adding optional
+                // accounts at the end of the Accounts struct without causing a breaking
+                // change. This is safe and will error out if a required account is then
+                // added after the optional account and the accounts aren't passed in.
+                Ok(None)
+            } else {
+                // If the feature is inactive (it is off by default), then we error out
+                // like every other Account.
+                Err(ErrorCode::AccountNotEnoughKeys.into())
+            };
+        }
+
+        // If there are enough accounts, it will check the program_id and return
+        // None if it matches, popping the first account off the accounts vec.
+        if accounts[0].key == program_id {
+            *accounts = &accounts[1..];
+            Ok(None)
+        } else {
+            // If the program_id doesn't equal the account key, we default to
+            // the try_accounts implementation for the inner type and then wrap that with
+            // Some. This should handle all possible valid cases.
+            T::try_accounts(program_id, accounts, ix_data, bumps, reallocs).map(Some)
+        }
+    }
+}
+
+impl<'info, T: ToAccountInfos<'info>> ToAccountInfos<'info> for Option<T> {
+    fn to_account_infos(&self) -> Vec<AccountInfo<'info>> {
+        self.as_ref()
+            .map_or_else(Vec::new, |account| account.to_account_infos())
+    }
+}
+
+impl<T: ToAccountMetas> ToAccountMetas for Option<T> {
+    fn to_account_metas(&self, is_signer: Option<bool>) -> Vec<AccountMeta> {
+        self.as_ref()
+            .expect("Cannot run `to_account_metas` on None")
+            .to_account_metas(is_signer)
+    }
+}
+
+impl<'info, T: AccountsClose<'info>> AccountsClose<'info> for Option<T> {
+    fn close(&self, sol_destination: AccountInfo<'info>) -> Result<()> {
+        self.as_ref()
+            .map_or(Ok(()), |t| T::close(t, sol_destination))
+    }
+}
+
+impl<'info, T: AccountsExit<'info>> AccountsExit<'info> for Option<T> {
+    fn exit(&self, program_id: &Pubkey) -> Result<()> {
+        self.as_ref().map_or(Ok(()), |t| t.exit(program_id))
+    }
+}

lang/src/error.rs

@@ -105,6 +105,9 @@ pub enum ErrorCode {
     /// 2019 - A space constraint was violated
     #[msg("A space constraint was violated")]
     ConstraintSpace,
+    /// 2020 - A required account for the constraint is None
+    #[msg("A required account for the constraint is None")]
+    ConstraintAccountIsNone,
 
     // Require
     /// 2500 - A require expression was violated

lang/syn/Cargo.toml

@@ -9,6 +9,7 @@ rust-version = "1.59"
 edition = "2021"
 
 [features]
+allow-missing-optionals = []
 init-if-needed = []
 idl = []
 hash = []

lang/syn/src/codegen/accounts/__client_accounts.rs

@@ -61,9 +61,16 @@ pub fn generate(accs: &AccountsStruct) -> proc_macro2::TokenStream {
                 } else {
                     quote!()
                 };
-                quote! {
-                    #docs
-                    pub #name: anchor_lang::solana_program::pubkey::Pubkey
+                if f.is_optional {
+                    quote! {
+                        #docs
+                        pub #name: Option<anchor_lang::solana_program::pubkey::Pubkey>
+                    }
+                } else {
+                    quote! {
+                        #docs
+                        pub #name: anchor_lang::solana_program::pubkey::Pubkey
+                    }
                 }
             }
         })
@@ -93,8 +100,18 @@ pub fn generate(accs: &AccountsStruct) -> proc_macro2::TokenStream {
                     true => quote! { anchor_lang::solana_program::instruction::AccountMeta::new },
                 };
                 let name = &f.ident;
-                quote! {
-                    account_metas.push(#meta(self.#name, #is_signer));
+                if f.is_optional {
+                    quote! {
+                        if let Some(#name) = &self.#name {
+                            account_metas.push(#meta(*#name, #is_signer));
+                        } else {
+                            account_metas.push(anchor_lang::solana_program::instruction::AccountMeta::new_readonly(crate::ID, false));
+                        }
+                    }
+                } else {
+                    quote! {
+                        account_metas.push(#meta(self.#name, #is_signer));
+                    }
                 }
             }
         })