smartcontract: add flex-algo topology accounts and link classification (RFC-18, PR 1/4)

.gitignore

@@ -34,3 +34,4 @@ dev/.deploy/
 # Ignore the directory used for checking out the monitor tool in CI
 /doublezero_monitor/
 .claude/settings.local.json
+.worktrees/

CHANGELOG.md

@@ -63,6 +63,19 @@ All notable changes to this project will be documented in this file.
 - 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
+- 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
 
 ## [v0.15.0](https://github.com/malbeclabs/doublezero/compare/client/v0.14.0...client/v0.15.0) - 2026-03-27
 

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

@@ -764,6 +764,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();
@@ -798,6 +801,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")
 	}
 

controlplane/controller/internal/controller/server.go

@@ -348,22 +348,22 @@ func (c *Controller) updateStateCache(ctx context.Context) error {
 		cache.Ipv4BgpPeers = append(cache.Ipv4BgpPeers, candidateIpv4BgpPeer)
 
 		// determine if interface is in an onchain link and assign metrics
-		findLink := func(intf Interface) serviceability.Link {
-			for _, link := range links {
+		findLink := func(intf Interface) *serviceability.Link {
+			for i, link := range links {
 				if d.PubKey == base58.Encode(link.SideAPubKey[:]) && intf.Name == link.SideAIfaceName {
-					return link
+					return &links[i]
 				}
 				if d.PubKey == base58.Encode(link.SideZPubKey[:]) && intf.Name == link.SideZIfaceName {
-					return link
+					return &links[i]
 				}
 			}
-			return serviceability.Link{}
+			return nil
 		}
 
 		for i, iface := range d.Interfaces {
 			link := findLink(iface)
 
-			if link == (serviceability.Link{}) || (link.Status != serviceability.LinkStatusActivated && link.Status != serviceability.LinkStatusSoftDrained && link.Status != serviceability.LinkStatusHardDrained) {
+			if link == nil || (link.Status != serviceability.LinkStatusActivated && link.Status != serviceability.LinkStatusSoftDrained && link.Status != serviceability.LinkStatusHardDrained) {
 				d.Interfaces[i].IsLink = false
 				d.Interfaces[i].Metric = 0
 				d.Interfaces[i].LinkStatus = serviceability.LinkStatusPending

controlplane/doublezero-admin/src/cli/command.rs

@@ -2,8 +2,8 @@ use super::{multicast::MulticastCliCommand, sentinel::SentinelCliCommand};
 use crate::cli::{
     accesspass::AccessPassCliCommand, config::ConfigCliCommand, contributor::ContributorCliCommand,
     device::DeviceCliCommand, exchange::ExchangeCliCommand, globalconfig::GlobalConfigCliCommand,
-    link::LinkCliCommand, location::LocationCliCommand, permission::PermissionCliCommand,
-    tenant::TenantCliCommand, user::UserCliCommand,
+    link::LinkCliCommand, location::LocationCliCommand, migrate::MigrateCliCommand,
+    permission::PermissionCliCommand, tenant::TenantCliCommand, user::UserCliCommand,
 };
 use clap::{Args, Subcommand};
 use clap_complete::Shell;
@@ -69,6 +69,9 @@ pub enum Command {
     /// Sentinel admin commands
     #[command()]
     Sentinel(SentinelCliCommand),
+    /// Backfill link topologies and report Vpnv4 loopback gaps (RFC-18 migration)
+    #[command()]
+    Migrate(MigrateCliCommand),
     /// Export all data to files
     #[command()]
     Export(ExportCliCommand),