feat(stellar): add indexed get_campaigns_by_tag query (#540)

src/campaigns/create.rs

@@ -6,10 +6,11 @@ use crate::storage::{
     bump_instance_ttl, get_campaign_count, get_category_campaign_bucket,
     get_category_campaign_count, get_category_duration_cap, get_creation_disabled,
     get_creator_campaign_bucket, get_creator_campaign_count, get_max_campaign_funding_goal,
-    get_min_campaign_funding_goal, set_campaign, set_campaign_count, set_campaign_creator_index,
-    set_campaign_start_time, set_category_campaign_bucket, set_category_campaign_count,
-    set_creator_campaign_bucket, set_creator_campaign_count, set_revenue_pool,
-    CATEGORY_CAMPAIGNS_BUCKET_SIZE, CREATOR_CAMPAIGNS_BUCKET_SIZE,
+    get_min_campaign_funding_goal, get_tag_campaign_bucket, get_tag_campaign_count, set_campaign,
+    set_campaign_count, set_campaign_creator_index, set_campaign_start_time,
+    set_category_campaign_bucket, set_category_campaign_count, set_creator_campaign_bucket,
+    set_creator_campaign_count, set_revenue_pool, set_tag_campaign_bucket,
+    CATEGORY_CAMPAIGNS_BUCKET_SIZE, CREATOR_CAMPAIGNS_BUCKET_SIZE, TAG_CAMPAIGNS_BUCKET_SIZE,
 };
 use crate::types::{Campaign, Category, CreateCampaignParams, MaybePendingCreator};
 

src/lib.rs

@@ -596,6 +596,16 @@ impl ProofOfHeart {
         queries::get_campaigns_by_category(&env, category, offset, limit)
     }
 
+    /// Gets all campaigns matching a tag, using an index for efficient lookup (#540).
+    pub fn get_campaigns_by_tag(
+        env: Env,
+        tag: String,
+        offset: u32,
+        limit: u32,
+    ) -> soroban_sdk::Vec<Campaign> {
+        queries::get_campaigns_by_tag(&env, tag, offset, limit)
+    }
+
     pub fn get_creator_campaigns(
         env: Env,
         creator: Address,

src/queries.rs

@@ -4,8 +4,9 @@ use crate::storage::{
     get_active_campaign_count, get_campaign, get_campaign_count, get_cancelled_campaign_count,
     get_category_campaign_bucket, get_category_campaign_count, get_contribution,
     get_contributor_count, get_creator_campaign_bucket, get_creator_campaign_count,
-    get_platform_fee, get_token, get_total_raised_global, get_verified_campaign_count,
-    CATEGORY_CAMPAIGNS_BUCKET_SIZE, CREATOR_CAMPAIGNS_BUCKET_SIZE,
+    get_platform_fee, get_tag_campaign_bucket, get_tag_campaign_count, get_token,
+    get_total_raised_global, get_verified_campaign_count, CATEGORY_CAMPAIGNS_BUCKET_SIZE,
+    CREATOR_CAMPAIGNS_BUCKET_SIZE, TAG_CAMPAIGNS_BUCKET_SIZE,
 };
 use crate::types::{Campaign, Category, CreatorStats, PlatformReport, PlatformStats};
 
@@ -317,3 +318,56 @@ pub(crate) fn get_contributor_portfolio(
 
     portfolio
 }
+
+/// Lists campaigns by tag for efficient tag-based discovery (#540).
+///
+/// **Performance benefit:** Uses the tag index (`TagCampaigns`) instead of scanning all
+/// campaigns. For the common case where `limit == 0` (meta-query), we return just the
+/// count of campaigns for this tag without any campaign objects.
+pub(crate) fn get_campaigns_by_tag(
+    env: &Env,
+    tag: String,
+    offset: u32,
+    limit: u32,
+) -> soroban_sdk::Vec<Campaign> {
+    let mut campaigns = soroban_sdk::Vec::new(env);
+    if limit == 0 {
+        return campaigns;
+    }
+
+    let total = get_tag_campaign_count(env, tag.clone());
+    if offset >= total {
+        return campaigns;
+    }
+
+    let capped_limit = limit.min(crate::LIST_MAX_LIMIT);
+    let end = offset.saturating_add(capped_limit).min(total);
+
+    let mut position = offset;
+    while position < end {
+        let bucket_idx = position / TAG_CAMPAIGNS_BUCKET_SIZE;
+        let bucket = get_tag_campaign_bucket(env, tag.clone(), bucket_idx);
+        let bucket_start = bucket_idx * TAG_CAMPAIGNS_BUCKET_SIZE;
+        let mut idx_in_bucket = position - bucket_start;
+
+        let bucket_len = bucket.len();
+        while idx_in_bucket < bucket_len && position < end {
+            let campaign_id = bucket.get(idx_in_bucket).unwrap();
+            if let Some(campaign) = get_campaign(env, campaign_id) {
+                campaigns.push_back(campaign);
+            }
+            idx_in_bucket += 1;
+            position += 1;
+        }
+
+        if idx_in_bucket >= bucket_len {
+            position = if bucket_len == 0 {
+                bucket_start + TAG_CAMPAIGNS_BUCKET_SIZE
+            } else {
+                bucket_start + bucket_len
+            };
+        }
+    }
+
+    campaigns
+}

src/storage.rs

@@ -110,6 +110,8 @@ pub enum CampaignKey {
     /// Reverse mapping from campaign ID to its current creator, keyed by campaign ID.
     /// Enables O(1) ownership verification without scanning a creator's campaign bucket.
     CampaignCreatorIndex(u32),
+    /// Campaign ids grouped by tag as append-only creation index.
+    TagCampaigns(String),
 }
 
 /// Keys for contributor balances, caps, and contribution tracking.

src/types.rs

@@ -97,6 +97,8 @@ pub struct Campaign {
     pub deadline_extended: bool,
     /// Total live contributions remaining after refunds, used for revenue-sharing pro-rata.
     pub effective_amount_raised: i128,
+    /// Tags for categorizing and searching campaigns
+    pub tags: Vec<String>,
 }
 
 /// Aggregate platform metrics for dashboard and indexer consumers.