@ballkidz/defifa 0.0.12 → 0.0.14

package/ADMINISTRATION.md

@@ -31,8 +31,8 @@ Admin privileges and their scope in defifa-collection-deployer-v6.
 | Function | Required Role | Permission Check | What It Does |
 |----------|--------------|-----------------|-------------|
 | `initializeGame()` | DefifaDeployer (owner) | `onlyOwner` | Sets attestation start time and grace period for a game. Enforces minimum 1-day grace period. Called automatically during `launchGameWith()`. |
-| `submitScorecardFor()` | Anyone | Must be in SCORING phase; no ratified scorecard yet; no duplicate scorecard hash; weighted tiers must have nonzero supply | Submits a scorecard for attestation. Sets `attestationsBegin` and `gracePeriodEnds` timestamps. |
-| `attestToScorecardFrom()` | Any NFT holder | Must be in SCORING phase; scorecard must be ACTIVE or SUCCEEDED; caller cannot have already attested | Records attestation weight based on tier holdings at the scorecard's `attestationsBegin` timestamp. |
+| `submitScorecardFor()` | Anyone | Must be in SCORING phase; no ratified scorecard yet; no duplicate scorecard hash; weighted tiers must have nonzero supply | Submits a scorecard for attestation. Sets `attestationsBegin` and `gracePeriodEnds` timestamps. Snapshots pending reserves per tier for BWA computation. |
+| `attestToScorecardFrom()` | Any NFT holder | Must be in SCORING phase; scorecard must be ACTIVE or SUCCEEDED; caller cannot have already attested | Records attestation weight based on tier holdings at the `attestationsBegin - 1` checkpoint timestamp. Uses pending reserve snapshot from submission time. |
 | `ratifyScorecardFrom()` | Anyone | Scorecard must be in SUCCEEDED state (quorum met + grace period elapsed); no scorecard already ratified | Executes the scorecard via low-level call to `setTierCashOutWeightsTo` on the hook, then calls `fulfillCommitmentsOf`. |
 
 ### DefifaHook
@@ -79,7 +79,7 @@ COUNTDOWN --> MINT --> REFUND (optional) --> SCORING --> COMPLETE or NO_CONTEST
 
 ### Attestation Quorum Details
 
-The quorum threshold is 50% of the total attestation power across all tiers with nonzero mint supply. Attestation power per tier is proportional to the tier's minted supply at the `attestationsBegin` snapshot timestamp.
+The quorum threshold is 50% of the total attestation power across all tiers with nonzero mint supply. Attestation power per tier is proportional to the tier's minted supply at the `attestationsBegin - 1` checkpoint timestamp, with pending reserves snapshotted at scorecard submission time to prevent reserve minting from inflating attestation power.
 
 **Edge cases:**
 - **Tiers with zero mints:** Tiers with `currentSupplyOfTier(tierId) == 0` are excluded from the quorum calculation. They have no attestation power and cannot influence scoring.

package/ARCHITECTURE.md

@@ -53,10 +53,11 @@ COMPLETE Phase:
 Scorer → DefifaGovernor.submitScorecard(tierWeights[])
   → Validate: correct phase, valid tier order, weights sum correctly
   → Create proposal hash
+  → Snapshot pending reserves per tier for BWA computation
 
 Attestor → DefifaGovernor.attestToScorecard(proposalId)
