@ballkidz/defifa 0.0.39 → 0.0.41

package/ADMINISTRATION.md

@@ -30,6 +30,7 @@
 | Ratification path caller | Any caller who meets the documented conditions | Per game | Finalizes a valid scorecard |
 | Fulfillment path caller | Any valid caller once ratified | Per game | Must run the completion commitment path |
 | `DefifaProjectOwner` holder | Project NFT sent into sink | Per fee project | Irreversible ownership lock |
+| `DefifaDeployer` owner | Constructor `initialOwner` (typically the Defifa multisig) | Global referral-attribution surface | Single privilege: call `setReferralProjectId` to repoint the fee-volume credit |
 
 ## Privileged Surfaces
 
@@ -37,6 +38,7 @@
 - `submitScorecardFor(...)`, `attestToScorecardFrom(...)`, `revokeAttestationFrom(...)`, and `ratifyScorecardFrom(...)` govern outcome selection
 - `fulfillCommitmentsOf(...)` turns a ratified scorecard into real settlement
 - `triggerNoContestFor(...)` moves failed games into the documented recovery path
+- `DefifaDeployer.setReferralProjectId(projectId, chainId)` — `onlyOwner`; retargets the fee-volume referrer credited on every `sendPayoutsOf` call this deployer makes from `fulfillCommitmentsOf`. Stores the packed `(chainId << 48) | projectId` value `JBMultiTerminal` expects on its `referralProjectId` argument. Defaults to `(1, DEFIFA_PROJECT_ID)` at construction so credit lands on the Defifa project on Ethereum mainnet regardless of which chain a game runs on. Passing `(0, 0)` disables the credit entirely. Bounded so the pack is lossless: `projectId <= type(uint48).max`, `chainId <= type(uint208).max`. Does not affect game economics — only where fee-volume attribution accrues.
 
 ## Immutable And One-Way
 
@@ -77,3 +79,4 @@
 - No one can set cash-out weights twice.
 - No one can fulfill commitments twice.
 - No one can recover the project NFT from `DefifaProjectOwner`.
