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

[ben-malbeclabs]

Summary of Changes

• Adds TopologyInfo as a new onchain account type. DZF creates topologies with an auto-assigned IS-IS TE admin-group bit (1–62), a derived flex-algo number (128 + bit), and a constraint type (include-any or include-all). Topologies are enforced to be unique by name and limited to 62 total via an AdminGroupBits resource extension.
• Adds link_topologies: Vec<Pubkey> (capped at 8) and link_flags: u8 (bit 0 = unicast-drained) to the Link account. Link activation now requires the UNICAST-DEFAULT topology to exist — the activate processor enforces this.
• Adds include_topologies to the Tenant account, allowing tenants to opt into topology-filtered routing.
• Adds full topology lifecycle CLI commands: doublezero link topology create/delete/clear/list/backfill.
• Extends doublezero link update with --link-topology (assign a named topology, or default to clear) and --unicast-drained true/false.
• Extends doublezero link list with --topology <name> filter (default = untagged links).
• Extends doublezero tenant update with --include-topologies <name>.
• Adds doublezero-admin migrate flex-algo [--dry-run] to tag existing links with UNICAST-DEFAULT and backfill Vpnv4 loopback node segments for pre-existing accounts.
• Updates Rust, Go, Python, and TypeScript SDKs with TopologyInfo deserialization and the new link/tenant fields.

Stacked PRs: This is PR 1/4. #3475 (activator) and #3476 (controller) depend on this one. Merge this first. #3475 and #3476 can merge in either order; #3477 (e2e) requires all three.

RFC: rfcs/rfc18-link-classification-flex-algo.md

Diff Breakdown

Category	Files	Lines (+/-)	Net
Core logic (program + Rust SDK)	~55	+2,100 / -120	+1,980
CLI + admin commands	~25	+1,400 / -55	+1,345
Language SDKs (Go/Python/TS) + fixtures	~20	+430 / -15	+415
Tests	~25	+3,700 / -5	+3,695
Scaffolding	~10	+180 / -0	+180

Test-heavy: ~52% of additions are program integration tests. The topology test file alone is 2,410 lines.

Key files (click to expand)

• smartcontract/programs/doublezero-serviceability/tests/topology_test.rs — 2,410-line integration test suite covering all topology processor paths
• smartcontract/programs/doublezero-serviceability/src/processors/topology/create.rs — auto-assigns admin-group bit, derives flex-algo number, validates caps
• smartcontract/programs/doublezero-serviceability/src/processors/link/update.rs — topology assignment and link_flags bitmask handling
• smartcontract/programs/doublezero-serviceability/src/processors/link/activate.rs — enforces UNICAST-DEFAULT exists before activation
• smartcontract/programs/doublezero-serviceability/src/state/topology.rs — TopologyInfo account definition
• smartcontract/cli/src/topology/ — create, delete, clear (with auto-discovery), list, backfill
• smartcontract/cli/src/link/list.rs — --topology filter; displays topology and unicast-drained in output
• controlplane/doublezero-admin/src/cli/migrate.rs — migrate flex-algo with --dry-run support

Testing Verification

• make rust-test passes: 675+ tests across workspace, program integration tests, and account compat checks
• Topology lifecycle, update validation, and error cases fully covered by program integration tests
• Link activation failure without UNICAST-DEFAULT covered in tests/link_wan_test.rs
• Tenant include_topologies serialization verified against binary fixtures in Go, Python, and TypeScript SDKs

[nikw9944]

Code Review: RFC-18 Smartcontract — Flex-Algo Topology Accounts

Overall this is a well-structured, well-tested PR that cleanly introduces the topology lifecycle. The onchain processors have proper authorization checks, the CLI provides good UX with auto-discovery, and the test coverage is thorough. A few issues worth addressing:

Bug: Python SDK AccountType mismatch

sdk/serviceability/python/serviceability/state.py — TOPOLOGY = 16 but the Rust AccountType enum defines Topology = 17 (with Index = 16). This will cause Python SDK consumers to misidentify topology accounts as index accounts and vice versa.

The fixture JSON metadata (topology_info.json) also has "account_type": 16 which appears to be a copy from the Rust enum ordinal rather than the discriminant value. The binary fixture should be correct (generated from borsh::to_vec which uses the Rust discriminant of 17), but the JSON metadata is misleading.

Fix: Change TOPOLOGY = 16 to TOPOLOGY = 17 in the Python SDK, and update topology_info.json's account_type and AccountType.value from 16 to 17.

Bug: PR description says include-all but code has Exclude

The PR summary says "constraint type (include-any or include-all)" but the actual TopologyConstraint enum has IncludeAny = 0 and Exclude = 1. The CLI parser also accepts "include-any" or "exclude". Minor, but worth fixing the PR description to avoid confusion for reviewers of downstream PRs.

Observation: resolve_topology_names duplicated 4 times

The identical resolve_topology_names function is copy-pasted across link/get.rs, link/list.rs, tenant/get.rs, and tenant/list.rs. Consider extracting it to a shared utility (e.g., in smartcontract/cli/src/util.rs) to avoid drift. Not blocking, but worth a follow-up.

Observation: MTU validation removal

The PR removes the LINK_MTU check from process_create_link (link create processor) and process_update_link (link update processor). This is a separate behavioral change from topology support — links can now be created/updated with any MTU value. If this is intentional (not just an artifact of the topology work), it might be worth calling out explicitly in the PR description for reviewer awareness, since it changes the validation contract.

Observation: AdminGroupBits range vs PR description

PR description says "capped at 62 topologies" and "admin-group bit (1–62)" but the AdminGroupBits resource range is IdRange(1, 127), allowing up to 127 topologies. The code is more permissive than the description suggests — just a documentation nit.

Observation: topology_info.json missing trailing newline

Both topology_info.json and the updated link.json / tenant.json fixtures are missing a trailing newline (\ No newline at end of file). Minor, but most linters flag this.

Minor: Unused binding in topology/list.rs

let _ = get_topology_pda(&program_id, &t.name); // kept for symmetry; use key directly

This binding is explicitly unused (commented "kept for symmetry"). It should be removed — dead code with a comment explaining why it exists is worse than just not having it.

Design: Auto-tagging at activation

The process_activate_link processor unconditionally sets link.link_topologies = vec![*unicast_default_topology_account.key] — this overwrites any topology that might have been assigned between create and activate. In the current flow this is fine (links are created with empty topologies), but it's worth noting that any pre-activation topology assignment would be lost. A push + dedup approach would be more defensive, but given the lifecycle this is acceptable as-is.

---

Verdict: The AccountType mismatch in the Python SDK is a real bug that should be fixed before merge. The rest are minor observations. Solid work overall — the test coverage (52% of additions) and the stacked-PR approach are well done.