activator: backfill flex-algo node segments on topology events (RFC-18, PR 2/4)

CHANGELOG.md

@@ -57,6 +57,22 @@ All notable changes to this project will be documented in this file.
   - Add `twamp-debug` diagnostic tool for testing kernel timestamping support on switches; sends real TWAMP probes to verify which SO_TIMESTAMPING modes (RX/TX software/hardware/sched) actually deliver timestamps, and reports RTT statistics comparing userspace vs kernel timestamp sources
 - E2E Tests
   - Switch backward compatibility test to install versioned CLI binaries from GitHub releases instead of Cloudsmith apt repos; version enumeration now uses the GitHub API directly from Go rather than querying apt-cache inside the container
+- Smartcontract
+  - Add `TopologyInfo` onchain account for IS-IS flex-algo link classification: auto-assigned TE admin-group bit (1–62), derived flex-algo number (128 + bit), and constraint type (`include-any`/`include-all`); capped at 62 topologies via `AdminGroupBits` resource extension
+  - Add `link_topologies: Vec<Pubkey>` (capped at 8) and `link_flags: u8` (bit 0 = unicast-drained) to the `Link` account
+  - Add `include_topologies` to the `Tenant` account for topology-filtered routing opt-in
+  - Enforce UNICAST-DEFAULT topology existence as a precondition for link activation
+- CLI
+  - Add `doublezero link topology` subcommands: `create`, `delete`, `clear`, `list`, `backfill`
+  - Add `--link-topology <name>` and `--unicast-drained <bool>` flags to `doublezero link update`
+  - Add `--topology <name>` filter to `doublezero link list` (`default` = untagged links)
+  - Add `--include-topologies <name>` flag to `doublezero tenant update`
+  - Add `doublezero-admin migrate flex-algo [--dry-run]` to tag existing links with UNICAST-DEFAULT and backfill node segments
+- SDK
+  - Update Go, Python, and TypeScript SDKs with `TopologyInfo` deserialization and new `link_topologies`, `link_flags`, and `include_topologies` fields
+- Activator
+  - Automatically backfill flex-algo node segment IDs for all activated devices when a new `TopologyInfo` account is created onchain
+  - Automatically backfill existing topologies' node segments when a Vpnv4 loopback interface is activated on a device
 - Client
   - Add `doublezero_connection_info` Prometheus metric exposing connection metadata (user_type, network, current_device, metro, tunnel_name, tunnel_src, tunnel_dst) ([#3201](https://github.com/malbeclabs/doublezero/pull/3201))
   - Add `doublezero_connection_rtt_nanoseconds` and `doublezero_connection_loss_percentage` Prometheus metrics reporting RTT and packet loss to the current connected device

activator/src/process/device.rs

@@ -437,6 +437,13 @@ mod tests {
                 )
                 .returning(|_, _| Ok(Signature::new_unique()));
 
+            // After activating a vpnv4 loopback, the interface manager queries existing topologies
+            // to auto-backfill flex-algo node segments.
+            client
+                .expect_gets()
+                .with(predicate::eq(AccountType::Topology))
+                .returning(|_| Ok(HashMap::new()));
+
             // interfaces get checked on activated devices
             device.status = DeviceStatus::Activated;
 
@@ -662,6 +669,13 @@ mod tests {
             )
             .returning(|_, _| Ok(Signature::new_unique()));
 
+        // After activating a vpnv4 loopback, the interface manager queries existing topologies
+        // to auto-backfill flex-algo node segments.
+        client
+            .expect_gets()
+            .with(predicate::eq(AccountType::Topology))
+            .returning(|_| Ok(HashMap::new()));
+
         process_device_event(
             &client,
             &pubkey,

activator/src/process/iface_mgr.rs

@@ -1,16 +1,67 @@
 use crate::{idallocator::IDAllocator, ipblockallocator::IPBlockAllocator};
 use doublezero_program_common::types::NetworkV4;
 use doublezero_sdk::{
-    commands::device::interface::{
-        activate::ActivateDeviceInterfaceCommand, reject::RejectDeviceInterfaceCommand,
-        remove::RemoveDeviceInterfaceCommand, unlink::UnlinkDeviceInterfaceCommand,
+    commands::{
+        device::interface::{
+            activate::ActivateDeviceInterfaceCommand, reject::RejectDeviceInterfaceCommand,
+            remove::RemoveDeviceInterfaceCommand, unlink::UnlinkDeviceInterfaceCommand,
+        },
+        topology::{backfill::BackfillTopologyCommand, list::ListTopologyCommand},
     },
     CurrentInterfaceVersion, Device, DoubleZeroClient, InterfaceStatus, InterfaceType,
     LoopbackType,
 };
 use log::{error, info};
 use solana_sdk::pubkey::Pubkey;
 
+/// After a vpnv4 loopback is activated, automatically backfill flex-algo node segments
+/// on that device for every topology that currently exists on the ledger.
+fn backfill_device_for_all_topologies(
+    client: &dyn DoubleZeroClient,
+    device_pubkey: &Pubkey,
+    device_code: &str,
+) {
+    let topologies = match ListTopologyCommand.execute(client) {
+        Ok(t) => t,
+        Err(e) => {
+            error!(
+                "Failed to list topologies for backfill after loopback activation on {device_code}: {e}"
+            );
+            return;
+        }
+    };
+
+    if topologies.is_empty() {
+        return;
+    }
+
+    info!(
+        "Backfilling {} topology/topologies for device {device_code} after vpnv4 loopback activation",
+        topologies.len()
+    );
+
+    for topology in topologies.values() {
+        let cmd = BackfillTopologyCommand {
+            name: topology.name.clone(),
+            device_pubkeys: vec![*device_pubkey],
+        };
+        match cmd.execute(client) {
+            Ok(sig) => {
+                info!(
+                    "Backfilled topology '{}' for device {device_code}: {sig}",
+                    topology.name
+                );
+            }
+            Err(e) => {
+                error!(
+                    "Failed to backfill topology '{}' for device {device_code}: {e}",
+                    topology.name
+                );
+            }
+        }
+    }
+}
+
 /// Stateless interface manager for onchain allocation mode.
 /// Does not use local allocators - all allocation is handled by the smart contract.
 pub struct InterfaceMgrStateless<'a> {
@@ -74,6 +125,10 @@ impl<'a> InterfaceMgrStateless<'a> {
             &NetworkV4::default(),
             0,
         );
+
+        if iface.loopback_type == LoopbackType::Vpnv4 {
+            backfill_device_for_all_topologies(self.client, device_pubkey, &device.code);
+        }
     }
 
     /// Handle interface deletion (stateless mode - no local deallocation)
@@ -254,6 +309,10 @@ impl<'a> InterfaceMgr<'a> {
             &iface.ip_net,
             iface.node_segment_idx,
         );
+
+        if iface.loopback_type == LoopbackType::Vpnv4 {
+            backfill_device_for_all_topologies(self.client, device_pubkey, &device.code);
+        }
     }
 
     /// Handle interface deletion and resource cleanup

activator/src/process/link.rs

@@ -271,6 +271,9 @@ mod tests {
                 link_health: doublezero_serviceability::state::link::LinkHealth::Pending,
                 desired_status:
                     doublezero_serviceability::state::link::LinkDesiredStatus::Activated,
+
+                link_topologies: Vec::new(),
+                link_flags: 0,
             };
 
             let tunnel_cloned = tunnel.clone();
@@ -397,6 +400,9 @@ mod tests {
             side_z_iface_name: "Ethernet1".to_string(),
             link_health: doublezero_serviceability::state::link::LinkHealth::Pending,
             desired_status: doublezero_serviceability::state::link::LinkDesiredStatus::Activated,
+
+            link_topologies: Vec::new(),
+            link_flags: 0,
         };
 
         let link_cloned = link.clone();
@@ -457,6 +463,9 @@ mod tests {
                 link_health: doublezero_serviceability::state::link::LinkHealth::Pending,
                 desired_status:
                     doublezero_serviceability::state::link::LinkDesiredStatus::Activated,
+
+                link_topologies: Vec::new(),
+                link_flags: 0,
             };
 
             let tunnel_clone = tunnel.clone();
@@ -544,6 +553,9 @@ mod tests {
                 link_health: doublezero_serviceability::state::link::LinkHealth::Pending,
                 desired_status:
                     doublezero_serviceability::state::link::LinkDesiredStatus::Activated,
+
+                link_topologies: Vec::new(),
+                link_flags: 0,
             };
 
             // SDK command fetches the link internally
@@ -623,6 +635,9 @@ mod tests {
                 link_health: doublezero_serviceability::state::link::LinkHealth::Pending,
                 desired_status:
                     doublezero_serviceability::state::link::LinkDesiredStatus::Activated,
+
+                link_topologies: Vec::new(),
+                link_flags: 0,
             };
 
             // SDK command fetches the link internally

activator/src/processor.rs

@@ -18,7 +18,7 @@ use doublezero_sdk::{
     commands::{
         device::list::ListDeviceCommand, exchange::list::ListExchangeCommand,
         link::list::ListLinkCommand, location::list::ListLocationCommand,
-        user::list::ListUserCommand,
+        topology::backfill::BackfillTopologyCommand, user::list::ListUserCommand,
     },
     doublezeroclient::DoubleZeroClient,
     AccountData, Device, DeviceStatus, Exchange, GetGlobalConfigCommand, InterfaceType, Link,
@@ -65,6 +65,35 @@ pub struct ProcessorStateless<T: DoubleZeroClient> {
     multicastgroups: MulticastGroupMap,
 }
 
+/// Solana transaction account limit minus the 4 fixed accounts in BackfillTopologyCommand
+/// (topology PDA, segment_routing_ids PDA, globalstate, payer).
+const BACKFILL_BATCH_SIZE: usize = 28;
+
+/// Backfill flex-algo node segments on a set of devices for a given topology, batching
+/// device pubkeys to stay within Solana's per-transaction account limit.
+fn backfill_topology_for_devices(
+    client: &dyn DoubleZeroClient,
+    topology_name: &str,
+    device_pubkeys: &[Pubkey],
+) {
+    if device_pubkeys.is_empty() {
+        return;
+    }
+    info!(
+        "Backfilling topology '{topology_name}' for {} device(s)",
+        device_pubkeys.len()
+    );
+    for chunk in device_pubkeys.chunks(BACKFILL_BATCH_SIZE) {
+        let cmd = BackfillTopologyCommand {
+            name: topology_name.to_string(),
+            device_pubkeys: chunk.to_vec(),
+        };
+        if let Err(e) = cmd.execute(client) {
+            error!("Failed to backfill topology '{topology_name}' for device batch: {e}");
+        }
+    }
+}
+
 /// Reserve segment routing IDs and loopback IPs for devices that have active allocations.
 /// Devices in Activated, Drained, DeviceProvisioning, or LinkProvisioning states all
 /// hold allocated addresses that must not be handed out to new devices.
@@ -340,6 +369,14 @@ impl<T: DoubleZeroClient> Processor<T> {
                             error!("Error processing access pass event: {e}");
                         });
             }
+            AccountData::Topology(topology) => {
+                let device_pubkeys: Vec<Pubkey> = self.devices.keys().copied().collect();
+                backfill_topology_for_devices(
+                    self.client.as_ref(),
+                    &topology.name,
+                    &device_pubkeys,
+                );
+            }
             _ => {}
         };
         metrics::counter!("doublezero_activator_event_handled").increment(1);
