smartcontract: integrate Index into multicast group lifecycle

Wire Index account management into multicast group create, update,
delete, and close instructions. Update Rust SDK commands to derive
and pass Index PDAs. Add close_index/rename_index args to control
Index lifecycle during deactivation and updates. Update activator,
Go/Python/TypeScript SDKs, and all integration tests.

Author: martinsander00

CHANGELOG.md

@@ -13,6 +13,8 @@ All notable changes to this project will be documented in this file.
 - CLI
   - Allow incremental multicast group addition without disconnecting
   - Reset SIGPIPE to SIG_DFL at the start of main() in all 3 CLI binaries (doublezero, doublezero-geolocation, doublezero-admin) so the process exits silently like standard CLI tools
+- Smartcontract
+  - Add Index account for multicast group code uniqueness — PDA derived from entity type + lowercased code enforces unique codes onchain and enables O(1) code-to-pubkey lookup
 - SDK
   - Add Go SDK for shred subscription program with read-only account deserialization (epoch state, seat assignments, pricing, settlement, validator client rewards), PDA derivation helpers, RPC fetchers, compatibility tests, and a fetch example CLI
 - Tools

activator/src/process/multicastgroup.rs

@@ -398,13 +398,22 @@ mod tests {
             // Insert it first so it can be removed
             multicastgroups.insert(pubkey, multicastgroup.clone());
 
-            // Stateless mode: use_onchain_deallocation=true
+            // Mock get() for DeactivateMulticastGroupCommand which fetches the
+            // multicast group to derive the Index PDA
+            let mgroup_for_get = multicastgroup.clone();
+            client
+                .expect_get()
+                .with(predicate::eq(pubkey))
+                .returning(move |_| Ok(AccountData::MulticastGroup(mgroup_for_get.clone())));
+
+            // Stateless mode: use_onchain_deallocation=true, close_index=true
             client
                 .expect_execute_transaction()
                 .with(
                     predicate::eq(DoubleZeroInstruction::DeactivateMulticastGroup(
                         MulticastGroupDeactivateArgs {
                             use_onchain_deallocation: true,
+                            close_index: true,
                         },
                     )),
                     predicate::always(),

e2e/internal/qa/provisioning.go

@@ -600,4 +600,3 @@ func formatBandwidth(bps uint64) string {
 	}
 	return fmt.Sprintf("%d bps", bps)
 }
-

sdk/serviceability/go/state.go

@@ -25,6 +25,7 @@ const (
 	ResourceExtensionType AccountType = 12
 	TenantType            AccountType = 13
 	PermissionType        AccountType = 15
+	IndexType             AccountType = 16
 )
 
 type LocationStatus uint8

sdk/serviceability/python/serviceability/state.py

@@ -42,6 +42,7 @@ class AccountTypeEnum(IntEnum):
     ACCESS_PASS = 11
     TENANT = 13
     PERMISSION = 15
+    INDEX = 16
 
 
 # ---------------------------------------------------------------------------

sdk/serviceability/typescript/serviceability/state.ts

@@ -32,6 +32,7 @@ export const ACCOUNT_TYPE_CONTRIBUTOR = 10;
 export const ACCOUNT_TYPE_ACCESS_PASS = 11;
 export const ACCOUNT_TYPE_TENANT = 13;
 export const ACCOUNT_TYPE_PERMISSION = 15;
+export const ACCOUNT_TYPE_INDEX = 16;
 
 // ---------------------------------------------------------------------------
 // Enum string mappings

smartcontract/programs/doublezero-serviceability/src/instructions.rs

@@ -988,6 +988,7 @@ mod tests {
                 publisher_count: None,
                 subscriber_count: None,
                 use_onchain_allocation: false,
+                rename_index: false,
             }),
             "UpdateMulticastGroup",
         );
