add total weight changes

Author: 0xShuk

programs/core-attribute-voter/README.md

@@ -12,7 +12,8 @@ Core Attribute Voter allows DAOs to use NFT collections for governance voting wh
 
 Each configured collection specifies:
 - A **weight attribute key** (e.g. `"voting_power"`, `"tier"`) — the attribute name to read from each NFT
-- A **max weight** — a ceiling that caps any single NFT's voting power and represents the collection's max governance weight
+- A **max weight** — a ceiling that caps any single NFT's voting power
+- A **total weight** — the collection's contribution to the quorum denominator (`max_voter_weight`)
 - An **expected attribute authority** — the trusted authority that set the attributes
 
 When a voter submits their NFTs, the program:
@@ -32,20 +33,21 @@ When a voter submits their NFTs, the program:
 The maximum possible voting power across all configured collections:
 
 ```
-max_voter_weight = Σ collection.max_weight
+max_voter_weight = Σ collection.total_weight
 ```
 
-This is used by SPL Governance to calculate quorum thresholds. Unlike the nft-voter and core-voter plugins (where max weight = `collection_size × weight_per_nft`), attribute-based voting has variable per-NFT weights, so `max_weight` must be set by the realm authority to reflect the expected total voting power of each collection.
+This is used by SPL Governance to calculate quorum thresholds. Unlike the nft-voter and core-voter plugins (where max weight = `collection_size × weight_per_nft`), attribute-based voting has variable per-NFT weights, so `total_weight` must be set by the realm authority to reflect the expected total voting power of each collection.
 
-#### Setting `max_weight` correctly
+#### Setting `max_weight` and `total_weight` correctly
 
-`max_weight` plays a dual role — it caps individual NFT weights **and** feeds into the quorum denominator. Getting it right matters:
+- `max_weight` caps per-NFT voting power.
+- `total_weight` controls quorum denominator contribution for the collection.
 
 **Example 1 — Well-calibrated:**
 A collection of 50 NFTs where attributes range from 1–10, totalling ~200 across the collection.
 Setting `max_weight = 200` means:
 - Individual NFTs are capped at 200 (effectively uncapped since max attribute is 10)
-- Quorum denominator reflects the true total voting power
+- If `total_weight = 200`, quorum denominator reflects the true total voting power
 - A 60% quorum requires 120 voting power to pass
 
 **Example 2 — Set too low:**
@@ -61,8 +63,8 @@ Same collection, but `max_weight = 10000`.
 - Risk: quorum becomes unreachable since the collection only holds ~200 total power
 
 **Example 4 — Multiple collections:**
-Collection A: `max_weight = 500`, Collection B: `max_weight = 300`.
-- `max_voter_weight = 500 + 300 = 800`
+Collection A: `max_weight = 500`, `total_weight = 500`; Collection B: `max_weight = 300`, `total_weight = 300`.
+- `max_voter_weight = 500 + 300 = 800` (sum of `total_weight`)
 - A voter holding NFTs from both collections accumulates weight across them
 - 60% quorum requires 480 total voting power
 
@@ -103,6 +105,7 @@ create_max_voter_weight_record()
 
 configure_collection(
     max_weight: 100,
+    total_weight: 1000,
     weight_attribute_key: "voting_power",
     expected_attribute_authority: UpdateAuthority
 )
@@ -162,7 +165,8 @@ relinquish_nft_vote()
 
 | Parameter | Type | Constraints | Description |
 |---|---|---|---|
-| `max_weight` | `u64` | > 0 | Max governance weight for the collection. Caps individual NFT weights and is summed across collections for quorum calculation. Should reflect the expected total voting power of the collection. |
+| `max_weight` | `u64` | > 0 | Max governance weight per NFT (attribute cap per asset). |
+| `total_weight` | `u64` | > 0 | Collection's total governance contribution for quorum calculation. Summed across collections into `max_voter_weight`. |
 | `weight_attribute_key` | `String` | 1–32 characters | Attribute name to read from NFTs |
 | `expected_attribute_authority` | `PluginAuthority` | Must match plugin | Trusted authority for attribute validation |
 

programs/core-attribute-voter/src/error.rs