@@ -439,6 +476,14 @@ impl<T: DoubleZeroClient> ProcessorStateless<T> {
                             error!("Error processing access pass event: {e}");
                         });
             }
+            AccountData::Topology(topology) => {
+                let device_pubkeys: Vec<Pubkey> = self.devices.keys().copied().collect();
+                backfill_topology_for_devices(
+                    self.client.as_ref(),
+                    &topology.name,
+                    &device_pubkeys,
+                );
+            }
             _ => {}
         };
         metrics::counter!("doublezero_activator_event_handled").increment(1);
@@ -761,6 +806,9 @@ mod tests {
             side_z_iface_name: "Ethernet1".to_string(),
             link_health: doublezero_serviceability::state::link::LinkHealth::Pending,
             desired_status: doublezero_serviceability::state::link::LinkDesiredStatus::Activated,
+
+            link_topologies: Vec::new(),
+            link_flags: 0,
         };
 
         let mut existing_links: HashMap<Pubkey, Link> = HashMap::new();
@@ -795,6 +843,9 @@ mod tests {
             side_z_iface_name: "Ethernet3".to_string(),
             link_health: doublezero_serviceability::state::link::LinkHealth::Pending,
             desired_status: doublezero_serviceability::state::link::LinkDesiredStatus::Activated,
+
+            link_topologies: Vec::new(),
+            link_flags: 0,
         };
 
         let new_link_cloned = new_link.clone();