@@ -1005,13 +1006,15 @@ mod tests {
         test_instruction(
             DoubleZeroInstruction::DeleteMulticastGroup(MulticastGroupDeleteArgs {
                 use_onchain_deallocation: false,
+                close_index: false,
             }),
             "DeleteMulticastGroup",
         );
 
         test_instruction(
             DoubleZeroInstruction::DeactivateMulticastGroup(MulticastGroupDeactivateArgs {
                 use_onchain_deallocation: false,
+                close_index: false,
             }),
             "DeactivateMulticastGroup",
         );

smartcontract/programs/doublezero-serviceability/src/processors/multicastgroup/closeaccount.rs

@@ -1,10 +1,11 @@
 use crate::{
     error::DoubleZeroError,
-    pda::get_resource_extension_pda,
+    pda::{get_index_pda, get_resource_extension_pda},
     processors::resource::deallocate_ip,
     resource::ResourceType,
+    seeds::SEED_MULTICAST_GROUP,
     serializer::try_acc_close,
-    state::{globalstate::GlobalState, multicastgroup::*},
+    state::{globalstate::GlobalState, index::Index, multicastgroup::*},
 };
 use borsh::BorshSerialize;
 use borsh_incremental::BorshDeserializeIncremental;
@@ -24,14 +25,17 @@ pub struct MulticastGroupDeactivateArgs {
     /// When false, legacy behavior is used (no deallocation).
     #[incremental(default = false)]
     pub use_onchain_deallocation: bool,
+    /// When true, close the associated Index account alongside the multicast group.
+    #[incremental(default = false)]
+    pub close_index: bool,
 }
 
 impl fmt::Debug for MulticastGroupDeactivateArgs {
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
         write!(
             f,
-            "use_onchain_deallocation: {}",
-            self.use_onchain_deallocation
+            "use_onchain_deallocation: {}, close_index: {}",
+            self.use_onchain_deallocation, self.close_index
         )
     }
 }