-  → Must hold NFT tier tokens
-  → Attestation weight = voting power from held tiers
+  → Must hold NFT tier tokens at attestationsBegin - 1 checkpoint
+  → Attestation weight = voting power from held tiers (diluted by snapshotted pending reserves)
   → When quorum reached → scorecard ratified
   → DefifaHook.setScorecard() called
 ```

package/AUDIT_INSTRUCTIONS.md

@@ -150,7 +150,7 @@ NO_CONTEST (safety mechanism triggered)
 **Attest (DefifaGovernor.attestToScorecardFrom):**
 1. Require SCORING phase, scorecard ACTIVE or SUCCEEDED.
 2. Prevent double attestation per account per scorecard.
-3. Compute weight via `getAttestationWeight()` at `attestationsBegin` timestamp.
+3. Compute weight via `getBWAAttestationWeight()` at `attestationsBegin - 1` timestamp, using pending reserve snapshot from submission time.
 4. Increment `_scorecardAttestationsOf[gameId][scorecardId].count += weight`.
 
 **Ratify (DefifaGovernor.ratifyScorecardFrom):**
@@ -188,7 +188,7 @@ tierPower = MAX_ATTESTATION_POWER_TIER * (account's attestation units / tier's t
 
 Where:
 - `MAX_ATTESTATION_POWER_TIER = 1,000,000,000` (1e9)
-- Account's units come from `getPastTierAttestationUnitsOf()` (checkpoint at `attestationsBegin` timestamp)
+- Account's units come from `getPastTierAttestationUnitsOf()` (checkpoint at `attestationsBegin - 1` timestamp)
 - Total tier units from `getPastTierTotalAttestationUnitsOf()`
 
 Total attestation power = sum of per-tier powers across all tiers.
@@ -296,9 +296,9 @@ Start with the money: follow ETH from payment to cash-out.
 
 6. **Quorum manipulation via live supply**: `quorum()` reads `currentSupplyOfTier()` at call time (not snapshotted). Verify that burning tokens during SCORING is prevented by `DefifaHook_NothingToClaim` (cash-out weights not set yet). Check if any other burn path exists that could reduce quorum after attestations have begun.
 
-7. **Attestation snapshotting**: Attestation weight is computed at the `attestationsBegin` timestamp via `getPastTierAttestationUnitsOf()`. Verify that the `Checkpoints.Trace208.upperLookup()` correctly captures the state at that exact timestamp, and that minting or transferring NFTs after `attestationsBegin` does not retroactively affect attestation power.
+7. **Attestation snapshotting**: Attestation weight is computed at the `attestationsBegin - 1` timestamp via `getPastTierAttestationUnitsOf()`. Pending reserves are snapshotted at submission time (`_pendingReservesSnapshotOf`). Verify that the `Checkpoints.Trace208.upperLookup()` correctly captures the state at that timestamp, that minting or transferring NFTs after `attestationsBegin - 1` does not retroactively affect attestation power, and that minting reserves after submission does not change the snapshotted pending reserve counts.
 
-8. **Double attestation prevention**: `_attestations.hasAttested[msg.sender]` prevents double voting. But verify that an attacker cannot attest, transfer NFTs to another address, and have that address attest with the same attestation power (the snapshot at `attestationsBegin` should prevent this, but verify the checkpoint resolution).
+8. **Double attestation prevention**: `_attestations.attestedWeightOf[msg.sender]` prevents double voting. Verify that an attacker cannot attest, transfer NFTs to another address, and have that address attest with the same attestation power (the checkpoint at `attestationsBegin - 1` should prevent this because same-block transfers are invisible at `attestationsBegin - 1`).
 
 9. **Grace period anchoring**: `gracePeriodEnds = attestationsBegin + attestationGracePeriod`. Verify that early scorecard submission (before `attestationStartTime`) correctly delays the grace period start, preventing instant ratification.
 
@@ -344,7 +344,7 @@ These properties should hold for all games in all states. The test suite validat
 
 ### Governance
 - Each account can attest to a given scorecard at most once
-- Attestation power is snapshotted at `attestationsBegin` (not live)
+- Attestation power is checkpointed at `attestationsBegin - 1` (not live); pending reserves snapshotted at submission time
 - Quorum threshold: 50% of minted tiers' total max attestation power (live at call time)
 - Only one scorecard can be ratified per game
 - Minimum grace period: 1 day (enforced in `initializeGame`)

package/CHANGE_LOG.md

@@ -8,7 +8,20 @@ This document describes the changes between `defifa-collection-deployer` (v5) an
 - **Dependency modernization**: Core, permission IDs, address registry, and ownable dependencies all updated to v6. New ecosystem dependencies on `croptop-core-v6` and `revnet-core-v6`.
 - **Error naming standardized**: Error names changed from bare names (e.g., `InvalidCashoutWeights`) to contract-prefixed names (e.g., `DefifaHook_InvalidCashoutWeights`).
 - **Cash out hook spec gains `noop` field**: `beforeCashOutRecordedWith` now returns `noop=false` in all specifications, ensuring the terminal always calls the hook callback.
-- **Game lifecycle unchanged**: The core game phases (COUNTDOWN → MINT → REFUND → SCORING → COMPLETE) and governance model (50% quorum, scorecard ratification) remain identical.
+- **Compiler/tooling updated**: The v6 repo now builds and tests on Solidity `0.8.28`, matching the rest of the V6 ecosystem.
+- **Game lifecycle preserved**: The core game phases (COUNTDOWN → MINT → REFUND → SCORING → COMPLETE) and governance model (50% quorum, scorecard ratification) remain the same at the product level even though the underlying hook/controller integrations changed.
+
+## ABI Status
+
+This repo does have meaningful ABI migration surface. The main ABI-facing contracts for integrators are:
+- `IDefifaDeployer`
+- `IDefifaHook`
+- `IDefifaGovernor`
+
+The largest ABI risks are:
+- inherited 721-hook/core-v6 struct and return-shape changes flowing through Defifa interfaces;
+- event families now living on v6 interfaces/contracts with prefixed errors and updated dependent types;
+- hook return values that now include v6 `noop`-aware hook-spec structures.
 
 ---
 
@@ -42,7 +55,8 @@ The v6 `JBCashOutHookSpecification` struct has a `noop` boolean field. `DefifaHo
 
 ### 1.4 Solidity Version
 