client/doublezero/src/cli/link.rs

@@ -1,8 +1,15 @@
 use clap::{Args, Subcommand};
-use doublezero_cli::link::{
-    accept::AcceptLinkCliCommand, delete::*, dzx_create::CreateDZXLinkCliCommand, get::*,
-    latency::LinkLatencyCliCommand, list::*, sethealth::SetLinkHealthCliCommand, update::*,
-    wan_create::*,
+use doublezero_cli::{
+    link::{
+        accept::AcceptLinkCliCommand, delete::*, dzx_create::CreateDZXLinkCliCommand, get::*,
+        latency::LinkLatencyCliCommand, list::*, sethealth::SetLinkHealthCliCommand, update::*,
+        wan_create::*,
+    },
+    topology::{
+        backfill::BackfillTopologyCliCommand, clear::ClearTopologyCliCommand,
+        create::CreateTopologyCliCommand, delete::DeleteTopologyCliCommand,
+        list::ListTopologyCliCommand,
+    },
 };
 
 #[derive(Args, Debug)]
@@ -53,4 +60,27 @@ pub enum LinkCommands {
     // Hidden because this is an internal/operational command not intended for general CLI users.
     #[clap(hide = true)]
     SetHealth(SetLinkHealthCliCommand),
+    /// Manage link topologies
+    #[clap()]
+    Topology(TopologyLinkCommand),
+}
+
+#[derive(Args, Debug)]
+pub struct TopologyLinkCommand {
+    #[command(subcommand)]
+    pub command: TopologyCommands,
+}
+
+#[derive(Debug, Subcommand)]
+pub enum TopologyCommands {
+    /// Create a new topology
+    Create(CreateTopologyCliCommand),
+    /// Delete a topology
+    Delete(DeleteTopologyCliCommand),
+    /// Clear a topology from links
+    Clear(ClearTopologyCliCommand),
+    /// Backfill FlexAlgoNodeSegment entries on existing Vpnv4 loopbacks
+    Backfill(BackfillTopologyCliCommand),
+    /// List all topologies
+    List(ListTopologyCliCommand),
 }

client/doublezero/src/command/connect.rs

@@ -1072,6 +1072,7 @@ mod tests {
                 metro_routing: false,
                 route_liveness: false,
                 billing: TenantBillingConfig::default(),
+                include_topologies: vec![],
             };
 
             let mut tenants = HashMap::new();
@@ -1397,6 +1398,7 @@ mod tests {
                 metro_routing: false,
                 route_liveness: false,
                 billing: TenantBillingConfig::default(),
+                include_topologies: vec![],
             };
             tenants.insert(pk, tenant.clone());
             (pk, tenant)

client/doublezero/src/dzd_latency.rs

@@ -274,6 +274,7 @@ mod tests {
                     ip_net: NetworkV4::new(ip, 32).unwrap(),
                     node_segment_idx: 0,
                     user_tunnel_endpoint: true,
+                    flex_algo_node_segments: vec![],
                 })
             })
             .collect();

