serviceability: add Feed catalog account and CRUD

CHANGELOG.md

@@ -9,6 +9,11 @@ All notable changes to this project will be documented in this file.
 - SDK
   - revdist Python SDK migrated to the async solana-py RPC API (solana-py 0.40.0 removed the sync `Client`). The `Client` read methods (`fetch_config`, `fetch_distribution`, etc.) are now coroutines and must be awaited; `new_rpc_client` returns an `AsyncClient`. (#3945)
 
+### Added
+
+- Serviceability
+  - `Feed` account: a catalog mapping `metro(exchange) → group-set`, managed by a catalog admin (`FEED_AUTHORITY` Permission or `FOUNDATION`) via `CreateFeed`/`UpdateFeed`/`DeleteFeed`. A feed with no metros imposes no restriction. (#1700)
+
 ### Changes
 
 ## [v0.28.0](https://github.com/malbeclabs/doublezero/compare/client/v0.27.1...client/v0.28.0) - 2026-06-26

smartcontract/cli/src/cli/command.rs

@@ -20,6 +20,7 @@ use crate::{
         contributor::{ContributorCliCommand, ContributorCommands},
         device::{DeviceCliCommand, DeviceCommands, InterfaceCommands},
         exchange::{ExchangeCliCommand, ExchangeCommands},
+        feed::{FeedCliCommand, FeedCommands},
         globalconfig::{
             AirdropCommands, AuthorityCommands, FeatureFlagsCommands, FoundationAllowlistCommands,
             GlobalConfigCliCommand, GlobalConfigCommands, QaAllowlistCommands,
@@ -62,6 +63,8 @@ pub enum ServiceabilityCommand {
     Location(LocationCliCommand),
     /// Manage exchanges
     Exchange(ExchangeCliCommand),
+    /// Manage feeds (metro→group-set catalog)
+    Feed(FeedCliCommand),
     /// Manage contributors
     Contributor(ContributorCliCommand),
     /// Manage permissions
@@ -170,6 +173,13 @@ impl ServiceabilityCommand {
                 ExchangeCommands::Get(args) => args.execute(ctx, client, out).await,
                 ExchangeCommands::Delete(args) => args.execute(ctx, client, out).await,
             },
+            Self::Feed(cmd) => match cmd.command {
+                FeedCommands::Create(args) => args.execute(ctx, client, out).await,
+                FeedCommands::Update(args) => args.execute(ctx, client, out).await,
+                FeedCommands::List(args) => args.execute(ctx, client, out).await,
+                FeedCommands::Get(args) => args.execute(ctx, client, out).await,
+                FeedCommands::Delete(args) => args.execute(ctx, client, out).await,
+            },
             Self::Contributor(cmd) => match cmd.command {
                 ContributorCommands::Create(args) => args.execute(ctx, client, out).await,
                 ContributorCommands::Update(args) => args.execute(ctx, client, out).await,

smartcontract/cli/src/cli/feed.rs

@@ -0,0 +1,28 @@
+use clap::{Args, Subcommand};
+
+use crate::feed::{create::*, delete::*, get::*, list::*, update::*};
+
+#[derive(Args, Debug)]
+pub struct FeedCliCommand {
+    #[command(subcommand)]
+    pub command: FeedCommands,
+}
+
+#[derive(Debug, Subcommand)]
+pub enum FeedCommands {
+    /// Create a new feed (catalog entry)
+    #[clap()]
+    Create(CreateFeedCliCommand),
+    /// Update a feed's name or metro map
+    #[clap()]
+    Update(UpdateFeedCliCommand),
+    /// List all feeds
+    #[clap()]
+    List(ListFeedCliCommand),
+    /// Get details for a specific feed
+    #[clap()]
+    Get(GetFeedCliCommand),
+    /// Delete a feed (must have no references)
+    #[clap()]
+    Delete(DeleteFeedCliCommand),
+}

smartcontract/cli/src/cli/mod.rs

@@ -15,6 +15,7 @@ pub use command::ServiceabilityCommand;
 pub mod contributor;
 pub mod device;
 pub mod exchange;
+pub mod feed;
 pub mod globalconfig;
 pub mod link;
 pub mod location;

smartcontract/cli/src/doublezerocommand.rs

@@ -38,6 +38,10 @@ use doublezero_sdk::{
             list::ListExchangeCommand, setdevice::SetDeviceExchangeCommand,
             update::UpdateExchangeCommand,
         },
+        feed::{
+            create::CreateFeedCommand, delete::DeleteFeedCommand, get::GetFeedCommand,
+            list::ListFeedCommand, update::UpdateFeedCommand,
+        },
         globalconfig::set::SetGlobalConfigCommand,
         globalstate::{
             init::InitGlobalStateCommand, setairdrop::SetAirdropCommand,
@@ -106,7 +110,7 @@ use doublezero_sdk::{
         },
     },
     telemetry::LinkLatencyStats,
-    DZClient, DZTransaction, Device, DoubleZeroClient, Exchange, GetGlobalConfigCommand,
+    DZClient, DZTransaction, Device, DoubleZeroClient, Exchange, Feed, GetGlobalConfigCommand,
     GetGlobalStateCommand, GlobalConfig, GlobalState, Link, Location, MulticastGroup,
     ResourceExtensionOwned, TopologyInfo, User,
 };
@@ -181,6 +185,12 @@ pub trait CliCommand {
     fn delete_exchange(&self, cmd: DeleteExchangeCommand) -> eyre::Result<Signature>;
     fn setdevice_exchange(&self, cmd: SetDeviceExchangeCommand) -> eyre::Result<Signature>;
 
+    fn create_feed(&self, cmd: CreateFeedCommand) -> eyre::Result<(Signature, Pubkey)>;
+    fn get_feed(&self, cmd: GetFeedCommand) -> eyre::Result<(Pubkey, Feed)>;
+    fn list_feed(&self, cmd: ListFeedCommand) -> eyre::Result<HashMap<Pubkey, Feed>>;
+    fn update_feed(&self, cmd: UpdateFeedCommand) -> eyre::Result<Signature>;
+    fn delete_feed(&self, cmd: DeleteFeedCommand) -> eyre::Result<Signature>;
+
     fn create_contributor(
         &self,
         cmd: CreateContributorCommand,
@@ -496,6 +506,21 @@ impl CliCommand for CliCommandImpl<'_> {
     fn setdevice_exchange(&self, cmd: SetDeviceExchangeCommand) -> eyre::Result<Signature> {
         cmd.execute(self.client)
     }
+    fn create_feed(&self, cmd: CreateFeedCommand) -> eyre::Result<(Signature, Pubkey)> {
+        cmd.execute(self.client)
+    }
+    fn get_feed(&self, cmd: GetFeedCommand) -> eyre::Result<(Pubkey, Feed)> {
+        cmd.execute(self.client)
+    }
+    fn list_feed(&self, cmd: ListFeedCommand) -> eyre::Result<HashMap<Pubkey, Feed>> {
+        cmd.execute(self.client)
+    }
+    fn update_feed(&self, cmd: UpdateFeedCommand) -> eyre::Result<Signature> {
+        cmd.execute(self.client)
+    }
+    fn delete_feed(&self, cmd: DeleteFeedCommand) -> eyre::Result<Signature> {
+        cmd.execute(self.client)
+    }
     fn create_contributor(
         &self,
         cmd: CreateContributorCommand,

smartcontract/cli/src/feed/create.rs

@@ -0,0 +1,42 @@
+use crate::{doublezerocommand::CliCommand, feed::parse_metro, validators::validate_code};
+use clap::Args;
+use doublezero_cli_core::{print_signature, require, CliContext, RequirementCheck};
+use doublezero_sdk::commands::feed::create::CreateFeedCommand;
+use solana_sdk::pubkey::Pubkey;
+use std::io::Write;
+
+#[derive(Args, Debug)]
+pub struct CreateFeedCliCommand {
+    /// Unique code for the feed (immutable; used as the PDA seed)
+    #[arg(long, value_parser = validate_code)]
+    pub code: String,
+    /// Human-readable name for the feed
+    #[arg(long)]
+    pub name: String,
+    /// Metro mapping `EXCHANGE_PK=GROUP_PK[,GROUP_PK...]` (repeatable). Omit for a feed with no
+    /// metro restriction (reachable from any exchange).
+    #[arg(long = "metro", value_parser = parse_metro)]
+    pub metros: Vec<(Pubkey, Vec<Pubkey>)>,
+}
+
+impl CreateFeedCliCommand {
+    pub async fn execute<C: CliCommand, W: Write>(
+        self,
+        _ctx: &CliContext,
+        client: &C,
+        out: &mut W,
+    ) -> eyre::Result<()> {
+        require!(
+            client,
+            RequirementCheck::KEYPAIR | RequirementCheck::BALANCE
+        );
+
+        let (signature, _pubkey) = client.create_feed(CreateFeedCommand {
+            code: self.code,
+            name: self.name,
+            metros: self.metros,
+        })?;
+
+        print_signature(out, &signature)
+    }
+}

smartcontract/cli/src/feed/delete.rs

@@ -0,0 +1,33 @@
+use crate::{doublezerocommand::CliCommand, validators::validate_pubkey_or_code};
+use clap::Args;
+use doublezero_cli_core::{print_signature, require, CliContext, RequirementCheck};
+use doublezero_sdk::commands::feed::{delete::DeleteFeedCommand, get::GetFeedCommand};
+use std::io::Write;
+
+#[derive(Args, Debug)]
+pub struct DeleteFeedCliCommand {
+    /// Feed pubkey or code to delete
+    #[arg(long, value_parser = validate_pubkey_or_code)]
+    pub pubkey: String,
+}
+
+impl DeleteFeedCliCommand {
+    pub async fn execute<C: CliCommand, W: Write>(
+        self,
+        _ctx: &CliContext,
+        client: &C,
+        out: &mut W,
+    ) -> eyre::Result<()> {
+        require!(
+            client,
+            RequirementCheck::KEYPAIR | RequirementCheck::BALANCE
+        );
+
+        let (pubkey, _feed) = client.get_feed(GetFeedCommand {
+            pubkey_or_code: self.pubkey,
+        })?;
+
+        let signature = client.delete_feed(DeleteFeedCommand { pubkey })?;
+        print_signature(out, &signature)
+    }
+}

smartcontract/cli/src/feed/get.rs

@@ -0,0 +1,52 @@
+use crate::{doublezerocommand::CliCommand, validators::validate_pubkey_or_code};
+use clap::Args;
+use doublezero_cli_core::{render_record, CliContext, OutputFormat};
+use doublezero_sdk::commands::feed::get::GetFeedCommand;
+use serde::Serialize;
+use std::io::Write;
+use tabled::Tabled;
+
+#[derive(Args, Debug)]
+pub struct GetFeedCliCommand {
+    /// Feed pubkey or code to get details for
+    #[arg(long, value_parser = validate_pubkey_or_code)]
+    pub pubkey: String,
+    /// Output as JSON
+    #[arg(long)]
+    pub json: bool,
+}
+
+#[derive(Tabled, Serialize)]
+struct FeedDisplay {
+    pub account: String,
+    pub code: String,
+    pub name: String,
+    /// Number of metros (exchanges) in the feed map. Empty ⇒ no metro restriction.
+    pub metros: usize,
+    pub reference_count: u32,
+    pub owner: String,
+}
+
+impl GetFeedCliCommand {
+    pub async fn execute<C: CliCommand, W: Write>(
+        self,
+        _ctx: &CliContext,
+        client: &C,
+        out: &mut W,
+    ) -> eyre::Result<()> {
+        let (pubkey, feed) = client.get_feed(GetFeedCommand {
+            pubkey_or_code: self.pubkey,
+        })?;
+
+        let display = FeedDisplay {
+            account: pubkey.to_string(),
+            code: feed.code,
+            name: feed.name,
+            metros: feed.metros.len(),
+            reference_count: feed.reference_count,
+            owner: feed.owner.to_string(),
+        };
+
+        render_record(out, &display, OutputFormat::from_flags(self.json, false))
+    }
+}

smartcontract/cli/src/feed/list.rs

@@ -0,0 +1,62 @@
+use crate::doublezerocommand::CliCommand;
+use clap::Args;
+use doublezero_cli_core::{render_collection, CliContext, OutputFormat};
+use doublezero_program_common::serializer;
+use doublezero_sdk::commands::feed::list::ListFeedCommand;
+use serde::Serialize;
+use solana_sdk::pubkey::Pubkey;
+use std::io::Write;
+use tabled::Tabled;
+
+#[derive(Args, Debug)]
+pub struct ListFeedCliCommand {
+    /// Output in JSON format
+    #[arg(long, default_value_t = false)]
+    pub json: bool,
+    /// Output in compact JSON format
+    #[arg(long, default_value_t = false)]
+    pub json_compact: bool,
+}
+
+#[derive(Tabled, Serialize)]
+pub struct FeedDisplay {
+    #[serde(serialize_with = "serializer::serialize_pubkey_as_string")]
+    pub account: Pubkey,
+    pub code: String,
+    pub name: String,
+    pub metros: usize,
+    pub reference_count: u32,
+    #[serde(serialize_with = "serializer::serialize_pubkey_as_string")]
+    pub owner: Pubkey,
+}
+
+impl ListFeedCliCommand {
+    pub async fn execute<C: CliCommand, W: Write>(
+        self,
+        _ctx: &CliContext,
+        client: &C,
+        out: &mut W,
+    ) -> eyre::Result<()> {
+        let feeds = client.list_feed(ListFeedCommand)?;
+
+        let mut displays: Vec<FeedDisplay> = feeds
+            .into_iter()
+            .map(|(pubkey, feed)| FeedDisplay {
+                account: pubkey,
+                code: feed.code,
+                name: feed.name,
+                metros: feed.metros.len(),
+                reference_count: feed.reference_count,
+                owner: feed.owner,
+            })
+            .collect();
+
+        displays.sort_by(|a, b| a.code.cmp(&b.code));
+
+        render_collection(
+            out,
+            displays,
+            OutputFormat::from_flags(self.json, self.json_compact),
+        )
+    }
+}

smartcontract/cli/src/feed/mod.rs

@@ -0,0 +1,49 @@
+pub mod create;
+pub mod delete;
+pub mod get;
+pub mod list;
+pub mod update;
+
+use solana_sdk::pubkey::Pubkey;
+use std::str::FromStr;
+
+/// Parse a `--metro` argument of the form `EXCHANGE_PK=GROUP_PK[,GROUP_PK...]` into
+/// `(exchange_pk, [group_pk, ...])`. An empty group list (`EXCHANGE_PK=`) is allowed.
+pub fn parse_metro(s: &str) -> Result<(Pubkey, Vec<Pubkey>), String> {
+    let (exchange, groups) = s
+        .split_once('=')
+        .ok_or_else(|| format!("expected EXCHANGE_PK=GROUP_PK[,GROUP_PK...], got '{s}'"))?;
+    let exchange_pk =
+        Pubkey::from_str(exchange.trim()).map_err(|e| format!("invalid exchange pubkey: {e}"))?;
+    let group_pks = groups
+        .split(',')
+        .map(str::trim)
+        .filter(|g| !g.is_empty())
+        .map(|g| Pubkey::from_str(g).map_err(|e| format!("invalid group pubkey '{g}': {e}")))
+        .collect::<Result<Vec<_>, _>>()?;
+    Ok((exchange_pk, group_pks))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::parse_metro;
+    use solana_sdk::pubkey::Pubkey;
+
+    #[test]
+    fn test_parse_metro() {
+        let ex = Pubkey::new_unique();
+        let g1 = Pubkey::new_unique();
+        let g2 = Pubkey::new_unique();
+        let (e, gs) = parse_metro(&format!("{ex}={g1},{g2}")).unwrap();
+        assert_eq!(e, ex);
+        assert_eq!(gs, vec![g1, g2]);
+
+        // No groups is allowed.
+        let (e, gs) = parse_metro(&format!("{ex}=")).unwrap();
+        assert_eq!(e, ex);
+        assert!(gs.is_empty());
+
+        assert!(parse_metro("not-a-pair").is_err());
+        assert!(parse_metro("bad=alsoBad").is_err());
+    }
+}