@@ -12,6 +12,9 @@ pub enum CoreNftAttributeVoterError {
     #[msg("Invalid max weight, must be greater than 0")]
     InvalidMaxWeight,
 
+    #[msg("Invalid total weight, must be greater than 0")]
+    InvalidTotalWeight,
+
     #[msg("Invalid MaxVoterWeightRecord Realm")]
     InvalidMaxVoterWeightRecordRealm,
 

programs/core-attribute-voter/src/instructions/configure_collection.rs

@@ -49,6 +49,7 @@ pub struct ConfigureCollection<'info> {
 pub fn configure_collection(
     ctx: Context<ConfigureCollection>,
     max_weight: u64,
+    total_weight: u64,
     weight_attribute_key: String,
     expected_attribute_authority: PluginAuthority,
 ) -> Result<()> {
@@ -71,6 +72,11 @@ pub fn configure_collection(
         CoreNftAttributeVoterError::InvalidMaxWeight
     );
 
+    require!(
+        total_weight > 0,
+        CoreNftAttributeVoterError::InvalidTotalWeight
+    );
+
     // Validate weight_attribute_key
     require!(
         !weight_attribute_key.is_empty() && weight_attribute_key.len() <= 32,
@@ -80,6 +86,7 @@ pub fn configure_collection(
     let collection_config = CollectionConfig {
         collection: collection_key,
         max_weight,
+        total_weight,
         weight_attribute_key,
         expected_attribute_authority,
         reserved: [0; 8],

programs/core-attribute-voter/src/lib.rs

@@ -52,11 +52,12 @@ pub mod core_attribute_voter {
     pub fn configure_collection(
         ctx: Context<ConfigureCollection>,
         max_weight: u64,
+        total_weight: u64,
         weight_attribute_key: String,
         expected_attribute_authority: mpl_core::types::PluginAuthority,
     ) -> Result<()> {
         log_version();
-        instructions::configure_collection(ctx, max_weight, weight_attribute_key, expected_attribute_authority)
+        instructions::configure_collection(ctx, max_weight, total_weight, weight_attribute_key, expected_attribute_authority)
     }
 
     pub fn cast_nft_vote<'a, 'b, 'c, 'info>(

programs/core-attribute-voter/src/state/collection_config.rs

@@ -8,12 +8,13 @@ pub struct CollectionConfig {
     pub collection: Pubkey,
 
     /// Maximum governance power weight of the collection
-    /// Serves as both the per-NFT weight cap and the quorum denominator contribution
-    /// (i.e. it is summed across collections to produce MaxVoterWeightRecord.max_voter_weight)
-    /// Should be set to the expected total voting power of the collection,
-    /// in the same unit/scale as the attribute values stored on the NFTs
+    /// Any NFT whose configured attribute value exceeds this cap is limited to this value.
     pub max_weight: u64,
 
+    /// Total governance power contribution of the collection to quorum denominator.
+    /// This value is summed across collections to produce MaxVoterWeightRecord.max_voter_weight.
+    pub total_weight: u64,
+
     /// The attribute key to read the voting weight from on each NFT
     /// The attribute value must be a valid u64 string
     pub weight_attribute_key: String,
@@ -27,8 +28,9 @@ pub struct CollectionConfig {
 }
 
 impl CollectionConfig {
-    /// Borsh serialized size: 32 (Pubkey) + 8 (u64) + 4+32 (String with max 32 chars) + 33 (PluginAuthority) + 8 (reserved)
-    pub const SERIALIZED_SIZE: usize = 32 + 8 + 36 + 33 + 8;
+    /// Borsh serialized size: 32 (Pubkey) + 8 (max_weight) + 8 (total_weight)
+    /// + 4+32 (String with max 32 chars) + 33 (PluginAuthority) + 8 (reserved)
+    pub const SERIALIZED_SIZE: usize = 32 + 8 + 8 + 36 + 33 + 8;
 
 }
 
@@ -37,6 +39,7 @@ impl Default for CollectionConfig {
         Self {
             collection: Pubkey::default(),
             max_weight: 0,
+            total_weight: 0,
             // Default to a 32-byte zero-padded string for deterministic sizing
             weight_attribute_key: "\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0".to_string(),
             expected_attribute_authority: PluginAuthority::Address { address: Pubkey::default() },

programs/core-attribute-voter/src/state/registrar.rs

@@ -68,7 +68,7 @@ impl Registrar {
         self.collection_configs
             .iter()
             .try_fold(0u64, |sum, cc| {
-                sum.checked_add(cc.max_weight)
+                sum.checked_add(cc.total_weight)
                     .ok_or_else(|| CoreNftAttributeVoterError::ArithmeticOverflow.into())
             })
     }

programs/core-attribute-voter/tests/configure_collection.rs

@@ -62,7 +62,7 @@ async fn test_configure_collection() -> Result<(), TransportError> {
     assert_eq!(max_voter_weight_record.max_voter_weight_expiry, None);
     assert_eq!(
         max_voter_weight_record.max_voter_weight,
-        registrar.collection_configs[0].max_weight
+        registrar.collection_configs[0].total_weight
     );
 
     Ok(())
@@ -505,6 +505,43 @@ async fn test_configure_collection_with_empty_weight_attribute_key_error(
     Ok(())
 }
 
+#[tokio::test]
+async fn test_configure_collection_with_zero_total_weight_error(
+) -> Result<(), TransportError> {
+    // Arrange
+    let mut core_voter_test = CoreVoterTest::start_new().await;
+
+    let realm_cookie = core_voter_test.governance.with_realm().await?;
+
+    let registrar_cookie = core_voter_test.with_registrar(&realm_cookie).await?;
+
+    let collection_cookie = core_voter_test.core.create_collection(Some(1)).await?;
+
+    let max_voter_weight_record_cookie = core_voter_test
+        .with_max_voter_weight_record(&registrar_cookie)
+        .await?;
+
+    // Act
+    let err = core_voter_test
+        .with_collection(
+            &registrar_cookie,
+            &collection_cookie,
+            &max_voter_weight_record_cookie,
+            Some(ConfigureCollectionArgs {
+                total_weight: Some(0),
+                ..Default::default()
+            }),
+        )
+        .await
+        .err()
+        .unwrap();
+
+    // Assert
+    assert_nft_voter_err(err, CoreNftAttributeVoterError::InvalidTotalWeight);
+
+    Ok(())
+}
+
 #[tokio::test]
 async fn test_configure_collection_with_too_long_weight_attribute_key_error(
 ) -> Result<(), TransportError> {

programs/core-attribute-voter/tests/program_test/core_voter_test.rs

@@ -57,6 +57,7 @@ pub struct CollectionConfigCookie {
 
 pub struct ConfigureCollectionArgs {
     pub max_weight: u64,
+    pub total_weight: Option<u64>,
     pub weight_attribute_key: String,
     pub expected_attribute_authority: mpl_core::types::PluginAuthority,
 }
@@ -65,6 +66,7 @@ impl Default for ConfigureCollectionArgs {
     fn default() -> Self {
         Self {
             max_weight: 1,
+            total_weight: None,
             weight_attribute_key: "weight".to_string(),
             expected_attribute_authority: mpl_core::types::PluginAuthority::UpdateAuthority,
         }
@@ -522,10 +524,12 @@ impl CoreVoterTest {
         signers_override: Option<&[&Keypair]>,
     ) -> Result<CollectionConfigCookie, BanksClientError> {
         let args = args.unwrap_or_default();
+        let total_weight = args.total_weight.unwrap_or(args.max_weight);
 
         let data =
             anchor_lang::InstructionData::data(&gpl_core_attribute_voter::instruction::ConfigureCollection {
                 max_weight: args.max_weight,
+                total_weight,
                 weight_attribute_key: args.weight_attribute_key.clone(),
                 expected_attribute_authority: args.expected_attribute_authority.clone(),
             });
@@ -556,6 +560,7 @@ impl CoreVoterTest {
         let collection_config = CollectionConfig {
             collection: collection_cookie.collection,
             max_weight: args.max_weight,
+            total_weight,
             weight_attribute_key: args.weight_attribute_key,
             expected_attribute_authority: args.expected_attribute_authority,
             reserved: [0; 8],

programs/core-attribute-voter/tests/update_max_voter_weight_record.rs

@@ -22,7 +22,8 @@ async fn test_update_collection_config_invalidates_max_voter_weight_record_expir
         .await?;
 
     let collection_1_size = 7;
-    let collection_1_weight = 5;
+    let collection_1_max_weight = 5;
+    let collection_1_total_weight = 40;
 
     let collection_cookie_1 = core_voter_test
         .core
@@ -36,7 +37,8 @@ async fn test_update_collection_config_invalidates_max_voter_weight_record_expir
             &collection_cookie_1,
             &max_voter_weight_record_cookie,
             Some(ConfigureCollectionArgs {
-                max_weight: collection_1_weight,
+                max_weight: collection_1_max_weight,
+                total_weight: Some(collection_1_total_weight),
                 ..Default::default()
             }),
         )
@@ -48,7 +50,8 @@ async fn test_update_collection_config_invalidates_max_voter_weight_record_expir
         .await?;
 
     let collection_2_size = 10;
-    let collection_2_weight = 2;
+    let collection_2_max_weight = 2;
+    let collection_2_total_weight = 30;
 
     // Generate a new collection and update the registrar with the additional collection
     // while invalidating max voter weight.
@@ -64,7 +67,8 @@ async fn test_update_collection_config_invalidates_max_voter_weight_record_expir
             &collection_cookie_2,
             &max_voter_weight_record_cookie,
             Some(ConfigureCollectionArgs {
-                max_weight: collection_2_weight,
+                max_weight: collection_2_max_weight,
+                total_weight: Some(collection_2_total_weight),
                 ..Default::default()
             }),
         )
@@ -83,7 +87,7 @@ async fn test_update_collection_config_invalidates_max_voter_weight_record_expir
     let _clock = core_voter_test.bench.get_clock().await;
 
     // Assert
-    let max_voter_weight_total = collection_1_weight + collection_2_weight;
+    let max_voter_weight_total = collection_1_total_weight + collection_2_total_weight;
 
     assert!(registrar.collection_configs.len() == 2);
     assert!(max_voter_weight_record.max_voter_weight_expiry.is_none());
@@ -110,7 +114,8 @@ async fn test_update_max_voter_weight_record_provides_valid_expirey() -> Result<
 
     // Set collection sizes and weights for collection_1
     let collection_1_size = 11;
-    let collection_1_weight = 4;
+    let collection_1_max_weight = 4;
+    let collection_1_total_weight = 44;
 
     let collection_cookie_1 = core_voter_test
         .core
@@ -124,7 +129,8 @@ async fn test_update_max_voter_weight_record_provides_valid_expirey() -> Result<
             &collection_cookie_1,
             &max_voter_weight_record_cookie,
             Some(ConfigureCollectionArgs {
-                max_weight: collection_1_weight,
+                max_weight: collection_1_max_weight,
+                total_weight: Some(collection_1_total_weight),
                 ..Default::default()
             }),
         )
@@ -145,7 +151,8 @@ async fn test_update_max_voter_weight_record_provides_valid_expirey() -> Result<
     // which also invalidates max_voter_weight_expirey.
 
     let collection_2_size = 9;
-    let collection_2_weight = 3;
+    let collection_2_max_weight = 3;
+    let collection_2_total_weight = 27;
     let collection_cookie_2 = core_voter_test
         .core
         .create_collection(Some(collection_2_size))
@@ -158,7 +165,8 @@ async fn test_update_max_voter_weight_record_provides_valid_expirey() -> Result<
             &collection_cookie_2,
             &max_voter_weight_record_cookie,
             Some(ConfigureCollectionArgs {
-                max_weight: collection_2_weight,
+                max_weight: collection_2_max_weight,
+                total_weight: Some(collection_2_total_weight),
                 ..Default::default()
             }),
         )
@@ -180,7 +188,7 @@ async fn test_update_max_voter_weight_record_provides_valid_expirey() -> Result<
         .await;
 
     // Assert
-    let max_voter_weight_total = collection_1_weight + collection_2_weight;
+    let max_voter_weight_total = collection_1_total_weight + collection_2_total_weight;
 
     assert!(registrar.collection_configs.len() == 2);
     assert!(max_voter_weight_record.max_voter_weight == max_voter_weight_total as u64);