client/doublezero/src/main.rs

@@ -17,7 +17,7 @@ use crate::cli::{
         AirdropCommands, AuthorityCommands, FeatureFlagsCommands, FoundationAllowlistCommands,
         GlobalConfigCommands, QaAllowlistCommands,
     },
-    link::LinkCommands,
+    link::{LinkCommands, TopologyCommands},
     location::LocationCommands,
     user::UserCommands,
 };
@@ -232,6 +232,13 @@ async fn main() -> eyre::Result<()> {
             LinkCommands::Latency(args) => args.execute(&client, &mut handle),
             LinkCommands::Delete(args) => args.execute(&client, &mut handle),
             LinkCommands::SetHealth(args) => args.execute(&client, &mut handle),
+            LinkCommands::Topology(args) => match args.command {
+                TopologyCommands::Create(args) => args.execute(&client, &mut handle),
+                TopologyCommands::Delete(args) => args.execute(&client, &mut handle),
+                TopologyCommands::Clear(args) => args.execute(&client, &mut handle),
+                TopologyCommands::Backfill(args) => args.execute(&client, &mut handle),
+                TopologyCommands::List(args) => args.execute(&client, &mut handle),
+            },
         },
         Command::AccessPass(command) => match command.command {
             cli::accesspass::AccessPassCommands::Set(args) => args.execute(&client, &mut handle),

controlplane/controller/internal/controller/models.go

@@ -49,7 +49,7 @@ type Interface struct {
 
 // toInterface validates onchain data for a serviceability interface and converts it to a controller interface.
 func toInterface(iface serviceability.Interface) (Interface, error) {
-	if iface == (serviceability.Interface{}) {
+	if iface.IpNet == ([5]byte{}) && iface.Name == "" {
 		return Interface{}, errors.New("serviceability interface cannot be nil")
 	}