feat: add endorsement and governance changes (#67)

Author: Agilulfo1820

packages/contracts/.gitignore

@@ -15,4 +15,9 @@ artifacts
 docs
 
 # GalaxyMember metadata
-metadata/galaxyMember/metadata.zip
+metadata/galaxyMember/metadata.zip
+# Local upgrade worklog (not deployed yet)
+.upgrade-worklog.md
+
+# Endorsement migration output
+scripts/endorsement-migration/data/

packages/contracts/CLAUDE.md

@@ -2,6 +2,10 @@
 
 Instructions specific to `packages/contracts` directory.
 
+## Important Notes
+
+If you figure new rules out, or important things to remember for next time you will work on smart contracts changes, told to you by the devs, please add them to the file.
+
 ## Domain Knowledge
 
 ### VeBetterDAO Overview
@@ -181,6 +185,28 @@ const v6 = await upgradeProxy("GalaxyMemberV5", "GalaxyMember", await v5.getAddr
 expect(await v6.existingData()).to.equal(expectedValue)
 ```
 
+### CRITICAL: Upgrade Test Version Mismatch Pattern
+
+When working with upgrade tests, watch for this common bug:
+
+```typescript
+// Comment says V4 → V5
+// Upgrade X2EarnAppsV4 to X2EarnAppsV5
+const x2EarnAppsV5 = (await upgradeProxy("X2EarnAppsV4", "X2EarnApps", ...)) as X2EarnApps
+//                                                        ^^^^^^^^^^^ WRONG!
+```
+
+**Problem**: The test was written when V5 was the latest version. `"X2EarnApps"` referred to V5 back then. Now that we're at V8, `"X2EarnApps"` refers to V8, so this test incorrectly upgrades from V4 → V8, skipping V5/V6/V7.
+
+**Fix**: Always use explicit version names for intermediate upgrades:
+
+```typescript
+// Correct: explicit version
+const x2EarnAppsV5 = (await upgradeProxy("X2EarnAppsV4", "X2EarnAppsV5", ...)) as X2EarnAppsV5
+```
+
+**Rule**: Only use `"ContractName"` (without version suffix) when upgrading TO the latest version. For intermediate versions, always use `"ContractNameVN"`.
+
 ### Library Redeployment
 
 **Always redeploy all libraries when upgrading.** Libraries are redeployed fresh with each contract upgrade - there's no library versioning or reuse.
@@ -258,6 +284,26 @@ NEXT_PUBLIC_APP_ENV=local npx hardhat test --network hardhat test/YourTest.test.
 - `{contract}/v{N}-compatibility.test.ts` - Backward compatibility tests
 - `{contract}/{feature}.test.ts` - Feature-specific tests
 
+### CI Unit Test Shards
+
+Unit tests run in parallel via shards in `.github/workflows/unit-tests.yml`. Each shard has a `label` and runs tests matched by `grep` on that label. Test describe blocks use `@shard15x` (or similar) in their name to match.
+
+**When adding a new test shard** (e.g. for a new feature or coverage-focused suite):
+
+1. Add `@shard15x` (or next available) to the describe block name in the test file
+2. **Add the shard to `.github/workflows/unit-tests.yml`** in the `strategy.matrix` - otherwise CI will not run it
+
+Example matrix entry:
+
+```yaml
+- shard: shard15f
+  label: X-Apps - V8 Upgrade
+- shard: shard15g
+  label: X-Apps - EndorsementUtils Coverage
+```
+
+Shard assignments are documented in `packages/contracts/test/README.md`.
+
 ### Helper Functions
 
 Import from `./helpers`:

packages/contracts/CONTRACTS_CHANGELOG.md

@@ -30,20 +30,18 @@ Our contracts are upgradeable and versioned. See the [contracts changelog](/pack
 ## Testnet contract addresses
 
 ```
-  "B3TR": "0xbf64cf86894Ee0877C4e7d03936e35Ee8D8b864F",
-  "B3TRGovernor": "0xDF5E114D391CAC840529802fe8D01f6bdeBE41eC",
-  "Emissions": "0x148d21032F4a7b4aeF236E2E9C0c5bF62d10f8EB",
-  "GalaxyMember": "0xCf73039913e05aa1838d5869E72290d2b454C1E8",
-  "TimeLock": "0x30ee94F303643902a68aD8A7A6456cA69d763192",
-  "Treasury": "0x039893EBe092A2D22B08E2b029735D211bfF7F50",
-  "VOT3": "0xa704c45971995467696EE9544Da77DD42Bc9706E",
-  "VoterRewards": "0x2E47fc4aabB3403037fB5E1f38995E7a91Ce8Ed2",
-  "X2EarnApps": "0xcB23Eb1bBD5c07553795b9538b1061D0f4ABA153",
-  "X2EarnRewardsPool": "0x5F8f86B8D0Fa93cdaE20936d150175dF0205fB38",
-  "XAllocationPool": "0x9B9CA9D0C41Add1d204f90BA0E9a6844f1843A84",
-  "XAllocationVoting": "0x5859ff910d8b0c127364c98E24233b0af7443c1c",
-  "B3TRFaucet": "0x5e9c1F0f52aC6b5004122059053b00017EAfB561",
-  "RelayerRewardsPool": "0x92b5a7484970d9b2ad981e8135ff14e6f996dc04"
+"B3TR": "0x95761346d18244bb91664181bf91193376197088",
+"B3TRGovernor": "0xc30b4d0837f7e3706749655d8bde0c0f265dd81b",
+"Emissions": "0x66898f98409db20ed6a1bf0021334b7897eb0688",
+"GalaxyMember": "0x38a59fa7fd7039884465a0ff285b8c4b6fe394ca",
+"TimeLock": "0x835509222aa67c333a1cbf29bd341e014aba86c9",
+"Treasury": "0x3d531a80c05099c71b02585031f86a2988e0caca",
+"VOT3": "0x6e8b4a88d37897fc11f6ba12c805695f1c41f40e",
+"VoterRewards": "0x851ef91801899a4e7e4a3174a9300b3e20c957e8",
+"X2EarnApps": "0x0b54a094b877a25bdc95b4431eaa1e2206b1ddfe",
+"X2EarnRewardsPool": "0x2d2a2207c68a46fc79325d7718e639d1047b0d8b",
+"XAllocationPool": "0x6f7b4bc19b4dc99005b473b9c45ce2815bbe7533",
+"XAllocationVoting": "0x8800592c463f0b21ae08732559ee8e146db1d7b2"
 ```
 
 Notice: _VeBetter Passport contract deployed only on mainnet._

packages/contracts/README.md

@@ -81,9 +81,14 @@ import { IGalaxyMember } from "./interfaces/IGalaxyMember.sol";
  * - Difference from V4: Updated all libraries to use new version of IVoterRewards that supports GM Upgrades.
  * ------------------ VERSION 6 ------------------
  * - Updated all libraries to use new version of IVoterRewards that supports GM Rewards Pool.
- ------------------ VERSION 7 ------------------
+ * ------------------ VERSION 7 ------------------
  * - Added proposal type concept, STANDARD (0n) for existing proposals and GRANT (1n) for new grants proposals.
  * - Added deposit threshold cap based on proposal type.
+ * ------------------ VERSION 8 ------------------
+ * - No changes from V7 (placeholder for future reference).
+ * ------------------ VERSION 9 ------------------
+ * - Added reason parameter to cancel function for providing cancellation rationale.
+ * - Added ProposalCanceledWithReason event.
  */
 contract B3TRGovernor is
   IB3TRGovernor,
@@ -537,7 +542,7 @@ contract B3TRGovernor is
    * @return string The version of the governor
    */
   function version() external pure returns (string memory) {
-    return "8";
+    return "9";
   }
 
   /**
@@ -814,13 +819,15 @@ contract B3TRGovernor is
    * @param values The list of values to send
    * @param calldatas The list of call data
    * @param descriptionHash The hash of the description
+   * @param reason The reason for canceling the proposal
    * @return uint256 The proposal id
    */
   function cancel(
     address[] memory targets,
     uint256[] memory values,
     bytes[] memory calldatas,
-    bytes32 descriptionHash
+    bytes32 descriptionHash,
+    string memory reason
   ) external returns (uint256) {
     GovernorStorageTypes.GovernorStorage storage $ = getGovernorStorage();
     return
@@ -831,7 +838,8 @@ contract B3TRGovernor is
         targets,
         values,
         calldatas,
-        descriptionHash
+        descriptionHash,
+        reason
       );
   }
 

packages/contracts/contracts/B3TRGovernor.sol

@@ -60,6 +60,7 @@ import { IX2EarnRewardsPool } from "./interfaces/IX2EarnRewardsPool.sol";
  * - Track the unallocated funds for each round
  * - Added admin function to manually set the unallocated funds for a given round
  * - Added a getter to see if all apps have claimed their rewards for a given round
+ * - Fix allocations with zero votes
  */
 contract XAllocationPool is IXAllocationPool, AccessControlUpgradeable, ReentrancyGuardUpgradeable, UUPSUpgradeable {
   using Checkpoints for Checkpoints.Trace208; // Checkpoints library for managing the voting mechanism used in the XAllocationVoting contract
@@ -268,10 +269,8 @@ contract XAllocationPool is IXAllocationPool, AccessControlUpgradeable, Reentran
       uint256 x2EarnRewardsPoolAmount
     ) = claimableAmount(roundId, appId);
 
-    require(amountToClaim > 0, "XAllocationPool: no rewards available for this app");
-
     $.claimedRewards[appId][roundId] = true;
-
+    
     //check that contract has enough funds to pay the reward
     require(
       $.b3tr.balanceOf(address(this)) >= (teamAllocationsAmount + x2EarnRewardsPoolAmount + unallocatedAmount),

packages/contracts/contracts/XAllocationPool.sol

@@ -23,19 +23,19 @@
 
 pragma solidity 0.8.20;
 
-import { X2EarnAppsUpgradeable } from "./x-2-earn-apps/X2EarnAppsUpgradeable.sol";
-import { AdministrationUpgradeable } from "./x-2-earn-apps/modules/AdministrationUpgradeable.sol";
-import { AppsStorageUpgradeable } from "./x-2-earn-apps/modules/AppsStorageUpgradeable.sol";
-import { ContractSettingsUpgradeable } from "./x-2-earn-apps/modules/ContractSettingsUpgradeable.sol";
-import { VoteEligibilityUpgradeable } from "./x-2-earn-apps/modules//VoteEligibilityUpgradeable.sol";
-import { EndorsementUpgradeable } from "./x-2-earn-apps/modules/EndorsementUpgradeable.sol";
-import { EndorsementUtils } from "./x-2-earn-apps/libraries/EndorsementUtils.sol";
+import { X2EarnAppsUpgradeableV7 } from "./x-2-earn-apps/X2EarnAppsUpgradeableV7.sol";
+import { AdministrationUpgradeableV7 } from "./x-2-earn-apps/modules/AdministrationUpgradeableV7.sol";
+import { AppsStorageUpgradeableV7 } from "./x-2-earn-apps/modules/AppsStorageUpgradeableV7.sol";
+import { ContractSettingsUpgradeableV7 } from "./x-2-earn-apps/modules/ContractSettingsUpgradeableV7.sol";
+import { VoteEligibilityUpgradeableV7 } from "./x-2-earn-apps/modules/VoteEligibilityUpgradeableV7.sol";
+import { EndorsementUpgradeableV7 } from "./x-2-earn-apps/modules/EndorsementUpgradeableV7.sol";
+import { EndorsementUtilsV7 } from "./x-2-earn-apps/libraries/EndorsementUtilsV7.sol";
 import { UUPSUpgradeable } from "@openzeppelin/contracts-upgradeable/proxy/utils/UUPSUpgradeable.sol";
 import { AccessControlUpgradeable } from "@openzeppelin/contracts-upgradeable/access/AccessControlUpgradeable.sol";
-import { IXAllocationVotingGovernor } from "./interfaces/IXAllocationVotingGovernor.sol";
+import { IXAllocationVotingGovernor } from "../../interfaces/IXAllocationVotingGovernor.sol";
 
 /**
- * @title X2EarnApps
+ * @title X2EarnAppsV7
  * @notice This contract handles the x-2-earn applications of the VeBetterDAO ecosystem. The contract allows the insert, management and
  * eligibility of apps for the B3TR allocation rounds.
  * @dev The contract is using AccessControl to handle the admin and upgrader roles.
@@ -60,20 +60,20 @@ import { IXAllocationVotingGovernor } from "./interfaces/IXAllocationVotingGover
  *
  * -------------------- Version 6 --------------------
  * - Upon StarGate launch, we updated the NodeManagement contract to V3. This impacted mostly
- *   EndorsementUtils library.
- *   EndorsementUpgradeable module.
+ *   EndorsementUtilsV7 library.
+ *   EndorsementUpgradeableV7 module.
  *
  * -------------------- Version 7 --------------------
  * - Integrated Stargate NFT contract for node management and endorsement verification.
  * - Updated endorsement system to use Stargate NFT for node ownership and token management.
  */
-contract X2EarnApps is
-  X2EarnAppsUpgradeable,
-  AdministrationUpgradeable,
-  ContractSettingsUpgradeable,
-  VoteEligibilityUpgradeable,
-  AppsStorageUpgradeable,
-  EndorsementUpgradeable,
+contract X2EarnAppsV7 is
+  X2EarnAppsUpgradeableV7,
+  AdministrationUpgradeableV7,
+  ContractSettingsUpgradeableV7,
+  VoteEligibilityUpgradeableV7,
+  AppsStorageUpgradeableV7,
+  EndorsementUpgradeableV7,
   AccessControlUpgradeable,
   UUPSUpgradeable
 {
@@ -94,7 +94,7 @@ contract X2EarnApps is
    * @dev This function is called only once during the contract deployment
    */
   function initializeV7(address _stargateNft) external onlyRole(UPGRADER_ROLE) reinitializer(7) {
-    require(_stargateNft != address(0), "X2EarnApps: Invalid Stargate NFT contract address");
+    require(_stargateNft != address(0), "X2EarnAppsV7: Invalid Stargate NFT contract address");
     __Endorsement_init_v7(_stargateNft);
   }
 
@@ -302,7 +302,7 @@ contract X2EarnApps is
    * @dev See {IX2EarnApps-updateNodeEndorsementScores}.
    */
   function updateNodeEndorsementScores(
-    EndorsementUtils.NodeStrengthScores calldata _nodeStrengthScores
+    EndorsementUtilsV7.NodeStrengthScores calldata _nodeStrengthScores
   ) external onlyRole(GOVERNANCE_ROLE) {
     _updateNodeEndorsementScores(_nodeStrengthScores);
   }