-Compiler remains at `pragma solidity 0.8.23` (not bumped to 0.8.26 unlike most other v6 repos).
+- **v5:** `pragma solidity 0.8.23`
+- **v6:** `pragma solidity 0.8.28`
 
 ### 1.5 721 Hook API Changes
 
@@ -52,6 +66,14 @@ Inherited from `nana-721-hook-v6`:
 - `JB721TierConfig` gained `splitPercent` and `splits` fields
 - `JB721TiersHookFlags` gained `issueTokensForSplits` field
 
+### 1.6 Function-Level Integration Changes
+
+These are the main V6 surface changes integrators should care about:
+- `beforeCashOutRecordedWith(...)` now returns a `JBCashOutHookSpecification` that includes the new `noop` field from core-v6.
+- Any integration constructing or decoding `JB721TierConfig` must account for the added `splitPercent` and `splits` fields.
+- Any integration reading pricing context from the inherited 721 hook must expect 2 return values, not 3.
+- Defifa deployer integrations should re-check `launchGameWith(...)`, `fulfillCommitmentsOf(...)`, `triggerNoContestFor(...)`, `nextPhaseNeedsQueueing(...)`, `safetyParamsOf(...)`, and `timesFor(...)` against the v6 ABIs and dependent core-v6 structs.
+
 ---
 
 ## 2. Game Lifecycle (Unchanged)
@@ -89,9 +111,22 @@ DefifaHook instances are deployed as minimal proxy clones via `Clones.cloneDeter
 - One-time `initialize()` call per clone
 - Owned by DefifaGovernor for scorecard weight setting
 
+## 4. Events and Errors
+
+The most important integration-facing patterns are:
+- Errors are now consistently contract-prefixed (`DefifaHook_*`, `DefifaDeployer_*`, `DefifaGovernor_*`, `DefifaProjectOwner_*`) instead of using the older unprefixed style.
+- Defifa-specific events remain centered around game launch, phase transitions, fulfillment, scoring, minting, claims, and delegation, but they now live against the V6 hook/controller stack and should be indexed using the V6 ABIs.
+- `CommitmentPayoutFailed`, `LaunchGame`, `QueuedRefundPhase`, `QueuedScoringPhase`, `QueuedNoContest`, `GameInitialized`, `ScorecardSubmitted`, `ScorecardAttested`, `ScorecardRatified`, `Mint`, `MintReservedToken`, `ClaimedTokens`, and `TierCashOutWeightsSet` are the key integration events to watch across the deployer, governor, and hook.
+- Other hook-level events worth indexing for governance clients are `TierDelegateAttestationsChanged` and `DelegateChanged`.
+
+Key runtime errors now exposed by the v6 contracts include:
+- `DefifaDeployer_*` errors such as `DefifaDeployer_InvalidGameConfiguration`, `DefifaDeployer_TerminalNotFound`, `DefifaDeployer_SplitsDontAddUp`, `DefifaDeployer_CantFulfillYet`, and `DefifaDeployer_NoContestAlreadyTriggered`.
+- `DefifaHook_*` errors such as `DefifaHook_InvalidCashoutWeights`, `DefifaHook_InvalidTierId`, `DefifaHook_ReservedTokenMintingPaused`, `DefifaHook_TransfersPaused`, and `DefifaHook_Unauthorized(...)`.
+- `DefifaGovernor_*` errors such as `DefifaGovernor_AlreadyAttested`, `DefifaGovernor_AlreadyRatified`, `DefifaGovernor_DuplicateScorecard`, `DefifaGovernor_NotAllowed`, and `DefifaGovernor_UnknownProposal`.
+
 ---
 
-## 4. Migration Table
+## 5. Migration Table
 
 | Aspect | v5 | v6 |
 |--------|----|----|
@@ -100,8 +135,30 @@ DefifaHook instances are deployed as minimal proxy clones via `Clones.cloneDeter
 | Permission IDs | Not a direct dependency | `@bananapus/permission-ids-v6` |
 | Error naming | Bare names | Contract-prefixed names |
 | `JBCashOutHookSpecification` | No `noop` field | `noop=false` on all specs |