+- The `DefifaDeployer` owner can repoint `referralProjectId` but cannot change anything else about an in-flight or past game — game economics, fees, and settlement remain bounded by the immutable launch configuration.

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.0.41 — Owner-settable referral target on `DefifaDeployer`
+
+- `DefifaDeployer` now inherits OpenZeppelin `Ownable`. New constructor arg `address initialOwner` is passed straight to `Ownable(initialOwner)`. **This is a breaking constructor signature change** — `script/Deploy.s.sol` and every test that instantiates `DefifaDeployer` directly was updated to pass `initialOwner` (typically `safeAddress()` in the deploy script; `address(this)` in tests).
+- New `referralProjectId()` view returning the packed `(chainId << 48) | projectId` reference credited as the referrer on every fee-payout `sendPayoutsOf` call from `fulfillCommitmentsOf`.
+- New `setReferralProjectId(uint256 projectId, uint256 chainId)` (`onlyOwner`): takes the two fields unpacked, packs and stores them. Bounded so the pack is lossless — `projectId <= type(uint48).max`, `chainId <= type(uint208).max`. Reverts with `DefifaDeployer_ReferralProjectIdTooLarge` / `DefifaDeployer_ReferralChainIdTooLarge` otherwise. Emits `SetReferralProjectId(referralChainId, referralProjectId, caller)`.
+- Default at construction: `(chainId = 1, projectId = DEFIFA_PROJECT_ID)` — fee-volume credit still lands on the Defifa project on Ethereum mainnet regardless of which chain a game runs on. Owner can repoint this or pass `(0, 0)` to disable referral credit entirely.
+- The inline `(uint256(1) << 48) | DEFIFA_PROJECT_ID` pack inside `fulfillCommitmentsOf` is replaced by a read of the new storage slot. No external behavior change for default deployments.
+
 ## 0.0.35 — Bump v6 deps to nana-core-v6 0.0.53 cohort
 
 - `@bananapus/core-v6`: `^0.0.48 → ^0.0.53` ([PR #145](https://github.com/Bananapus/nana-core-v6/pull/145)).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ballkidz/defifa",
-  "version": "0.0.39",
+  "version": "0.0.41",
   "license": "MIT",
   "engines": {
     "node": "25.9.0"
@@ -33,7 +33,7 @@
   "dependencies": {
     "@bananapus/721-hook-v6": "^0.0.54",
     "@bananapus/address-registry-v6": "^0.0.26",
-    "@bananapus/core-v6": "^0.0.57",
+    "@bananapus/core-v6": "^0.0.59",
     "@bananapus/permission-ids-v6": "^0.0.26",
     "@openzeppelin/contracts": "5.6.1",
     "@prb/math": "4.1.1",

package/script/Deploy.s.sol

@@ -119,7 +119,8 @@ contract DeployMainnet is Script, Sphinx {
             registry: registry.registry,
             defifaProjectId: _defifaProjectId,
             baseProtocolProjectId: _baseProtocolProjectId,
-            hookStore: hookStore
+            hookStore: hookStore,
+            initialOwner: safeAddress()
         });
 
         governor.transferOwnership(address(deployer));

package/src/DefifaDeployer.sol

@@ -21,6 +21,7 @@ import {JBFundAccessLimitGroup} from "@bananapus/core-v6/src/structs/JBFundAcces
 import {JBRulesetMetadata} from "@bananapus/core-v6/src/structs/JBRulesetMetadata.sol";
 import {JBSplit} from "@bananapus/core-v6/src/structs/JBSplit.sol";
 import {JBSplitGroup} from "@bananapus/core-v6/src/structs/JBSplitGroup.sol";
+import {Ownable} from "@openzeppelin/contracts/access/Ownable.sol";
 import {Clones} from "@openzeppelin/contracts/proxy/Clones.sol";
 import {IERC20} from "@openzeppelin/contracts/token/ERC20/IERC20.sol";
 import {SafeERC20} from "@openzeppelin/contracts/token/ERC20/utils/SafeERC20.sol";
@@ -46,7 +47,7 @@ import {DefifaTierParams} from "./structs/DefifaTierParams.sol";
 /// the event concludes, a scorecard assigns cash-out weights to each tier. The treasury is distributed proportionally
 /// to winning NFT holders. Games progress through phases: COUNTDOWN → MINT → REFUND → SCORING → COMPLETE (or
 /// NO_CONTEST if minimum participation isn't met or scorecard ratification times out).
-contract DefifaDeployer is IDefifaDeployer, IDefifaGamePhaseReporter, IDefifaGamePotReporter, IERC721Receiver {
+contract DefifaDeployer is IDefifaDeployer, IDefifaGamePhaseReporter, IDefifaGamePotReporter, IERC721Receiver, Ownable {
     using Strings for uint256;
     using SafeERC20 for IERC20;
 
@@ -61,6 +62,8 @@ contract DefifaDeployer is IDefifaDeployer, IDefifaGamePhaseReporter, IDefifaGam
     error DefifaDeployer_InvalidCurrency(address token, uint256 currency);
     error DefifaDeployer_NotNoContest(uint256 gameId, DefifaGamePhase phase);
     error DefifaDeployer_NoContestAlreadyTriggered(uint256 gameId);
+    error DefifaDeployer_ReferralChainIdTooLarge(uint256 referralChainId);
+    error DefifaDeployer_ReferralProjectIdTooLarge(uint256 referralProjectId);
     error DefifaDeployer_SplitsDontAddUp(uint256 totalPercent, uint256 maxPercent);
 
     //*********************************************************************//
@@ -133,6 +136,12 @@ contract DefifaDeployer is IDefifaDeployer, IDefifaGamePhaseReporter, IDefifaGam
     /// @dev Once triggered, the game stays in NO_CONTEST and refunds are enabled.
     mapping(uint256 => bool) public noContestTriggeredFor;
 
+    /// @notice The packed `(referralChainId << 48) | referralProjectId` reference credited as the referrer on
+    /// every fee-payout `sendPayoutsOf` call this deployer makes during `fulfillCommitmentsOf`. Defaults to
+    /// `(1, DEFIFA_PROJECT_ID)` so fee-volume credit accrues to the Defifa project on Ethereum mainnet
+    /// regardless of which chain the game runs on. Settable by the owner via `setReferralProjectId`.
+    uint256 public override referralProjectId;
+
     //*********************************************************************//
     // ------------------------- external views -------------------------- //
     //*********************************************************************//
@@ -281,6 +290,9 @@ contract DefifaDeployer is IDefifaDeployer, IDefifaGamePhaseReporter, IDefifaGam
     /// @param defifaProjectId The ID of the project that should take the fee from the games.
     /// @param baseProtocolProjectId The ID of the protocol project that'll receive fees from fulfilling commitments.
     /// @param hookStore The store used by Defifa hooks.
+    /// @param initialOwner The address granted authority to call `setReferralProjectId`. The contract is otherwise
+    /// stateless from an admin perspective — the owner only controls the referrer reference used when crediting
+    /// fee-volume on `fulfillCommitmentsOf` payouts.
     constructor(
         address hookCodeOrigin,
         IJB721TokenUriResolver tokenUriResolver,
@@ -289,8 +301,11 @@ contract DefifaDeployer is IDefifaDeployer, IDefifaGamePhaseReporter, IDefifaGam
         IJBAddressRegistry registry,
         uint256 defifaProjectId,
         uint256 baseProtocolProjectId,
-        IJB721TiersHookStore hookStore
-    ) {
+        IJB721TiersHookStore hookStore,
+        address initialOwner
+    )
+        Ownable(initialOwner)
+    {
         HOOK_CODE_ORIGIN = hookCodeOrigin;
         TOKEN_URI_RESOLVER = tokenUriResolver;
         GOVERNOR = governor;
@@ -301,6 +316,10 @@ contract DefifaDeployer is IDefifaDeployer, IDefifaGamePhaseReporter, IDefifaGam
         HOOK_STORE = hookStore;
         /// @dev Uses the deployer address as group ID. Game scoring rulesets use uint160(token) as group ID.
         SPLIT_GROUP = uint256(uint160(address(this)));
+
+        // Default referrer reference: Defifa project on Ethereum mainnet. Encoded `(chainId << 48) | projectId`
+        // per `JBMultiTerminal.currentReferralProjectId`. Owner can retarget via `setReferralProjectId`.
+        referralProjectId = (uint256(1) << 48) | defifaProjectId;
     }
 
     //*********************************************************************//
@@ -346,10 +365,18 @@ contract DefifaDeployer is IDefifaDeployer, IDefifaGamePhaseReporter, IDefifaGam
 
         // Send only the fee portion as payouts. The remaining balance stays as surplus for cash-outs.
         // Use the ruleset's baseCurrency — this matches the currency under which payout limits were stored
-        // at launch time, regardless of whether the token is native ETH or an ERC-20.
-        // Wrapped in try-catch so the final ruleset is always queued even if payout fails.
+        // at launch time, regardless of whether the token is native ETH or an ERC-20. Wrapped in try-catch so
+        // the final ruleset is always queued even if payout fails. The configured `referralProjectId` (default
+        // `(1, DEFIFA_PROJECT_ID)`, owner-settable via `setReferralProjectId`) credits Defifa with the protocol
+        // fee volume from every game's commitment payout. Pinning mainnet by default avoids scattering credit
+        // across L2s where Defifa has no canonical project ID.
         try terminal.sendPayoutsOf({
-            projectId: gameId, token: token, amount: feeAmount, currency: metadata.baseCurrency, minTokensPaidOut: 0
+            projectId: gameId,
+            token: token,
+            amount: feeAmount,
+            currency: metadata.baseCurrency,
+            minTokensPaidOut: 0,
+            referralProjectId: referralProjectId
         }) {}
         catch (bytes memory reason) {
             // Payout failed — fee stays in pot. Reset to 0 so currentGamePotOf
@@ -639,6 +666,36 @@ contract DefifaDeployer is IDefifaDeployer, IDefifaGamePhaseReporter, IDefifaGam
         return IERC721Receiver.onERC721Received.selector;
     }
 
+    /// @notice Update the referrer reference credited on every fee-payout `sendPayoutsOf` call this deployer
+    /// makes during `fulfillCommitmentsOf`.
+    /// @dev Stores the packed `(newReferralChainId << 48) | newReferralProjectId` value used by
+    /// `JBMultiTerminal.currentReferralProjectId`. Either field may be zero — passing `(0, 0)` disables the
+    /// referral credit entirely. Bounded so the pack is lossless: `newReferralProjectId` must fit in `uint48`,
+    /// `newReferralChainId` must fit in `uint208` (so the left-shift by 48 doesn't drop high bits).
+    /// @param newReferralProjectId The referring project's bare ID on `newReferralChainId`.
+    /// @param newReferralChainId The EIP-155 chain ID of the referrer's home chain.
+    function setReferralProjectId(
+        uint256 newReferralProjectId,
+        uint256 newReferralChainId
+    )
+        external
+        override
+        onlyOwner
+    {
+        // Bound the inputs to the on-chain encoding so the pack is lossless. The same shape JBMultiTerminal uses:
+        // projectId in bits [47:0], chainId in bits [255:48].
+        if (newReferralProjectId > type(uint48).max) {
+            revert DefifaDeployer_ReferralProjectIdTooLarge(newReferralProjectId);
+        }
+        if (newReferralChainId >> 208 != 0) revert DefifaDeployer_ReferralChainIdTooLarge(newReferralChainId);
+
+        referralProjectId = (newReferralChainId << 48) | newReferralProjectId;
+
+        emit SetReferralProjectId({
+            referralChainId: newReferralChainId, referralProjectId: newReferralProjectId, caller: msg.sender
+        });
+    }
+
     /// @notice Triggers the no-contest refund mechanism for a game.
     /// @dev Anyone can call this once the game is in the NO_CONTEST phase. This queues a new ruleset without
     /// payout limits, making the surplus equal to the balance so users can cash out at their mint price.

package/src/interfaces/IDefifaDeployer.sol

@@ -45,6 +45,12 @@ interface IDefifaDeployer {
     /// @param caller The address that queued the phase transition.
     event QueuedNoContest(uint256 indexed gameId, address caller);
 
+    /// @notice Emitted when the referrer reference for fee-volume credit is updated.
+    /// @param referralChainId The EIP-155 chain ID of the new referrer's home chain.
+    /// @param referralProjectId The new referring project's bare project ID on `referralChainId`.
+    /// @param caller The address that set the new referrer.
+    event SetReferralProjectId(uint256 indexed referralChainId, uint256 indexed referralProjectId, address caller);
+
     /// @notice The fee divisor for base protocol fees (100 / fee percent).
     /// @return The fee divisor.
     function BASE_PROTOCOL_FEE_DIVISOR() external view returns (uint256);
@@ -81,6 +87,12 @@ interface IDefifaDeployer {
     /// @return The address registry contract.
     function REGISTRY() external view returns (IJBAddressRegistry);
 
+    /// @notice The packed `(referralChainId << 48) | referralProjectId` reference credited as the referrer on
+    /// every fee-payout `sendPayoutsOf` call this deployer makes. Defaults to `(1, DEFIFA_PROJECT_ID)` so
+    /// credit accrues to Defifa on Ethereum mainnet; owner-settable via `setReferralProjectId`.
+    /// @return The packed referrer reference.
+    function referralProjectId() external view returns (uint256);
+
     /// @notice The split group ID used for distributing game pot funds.
     /// @return The split group.
     function SPLIT_GROUP() external view returns (uint256);
@@ -119,6 +131,16 @@ interface IDefifaDeployer {
     /// @return gameId The ID of the newly launched game.
     function launchGameWith(DefifaLaunchProjectData calldata launchProjectData) external returns (uint256 gameId);
 
+    /// @notice Update the referrer reference credited on every fee-payout `sendPayoutsOf` call this deployer
+    /// makes during `fulfillCommitmentsOf`.
+    /// @dev Stores the packed `(newReferralChainId << 48) | newReferralProjectId` value used by
+    /// `JBMultiTerminal.currentReferralProjectId`. Either field may be zero (passing `(0, 0)` disables the
+    /// referral credit). Bounded so the pack is lossless: `newReferralProjectId <= type(uint48).max`,
+    /// `newReferralChainId <= type(uint208).max`.
+    /// @param newReferralProjectId The referring project's bare ID on `newReferralChainId`.
+    /// @param newReferralChainId The EIP-155 chain ID of the referrer's home chain.
+    function setReferralProjectId(uint256 newReferralProjectId, uint256 newReferralChainId) external;
+
     /// @notice Trigger a no-contest outcome for a game.
     /// @param gameId The ID of the game.
     function triggerNoContestFor(uint256 gameId) external;