smartcontract: rename subscribe processor for clarity (#3499)

Resolves: #3498

## Summary
- Rename `process_subscribe_multicastgroup` →
`process_update_multicastgroup_subscription` and
`subscribe_user_to_multicastgroup` →
`update_user_multicastgroup_subscription` to reflect that these
functions handle both subscribe and unsubscribe
- Simplify the status validation guard to use a positive `is_subscribe`
check instead of double-negated `!is_unsubscribe_only`, making the
unsubscribe bypass for pending users easier to reason about

## Lines of Code
| Section | Added | Removed |
|---------|-------|---------|
| serviceability processor | +7 | -11 |
| serviceability entrypoint | +2 | -2 |
| create_subscribe processor | +2 | -2 |
| tests | +2 | -2 |

## Testing Verification
- Existing `multicastgroup_subscribe_test`,
`create_subscribe_user_test`, and `user_onchain_allocation_test` suites
cover all subscribe/unsubscribe paths including the pending user
regression added in #3494

Author: martinsander00

CHANGELOG.md

@@ -15,6 +15,7 @@ All notable changes to this project will be documented in this file.
 - Smartcontract
   - Allow `SubscribeMulticastGroup` for users in `Pending` status so that `CreateSubscribeUser` can be followed by additional subscribe calls before the activator runs ([#3521](https://github.com/malbeclabs/doublezero/pull/3521))
   - Add optional `owner` field to `UpdateMulticastGroup` instruction, allowing foundation members to reassign ownership of a multicast group ([#3527](https://github.com/malbeclabs/doublezero/pull/3527))
+  - Rename `SubscribeMulticastGroup` instruction variant to `UpdateMulticastGroupRoles` and rename associated processor functions, args struct, and SDK command to use "roles" terminology, clarifying they manage publisher/subscriber roles rather than just subscriptions
 - Geolocation
   - Add optional result destination to `GeolocationUser` so LocationOffsets can be sent to an alternate endpoint instead of the target IP; supports both IP and domain destinations (e.g., `185.199.108.1:9000` or `results.example.com:9000`); includes `SetResultDestination` onchain instruction, CLI `user set-result-destination` command, and Go SDK deserialization (backwards-compatible with existing accounts)
 - CLI

client/doublezero/src/command/connect.rs

@@ -15,7 +15,7 @@ use doublezero_sdk::{
         accesspass::get::GetAccessPassCommand,
         device::{get::GetDeviceCommand, list::ListDeviceCommand},
         multicastgroup::{
-            list::ListMulticastGroupCommand, subscribe::SubscribeMulticastGroupCommand,
+            list::ListMulticastGroupCommand, subscribe::UpdateMulticastGroupRolesCommand,
         },
         tenant::get::GetTenantCommand,
         user::{
@@ -621,7 +621,7 @@ impl ProvisioningCliCommand {
                 // Subscribe to remaining groups
                 for group_pk in all_group_pks.iter().skip(1) {
                     spinner.println(format!("    Subscribing to group: {group_pk}"));
-                    client.subscribe_multicastgroup(SubscribeMulticastGroupCommand {
+                    client.update_multicastgroup_roles(UpdateMulticastGroupRolesCommand {
                         user_pk,
                         group_pk: *group_pk,
                         client_ip: *client_ip,
@@ -647,13 +647,14 @@ impl ProvisioningCliCommand {
                             user_pk
                         ));
 
-                        let res = client.subscribe_multicastgroup(SubscribeMulticastGroupCommand {
-                            user_pk: *user_pk,
-                            group_pk: *group_pk,
-                            client_ip: *client_ip,
-                            publisher: true,
-                            subscriber: false,
-                        });
+                        let res =
+                            client.update_multicastgroup_roles(UpdateMulticastGroupRolesCommand {
+                                user_pk: *user_pk,
+                                group_pk: *group_pk,
+                                client_ip: *client_ip,
+                                publisher: true,
+                                subscriber: false,
+                            });
 
                         match res {
                             Ok(_) => {
@@ -676,13 +677,14 @@ impl ProvisioningCliCommand {
                             user_pk
                         ));
 
-                        let res = client.subscribe_multicastgroup(SubscribeMulticastGroupCommand {
-                            user_pk: *user_pk,
-                            group_pk: *group_pk,
-                            client_ip: *client_ip,
-                            publisher: false,
-                            subscriber: true,
-                        });
+                        let res =
+                            client.update_multicastgroup_roles(UpdateMulticastGroupRolesCommand {
+                                user_pk: *user_pk,
+                                group_pk: *group_pk,
+                                client_ip: *client_ip,
+                                publisher: false,
+                                subscriber: true,
+                            });
 
                         match res {
                             Ok(_) => {
@@ -757,7 +759,7 @@ impl ProvisioningCliCommand {
                 // Subscribe to remaining groups
                 for group_pk in all_group_pks.iter().skip(1) {
                     spinner.println(format!("    Subscribing to group: {group_pk}"));
-                    client.subscribe_multicastgroup(SubscribeMulticastGroupCommand {
+                    client.update_multicastgroup_roles(UpdateMulticastGroupRolesCommand {
                         user_pk,
                         group_pk: *group_pk,
                         client_ip: *client_ip,
@@ -1518,15 +1520,15 @@ mod tests {
         }
 
         #[allow(dead_code)]
-        pub fn expect_subscribe_multicastgroup(
+        pub fn expect_update_multicastgroup_roles(
             &mut self,
             user_pk: Pubkey,
             mcast_group_pk: Pubkey,
             client_ip: Ipv4Addr,
             publisher: bool,
             subscriber: bool,
         ) {
-            let expected_command = SubscribeMulticastGroupCommand {
+            let expected_command = UpdateMulticastGroupRolesCommand {
                 user_pk,
                 group_pk: mcast_group_pk,
                 client_ip,
@@ -1537,7 +1539,7 @@ mod tests {
             let users = self.users.clone();
             let provisioned = self.provisioned_services.clone();
             self.client
-                .expect_subscribe_multicastgroup()
+                .expect_update_multicastgroup_roles()
                 .times(1)
                 .with(predicate::eq(expected_command))
                 .returning_st(move |cmd| {
@@ -1887,7 +1889,7 @@ mod tests {
         let user_pk = fixture.add_user(&user);
 
         // Expect subscribe to second group
-        fixture.expect_subscribe_multicastgroup(
+        fixture.expect_update_multicastgroup_roles(
             user_pk,
             mcast_group2_pk,
             user.client_ip,
@@ -1963,8 +1965,8 @@ mod tests {
         user.publishers.push(mcast_group_pk);
         let user_pk = fixture.add_user(&user);
 
-        // Expect subscribe_multicastgroup call for the new subscriber group
-        fixture.expect_subscribe_multicastgroup(
+        // Expect update_multicastgroup_roles call for the new subscriber group
+        fixture.expect_update_multicastgroup_roles(
             user_pk,
             mcast_group2_pk,
             user.client_ip,
@@ -2005,8 +2007,8 @@ mod tests {
         user.subscribers.push(mcast_group_pk);
         let user_pk = fixture.add_user(&user);
 
-        // Expect subscribe_multicastgroup call for the new publisher group
-        fixture.expect_subscribe_multicastgroup(
+        // Expect update_multicastgroup_roles call for the new publisher group
+        fixture.expect_update_multicastgroup_roles(
             user_pk,
             mcast_group2_pk,
             user.client_ip,

smartcontract/cli/src/doublezerocommand.rs

@@ -78,7 +78,7 @@ use doublezero_sdk::{
             get::GetMulticastGroupCommand,
             list::ListMulticastGroupCommand,
             reject::RejectMulticastGroupCommand,
-            subscribe::SubscribeMulticastGroupCommand,
+            subscribe::UpdateMulticastGroupRolesCommand,
             update::UpdateMulticastGroupCommand,
         },
         permission::{
@@ -298,9 +298,9 @@ pub trait CliCommand {
         &self,
         cmd: DeactivateMulticastGroupCommand,
     ) -> eyre::Result<Signature>;
-    fn subscribe_multicastgroup(
+    fn update_multicastgroup_roles(
         &self,
-        cmd: SubscribeMulticastGroupCommand,
+        cmd: UpdateMulticastGroupRolesCommand,
     ) -> eyre::Result<Signature>;
     fn add_multicastgroup_pub_allowlist(
         &self,
@@ -737,9 +737,9 @@ impl CliCommand for CliCommandImpl<'_> {
     ) -> eyre::Result<Signature> {
         cmd.execute(self.client)
     }
-    fn subscribe_multicastgroup(
+    fn update_multicastgroup_roles(
         &self,
-        cmd: SubscribeMulticastGroupCommand,
+        cmd: UpdateMulticastGroupRolesCommand,
     ) -> eyre::Result<Signature> {
         cmd.execute(self.client)
     }

smartcontract/cli/src/user/subscribe.rs

@@ -7,7 +7,7 @@ use crate::{
 };
 use clap::Args;
 use doublezero_sdk::commands::{
-    multicastgroup::{get::GetMulticastGroupCommand, subscribe::SubscribeMulticastGroupCommand},
+    multicastgroup::{get::GetMulticastGroupCommand, subscribe::UpdateMulticastGroupRolesCommand},
     user::get::GetUserCommand,
 };
 use std::io::Write;
@@ -59,13 +59,14 @@ impl SubscribeUserCliCommand {
 
         // Subscribe to each group
         for group_pk in &group_pks {
-            let signature = client.subscribe_multicastgroup(SubscribeMulticastGroupCommand {
-                user_pk,
-                group_pk: *group_pk,
-                client_ip: user.client_ip,
-                publisher: self.publisher,
-                subscriber: self.subscriber,
-            })?;
+            let signature =
+                client.update_multicastgroup_roles(UpdateMulticastGroupRolesCommand {
+                    user_pk,
+                    group_pk: *group_pk,
+                    client_ip: user.client_ip,
+                    publisher: self.publisher,
+                    subscriber: self.subscriber,
+                })?;
             writeln!(out, "Subscribed to {group_pk}: {signature}")?;
         }
 
@@ -93,7 +94,7 @@ mod tests {
     use doublezero_sdk::{
         commands::{
             multicastgroup::{
-                get::GetMulticastGroupCommand, subscribe::SubscribeMulticastGroupCommand,
+                get::GetMulticastGroupCommand, subscribe::UpdateMulticastGroupRolesCommand,
             },
             user::get::GetUserCommand,
         },
@@ -172,8 +173,8 @@ mod tests {
             }))
             .returning(move |_| Ok((mgroup_pubkey, mgroup.clone())));
         client
-            .expect_subscribe_multicastgroup()
-            .with(predicate::eq(SubscribeMulticastGroupCommand {
+            .expect_update_multicastgroup_roles()
+            .with(predicate::eq(UpdateMulticastGroupRolesCommand {
                 user_pk: user_pubkey,
                 group_pk: mgroup_pubkey,
                 client_ip,
@@ -292,7 +293,7 @@ mod tests {
             }))
             .returning(move |_| Ok((mgroup_pubkey2, mgroup2.clone())));
         client
-            .expect_subscribe_multicastgroup()
+            .expect_update_multicastgroup_roles()
             .times(2)
             .returning(move |_| Ok(signature));
 

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

@@ -77,7 +77,7 @@ use crate::{
             delete::process_delete_multicastgroup,
             reactivate::process_reactivate_multicastgroup,
             reject::process_reject_multicastgroup,
-            subscribe::process_subscribe_multicastgroup,
+            subscribe::process_update_multicastgroup_roles,
             suspend::process_suspend_multicastgroup,
             update::process_update_multicastgroup,
         },
@@ -293,8 +293,8 @@ pub fn process_instruction(
         DoubleZeroInstruction::RemoveMulticastGroupSubAllowlist(value) => {
             process_remove_multicast_sub_allowlist(program_id, accounts, &value)?
         }
-        DoubleZeroInstruction::SubscribeMulticastGroup(value) => {
-            process_subscribe_multicastgroup(program_id, accounts, &value)?
+        DoubleZeroInstruction::UpdateMulticastGroupRoles(value) => {
+            process_update_multicastgroup_roles(program_id, accounts, &value)?
         }
         DoubleZeroInstruction::CreateSubscribeUser(value) => {
             process_create_subscribe_user(program_id, accounts, &value)?

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

@@ -63,7 +63,7 @@ use crate::processors::{
         delete::MulticastGroupDeleteArgs,
         reactivate::MulticastGroupReactivateArgs,
         reject::MulticastGroupRejectArgs,
-        subscribe::MulticastGroupSubscribeArgs,
+        subscribe::UpdateMulticastGroupRolesArgs,
         suspend::MulticastGroupSuspendArgs,
         update::MulticastGroupUpdateArgs,
     },
@@ -162,8 +162,8 @@ pub enum DoubleZeroInstruction {
     AddMulticastGroupSubAllowlist(AddMulticastGroupSubAllowlistArgs), // variant 56
     RemoveMulticastGroupSubAllowlist(RemoveMulticastGroupSubAllowlistArgs), // variant 57
 
-    SubscribeMulticastGroup(MulticastGroupSubscribeArgs), // variant 58
-    CreateSubscribeUser(UserCreateSubscribeArgs),         // variant 59
+    UpdateMulticastGroupRoles(UpdateMulticastGroupRolesArgs), // variant 58
+    CreateSubscribeUser(UserCreateSubscribeArgs),             // variant 59
 
     CreateContributor(ContributorCreateArgs),   // variant 60
     UpdateContributor(ContributorUpdateArgs),   // variant 61
@@ -304,7 +304,7 @@ impl DoubleZeroInstruction {
             55 => Ok(Self::RemoveMulticastGroupPubAllowlist(RemoveMulticastGroupPubAllowlistArgs::try_from(rest).unwrap())),
             56 => Ok(Self::AddMulticastGroupSubAllowlist(AddMulticastGroupSubAllowlistArgs::try_from(rest).unwrap())),
             57 => Ok(Self::RemoveMulticastGroupSubAllowlist(RemoveMulticastGroupSubAllowlistArgs::try_from(rest).unwrap())),
-            58 => Ok(Self::SubscribeMulticastGroup(MulticastGroupSubscribeArgs::try_from(rest).unwrap())),
+            58 => Ok(Self::UpdateMulticastGroupRoles(UpdateMulticastGroupRolesArgs::try_from(rest).unwrap())),
             59 => Ok(Self::CreateSubscribeUser(UserCreateSubscribeArgs::try_from(rest).unwrap())),
 
             60 => Ok(Self::CreateContributor(ContributorCreateArgs::try_from(rest).unwrap())),
@@ -438,8 +438,8 @@ impl DoubleZeroInstruction {
                 "RemoveMulticastGroupSubAllowlist".to_string()
             } // variant 57
 
-            Self::SubscribeMulticastGroup(_) => "SubscribeMulticastGroup".to_string(), // variant 58
-            Self::CreateSubscribeUser(_) => "CreateSubscribeUser".to_string(),         // variant 59
+            Self::UpdateMulticastGroupRoles(_) => "UpdateMulticastGroupRoles".to_string(), // variant 58
+            Self::CreateSubscribeUser(_) => "CreateSubscribeUser".to_string(), // variant 59
 
             Self::CreateContributor(_) => "CreateContributor".to_string(), // variant 60
             Self::UpdateContributor(_) => "UpdateContributor".to_string(), // variant 61
@@ -564,7 +564,7 @@ impl DoubleZeroInstruction {
             Self::DeleteMulticastGroup(args) => format!("{args:?}"), // variant 51
             Self::UpdateMulticastGroup(args) => format!("{args:?}"), // variant 52
             Self::DeactivateMulticastGroup(args) => format!("{args:?}"), // variant 53
-            Self::SubscribeMulticastGroup(args) => format!("{args:?}"), // variant 54
+            Self::UpdateMulticastGroupRoles(args) => format!("{args:?}"), // variant 54
             Self::AddMulticastGroupPubAllowlist(args) => format!("{args:?}"), // variant 55
             Self::RemoveMulticastGroupPubAllowlist(args) => format!("{args:?}"), // variant 56
             Self::AddMulticastGroupSubAllowlist(args) => format!("{args:?}"), // variant 57
@@ -1060,13 +1060,13 @@ mod tests {
             "RemoveMulticastGroupSubAllowlist",
         );
         test_instruction(
-            DoubleZeroInstruction::SubscribeMulticastGroup(MulticastGroupSubscribeArgs {
+            DoubleZeroInstruction::UpdateMulticastGroupRoles(UpdateMulticastGroupRolesArgs {
                 client_ip: [1, 2, 3, 4].into(),
                 publisher: false,
                 subscriber: true,
                 use_onchain_allocation: false,
             }),
-            "SubscribeMulticastGroup",
+            "UpdateMulticastGroupRoles",
         );
         test_instruction(
             DoubleZeroInstruction::CreateSubscribeUser(UserCreateSubscribeArgs {

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

@@ -27,7 +27,7 @@ use solana_program::{
 };
 use std::{fmt, net::Ipv4Addr};
 #[derive(BorshSerialize, BorshDeserializeIncremental, PartialEq, Clone)]
-pub struct MulticastGroupSubscribeArgs {
+pub struct UpdateMulticastGroupRolesArgs {
     #[incremental(default = Ipv4Addr::UNSPECIFIED)]
     pub client_ip: Ipv4Addr,
     pub publisher: bool,
@@ -36,7 +36,7 @@ pub struct MulticastGroupSubscribeArgs {
     pub use_onchain_allocation: bool,
 }
 
-impl fmt::Debug for MulticastGroupSubscribeArgs {
+impl fmt::Debug for UpdateMulticastGroupRolesArgs {
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
         write!(
             f,
@@ -54,13 +54,13 @@ pub struct SubscribeUserResult {
     pub publisher_list_transitioned: bool,
 }
 
-/// Toggle a user's multicast group subscription.
+/// Toggle a user's multicast group roles.
 ///
 /// Handles both create-time subscription (user lists start empty, only adds)
 /// and post-activation subscription changes (add/remove toggle). The caller is
 /// responsible for setting `user.status = Updating` when
 /// `publisher_list_transitioned` is true and the user is already activated.
-pub fn subscribe_user_to_multicastgroup(
+pub fn update_user_multicastgroup_roles(
     mgroup_account: &AccountInfo,
     accesspass: &AccessPass,
     user: &mut User,
@@ -130,10 +130,10 @@ pub fn subscribe_user_to_multicastgroup(
     })
 }
 
-pub fn process_subscribe_multicastgroup(
+pub fn process_update_multicastgroup_roles(
     program_id: &Pubkey,
     accounts: &[AccountInfo],
-    value: &MulticastGroupSubscribeArgs,
+    value: &UpdateMulticastGroupRolesArgs,
 ) -> ProgramResult {
     let num_accounts = accounts.len();
     let accounts_iter = &mut accounts.iter();
@@ -171,7 +171,7 @@ pub fn process_subscribe_multicastgroup(
     let system_program = next_account_info(accounts_iter)?;
 
     #[cfg(test)]
-    msg!("process_subscribe_multicastgroup({:?})", value);
+    msg!("process_update_multicastgroup_roles({:?})", value);
 
     // Check if the payer is a signer
     assert!(payer_account.is_signer, "Payer must be a signer");
@@ -201,12 +201,12 @@ pub fn process_subscribe_multicastgroup(
 
     // Parse and validate user
     let mut user: User = User::try_from(user_account)?;
-    // Allow subscribe for Pending users so that CreateSubscribeUser (which
-    // only takes one mgroup) can be followed by additional SubscribeMulticastGroup
-    // calls before the activator runs.  Also allow pure-unsubscribe (both false)
-    // for any status so cleanup works before activation.
-    let is_unsubscribe_only = !value.publisher && !value.subscriber;
-    if !is_unsubscribe_only
+    // Removing all roles is allowed for any status so that users
+    // created via CreateSubscribeUser can be cleaned up before activation.
+    // Adding roles is also allowed for Pending users so that CreateSubscribeUser
+    // (which only takes one mgroup) can be followed by additional calls.
+    let has_role = value.publisher || value.subscriber;
+    if has_role
         && user.status != UserStatus::Activated
         && user.status != UserStatus::Updating
         && user.status != UserStatus::Pending
@@ -254,7 +254,7 @@ pub fn process_subscribe_multicastgroup(
         }
     }
 
-    let result = subscribe_user_to_multicastgroup(
+    let result = update_user_multicastgroup_roles(
         mgroup_account,
         &accesspass,
         &mut user,