-| Solidity version | `0.8.23` | `0.8.23` (unchanged) |
+| Solidity version | `0.8.23` | `0.8.28` |
 | Game lifecycle | COUNTDOWN->MINT->REFUND->SCORING->COMPLETE | Identical |
 | Governance model | 50% quorum, tier-delegated | Identical |
 
-> **Cross-repo impact**: Uses `nana-721-hook-v6` for all tier management and cashout weight distribution. The `nana-permission-ids-v6` ID shifts affect any hardcoded permission checks. Not yet included in `deploy-all-v6` deployment phases (awaiting source updates).
+> **Cross-repo impact**: Uses `nana-721-hook-v6` for all tier management and cashout weight distribution. The `nana-permission-ids-v6` ID shifts affect any hardcoded permission checks. `deploy-all-v6` now includes Defifa as Phase 10, so canonical deployments can source Defifa addresses from the top-level rollout.
+
+---
+
+## 6. Post-Audit Fixes (Codex R2)
+
+### 6.1 H-1: Prevent same-block double attestation via checkpoint snapshot
+
+**File:** `DefifaGovernor.sol` -- `attestToScorecardFrom()`
+
+Previously, attestation weight was snapshot at `_scorecard.attestationsBegin`, which could equal `block.timestamp` during the same block as a transfer. This allowed a holder to attest, transfer the NFT, and have the recipient also attest in the same block -- both counting because `upperLookup(block.timestamp)` includes same-block checkpoints.
+
+**Fix:** Changed the checkpoint timestamp to `attestationsBegin - 1`, ensuring only state from before the attestation window opens is visible. Same-block transfer recipients now receive zero attestation weight. Note: NFTs minted in the same block as `attestationsBegin` have zero weight for attestation -- a negligible trade-off since attestation typically happens well after minting.
+
+### 6.2 H-2: Snapshot pending reserves at scorecard submission and include in denominators
+
+**Files:** `DefifaGovernor.sol` -- `submitScorecardFor()`, `getBWAAttestationWeight()`; `DefifaHook.sol` -- `afterCashOutRecordedWith()`
+
+Two related fixes to prevent gaming via pending reserve manipulation:
+
+**Governance (attestation weight):** Previously, `getBWAAttestationWeight()` read pending reserve counts live from the store. Minting reserves between scorecard submission and attestation could inflate a holder's BWA power by removing the pending-reserve dilution. **Fix:** `submitScorecardFor()` now snapshots `numberOfPendingReservesFor()` for every tier into `_pendingReservesSnapshotOf[gameId][scorecardId][tierId]`. `getBWAAttestationWeight()` reads from this snapshot instead of live state, locking the dilution in place regardless of subsequent reserve minting.
+
+**Cash-out (fee token distribution):** Previously, the fee token claim denominator (`_totalMintCost`) only counted minted tokens. Pending (unminted) reserve NFTs were excluded, allowing paid holders to cash out before reserves were minted and claim a disproportionate share of fee tokens ($DEFIFA/$NANA). **Fix:** `afterCashOutRecordedWith()` now passes `_totalMintCost + _pendingReserveMintCost()` as the denominator when distributing fee tokens. The new `_pendingReserveMintCost()` function iterates all tiers and sums `pendingReserves * tier.price`, ensuring pending reserves are accounted for in fee token distribution.