@@ -47,10 +51,12 @@ pub fn process_closeaccount_multicastgroup(
     let owner_account = next_account_info(accounts_iter)?;
     let globalstate_account = next_account_info(accounts_iter)?;
 
-    // Optional: ResourceExtension account for on-chain deallocation (before payer)
-    // Account layout WITH ResourceExtension (use_onchain_deallocation = true):
-    //   [multicastgroup, owner, globalstate, multicast_group_block, payer, system]
-    // Account layout WITHOUT (legacy, use_onchain_deallocation = false):
+    // Optional accounts (before payer/system):
+    // Account layout WITH deallocation + index:
+    //   [multicastgroup, owner, globalstate, multicast_group_block, index, payer, system]
+    // Account layout WITHOUT deallocation, with index:
+    //   [multicastgroup, owner, globalstate, index, payer, system]
+    // Legacy (no deallocation, no index):
     //   [multicastgroup, owner, globalstate, payer, system]
     let resource_extension_account = if value.use_onchain_deallocation {
         let multicast_group_block_ext = next_account_info(accounts_iter)?;
@@ -59,6 +65,12 @@ pub fn process_closeaccount_multicastgroup(
         None
     };
 
+    let index_account = if value.close_index {
+        Some(next_account_info(accounts_iter)?)
+    } else {
+        None
+    };
+
     let payer_account = next_account_info(accounts_iter)?;
     let system_program = next_account_info(accounts_iter)?;
 
@@ -137,6 +149,24 @@ pub fn process_closeaccount_multicastgroup(
 
     try_acc_close(multicastgroup_account, owner_account)?;
 
+    // Close the Index account if provided
+    if let Some(index_acc) = index_account {
+        assert_eq!(index_acc.owner, program_id, "Invalid Index Account Owner");
+        assert!(index_acc.is_writable, "Index Account is not writable");
+
+        let (expected_index_pda, _) =
+            get_index_pda(program_id, SEED_MULTICAST_GROUP, &multicastgroup.code);
+        assert_eq!(index_acc.key, &expected_index_pda, "Invalid Index Pubkey");
+
+        let index = Index::try_from(index_acc)?;
+        assert_eq!(
+            index.pk, *multicastgroup_account.key,
+            "Index does not point to this MulticastGroup"
+        );
+
+        try_acc_close(index_acc, payer_account)?;
+    }
+
     #[cfg(test)]
     msg!("Deactivated: MulticastGroup closed");
 

smartcontract/programs/doublezero-serviceability/src/processors/multicastgroup/create.rs

@@ -1,14 +1,15 @@
 use crate::{
     error::DoubleZeroError,
-    pda::{get_multicastgroup_pda, get_resource_extension_pda},
+    pda::{get_index_pda, get_multicastgroup_pda, get_resource_extension_pda},
     processors::{resource::allocate_ip, validation::validate_program_account},
     resource::ResourceType,
-    seeds::{SEED_MULTICAST_GROUP, SEED_PREFIX},
+    seeds::{SEED_INDEX, SEED_MULTICAST_GROUP, SEED_PREFIX},
     serializer::{try_acc_create, try_acc_write},
     state::{
         accounttype::AccountType,
         feature_flags::{is_feature_enabled, FeatureFlag},
         globalstate::GlobalState,
+        index::Index,
         multicastgroup::*,
     },
 };
@@ -57,17 +58,18 @@ pub fn process_create_multicastgroup(
     let mgroup_account = next_account_info(accounts_iter)?;
     let globalstate_account = next_account_info(accounts_iter)?;
 
-    // Optional: ResourceExtension account for onchain allocation (before payer)
+    // Optional: ResourceExtension account for onchain allocation
     // Account layout WITH ResourceExtension (use_onchain_allocation = true):
-    //   [mgroup, globalstate, multicast_group_block, payer, system]
+    //   [mgroup, globalstate, multicast_group_block, index, payer, system]
     // Account layout WITHOUT (legacy, use_onchain_allocation = false):
-    //   [mgroup, globalstate, payer, system]
+    //   [mgroup, globalstate, index, payer, system]
     let resource_extension_account = if value.use_onchain_allocation {
         Some(next_account_info(accounts_iter)?)
     } else {
         None
     };
 
+    let index_account = next_account_info(accounts_iter)?;
     let payer_account = next_account_info(accounts_iter)?;
     let system_program = next_account_info(accounts_iter)?;
 
@@ -80,6 +82,7 @@ pub fn process_create_multicastgroup(
     // Validate and normalize code
     let code =
         validate_account_code(&value.code).map_err(|_| DoubleZeroError::InvalidAccountCode)?;
+    let lowercase_code = code.to_ascii_lowercase();
 
     // Check the owner of the accounts
     assert_eq!(
@@ -114,6 +117,10 @@ pub fn process_create_multicastgroup(
         return Err(ProgramError::AccountAlreadyInitialized);
     }
 
+    // Validate Index PDA (before code is moved into multicastgroup)
+    let (expected_index_pda, index_bump_seed) =
+        get_index_pda(program_id, SEED_MULTICAST_GROUP, &code);
+
     let mut multicastgroup = MulticastGroup {
         account_type: AccountType::MulticastGroup,
         owner: value.owner,
@@ -147,6 +154,16 @@ pub fn process_create_multicastgroup(
         multicastgroup.multicast_ip = allocate_ip(multicast_group_block_ext, 1)?.ip();
         multicastgroup.status = MulticastGroupStatus::Activated;
     }
+    assert_eq!(
+        index_account.key, &expected_index_pda,
+        "Invalid Index Pubkey"
+    );
+    assert!(index_account.is_writable, "Index Account is not writable");
+
+    // Uniqueness: index account must not already exist
+    if !index_account.data_is_empty() {
+        return Err(ProgramError::AccountAlreadyInitialized);
+    }
 
     try_acc_create(
         &multicastgroup,
@@ -161,6 +178,29 @@ pub fn process_create_multicastgroup(
             &[bump_seed],
         ],
     )?;
+
+    // Create the Index account pointing to the multicast group
+    let index = Index {
+        account_type: AccountType::Index,
+        pk: *mgroup_account.key,
+        bump_seed: index_bump_seed,
+    };
+
+    try_acc_create(
+        &index,
+        index_account,
+        payer_account,
+        system_program,
+        program_id,
+        &[
+            SEED_PREFIX,
+            SEED_INDEX,
+            SEED_MULTICAST_GROUP,
+            lowercase_code.as_bytes(),
+            &[index_bump_seed],
+        ],
+    )?;
+
     try_acc_write(&globalstate, globalstate_account, payer_account, accounts)?;
 
     Ok(())

smartcontract/programs/doublezero-serviceability/src/processors/multicastgroup/delete.rs

@@ -1,12 +1,14 @@
 use crate::{
     error::DoubleZeroError,
-    pda::get_resource_extension_pda,
+    pda::{get_index_pda, get_resource_extension_pda},
     processors::{resource::deallocate_ip, validation::validate_program_account},
     resource::ResourceType,
+    seeds::SEED_MULTICAST_GROUP,
     serializer::{try_acc_close, try_acc_write},
     state::{
         feature_flags::{is_feature_enabled, FeatureFlag},
         globalstate::GlobalState,
+        index::Index,
         multicastgroup::*,
     },
 };
@@ -28,14 +30,17 @@ pub struct MulticastGroupDeleteArgs {
     /// Requires ResourceExtension accounts and owner account.
     #[incremental(default = false)]
     pub use_onchain_deallocation: bool,
+    /// When true, close the associated Index account alongside the multicast group.
+    #[incremental(default = false)]
+    pub close_index: bool,
 }
 
 impl fmt::Debug for MulticastGroupDeleteArgs {
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
         write!(
             f,
-            "use_onchain_deallocation: {}",
-            self.use_onchain_deallocation
+            "use_onchain_deallocation: {}, close_index: {}",
+            self.use_onchain_deallocation, self.close_index
         )
     }
 }
@@ -50,10 +55,12 @@ pub fn process_delete_multicastgroup(
     let multicastgroup_account = next_account_info(accounts_iter)?;
     let globalstate_account = next_account_info(accounts_iter)?;
 
-    // Optional: additional accounts for atomic deallocation (before payer)
-    // Account layout WITH deallocation (use_onchain_deallocation = true):
-    //   [mgroup, globalstate, multicast_group_block, owner, payer, system]
-    // Account layout WITHOUT (legacy, use_onchain_deallocation = false):
+    // Optional: additional accounts for atomic deallocation
+    // Account layout WITH deallocation + index:
+    //   [mgroup, globalstate, multicast_group_block, owner, index, payer, system]
+    // Account layout WITHOUT deallocation, with index:
+    //   [mgroup, globalstate, index, payer, system]
+    // Legacy (no deallocation, no index):
     //   [mgroup, globalstate, payer, system]
     let deallocation_accounts = if value.use_onchain_deallocation {
         let multicast_group_block_ext = next_account_info(accounts_iter)?;
@@ -63,6 +70,12 @@ pub fn process_delete_multicastgroup(
         None
     };
 
+    let index_account = if value.close_index {
+        Some(next_account_info(accounts_iter)?)
+    } else {
+        None
+    };
+
     let payer_account = next_account_info(accounts_iter)?;
     let system_program = next_account_info(accounts_iter)?;
 
@@ -98,6 +111,7 @@ pub fn process_delete_multicastgroup(
     }
 
     let multicastgroup: MulticastGroup = MulticastGroup::try_from(multicastgroup_account)?;
+    let multicastgroup_code = multicastgroup.code.clone();
 
     if matches!(multicastgroup.status, MulticastGroupStatus::Deleting) {
         return Err(DoubleZeroError::InvalidStatus.into());
@@ -158,5 +172,25 @@ pub fn process_delete_multicastgroup(
         msg!("Deleted: {:?}", multicastgroup_account);
     }
 
+    // Close the Index account if provided
+    if let Some(index_acc) = index_account {
+        assert_eq!(index_acc.owner, program_id, "Invalid Index Account Owner");
+        assert!(index_acc.is_writable, "Index Account is not writable");
+
+        // Verify the Index PDA matches
+        let (expected_index_pda, _) =
+            get_index_pda(program_id, SEED_MULTICAST_GROUP, &multicastgroup_code);
+        assert_eq!(index_acc.key, &expected_index_pda, "Invalid Index Pubkey");
+
+        // Verify it's an Index account pointing to this multicast group
+        let index = Index::try_from(index_acc)?;
+        assert_eq!(
+            index.pk, *multicastgroup_account.key,
+            "Index does not point to this MulticastGroup"
+        );
+
+        try_acc_close(index_acc, payer_account)?;
+    }
+
     Ok(())
 }