feat(reward): model f099 burn sentinel in mock (#29)

Author: rvagg

docs/f02-design.md

@@ -53,7 +53,10 @@ streams[]        [ id, WeightRecord[v_start, slope, t_start, floor, cap], distri
                               # stream only (the block winner)
   EXPLICIT  = [ writer,       # FIP "designated writer": may call SetShares.
                               # The SRA for the service stream. Not a payee.
-      shares[]:         [[wallet, share], ...]    # payees; <= MAX_RECIPIENTS
+      shares[]:         [[wallet, share], ...]    # payees; <= MAX_RECIPIENTS.
+                              # Sums to DENOM on the wire; stored shares may sum
+                              # lower, the shortfall being the burn share (see
+                              # "The f099 burn sentinel").
       payable[]:        [[wallet, amount], ...]   # unclaimed from closed periods
       claimed_period[]: [[wallet, amount], ...] ] # claimed from the current accrual
 
@@ -131,7 +134,11 @@ AwardBlockReward(miner, penalty, gas_reward, win_count):
     if any weight record is malformed or sum(evaluated weights) > DENOM:
         pay gas_reward and apply the penalty; commit no state or counter change; return
     miner = floor(w1 * BR)
-    explicit = floor(w2 * BR) if accounting_valid else 0
+    for each explicit stream:
+        portion = floor(w_stream * BR)
+        # burn sentinel: stored shares summing below DENOM burn the shortfall
+        accrue_to_stream = floor(portion * stored_share_total / DENOM)
+    explicit = sum(accrue_to_stream) if accounting_valid else 0
     burn = BR - miner - explicit
     total_minted_reward += BR
     total_burn_minted += burn
@@ -159,13 +166,14 @@ Applied and dropped events on this implicit path are best-effort. FIP-0107 is re
 ```
 SetShares(stream_id, new_map):
     caller must be the stream's designated writer
-    validate sum(new_map shares) == 1 and every share > 0
+    validate sum(new_map shares) == DENOM and every share > 0
     resolve recipients to ID addresses; reject the call if any does not resolve
     (recipients must exist; the SRA pre-validates at registration, so this is
      a backstop against typos and stranded credits)
+    strip any f099 rows before storing; their weight becomes the burn share
     pool = accrued[stream_id]
     for each (wallet, share) in the OLD map:
-        earned = floor(share * pool)
+        earned = floor(share * pool / stored_share_total)
         payable[wallet] += earned - claimed_period[wallet]
     residue = pool - sum(earned)             # rounding dust only
     send(f099, residue)                       # neither counter moves
@@ -190,7 +198,8 @@ Claim(stream_id, wallets[]) -> amounts[]:
             entitlement = its payable[wallet]              # nothing live on a tombstone
         else:
             s = the stream's EXPLICIT distribution
-            live = floor(share_of(s.shares, wallet) * accrued[stream_id])
+            live = floor(share_of(s.shares, wallet) * accrued[stream_id]
+                         / stored_share_total(s.shares))       # zero total pays nothing
                  - amount_of(s.claimed_period, wallet)         # current period
             entitlement = live + amount_of(s.payable, wallet)  # + unclaimed previous
         if entitlement == 0: amounts[i] = 0; continue
@@ -204,6 +213,28 @@ Claim(stream_id, wallets[]) -> amounts[]:
 
 Permissionless, batched, recipients fixed by the map, works mid-period. A batch is capped at `MAX_RECIPIENTS`, so a full payable table drains in two calls. Zero-entitlement entries (unknown wallets, duplicates within the batch) pay nothing and return 0 at their position. An unknown or deleted stream id returns all zeros, so a repeated claim after its tombstone drains is benign. An all-zero batch succeeds.
 
+## The f099 burn sentinel
+
+f099 in an explicit share map is a burn instruction, not a payee. Wire shares still sum to
+`DENOM`; share-map admission validates that checksum, then strips all f099 rows. The stored
+shortfall is the burn share. Persisted state rejects f099, so it cannot accrue, be claimed, or
+reach a tombstone.
+
+For each explicit stream award:
+
+```
+accrue = floor(portion * stored_share_total / DENOM)
+burn += portion - accrue
+```
+
+Only `accrue` enters the stream pool and `total_explicit_minted`; the remainder uses the
+existing burn send and counter. Flooring the survivor side prevents a removal from improving
+survivor earnings through rounding.
+
+Claim and fold divide the survivor pool by `stored_share_total`, leaving stored share values
+unchanged. A total of `DENOM` uses the ordinary path; zero accrues nothing and burns the whole
+portion. The total is derived from the inline share vector, bounded by `MAX_RECIPIENTS`.
+
 ## Supply accounting
 
 Circulating supply is consensus-relevant (`GetFilMined` feeds initial pledge) and Lotus, Forest, and Venus each compute it independently, so its inputs do not change. `FilMined` stays "read position 9 of f02": the split changes who receives issuance, not how much, so the field keeps meaning the total and no implementation changes its supply logic.

test/mocks/FVMRewardActor.sol

@@ -6,6 +6,7 @@ import {Vm} from "forge-std/Vm.sol";
 import {USR_FORBIDDEN, USR_ILLEGAL_ARGUMENT, USR_NOT_FOUND, USR_UNHANDLED_MESSAGE} from "fvm-solidity/FVMErrors.sol";
 import {CBOR_CODEC} from "fvm-solidity/FVMCodec.sol";
 import {FVMPay} from "fvm-solidity/FVMPay.sol";
+import {BURN_ADDRESS} from "fvm-solidity/FVMActors.sol";
 
 import {
     SET_WEIGHT_RECORDS,
@@ -221,8 +222,10 @@ contract FVMRewardActor {
             if (s.kind == DistributionKind.IMPLICIT) {
                 minerPortion += amount;
             } else {
-                servicePortion += amount;
-                s.accrued += amount;
+                uint256 storedShareTotal = _storedShareTotal(s);
+                uint256 accrued = storedShareTotal == SHARE_TOTAL ? amount : (amount * storedShareTotal) / SHARE_TOTAL;
+                servicePortion += accrued;
+                s.accrued += accrued;
             }
         }
         burnAmount = br - minerPortion - servicePortion;
@@ -347,9 +350,7 @@ contract FVMRewardActor {
         _foldAndBurnResidue(s);
 
         delete s.shares;
-        for (uint256 i = 0; i < newShares.length; i++) {
-            s.shares.push(newShares[i]);
-        }
+        _pushNonBurnShares(s.shares, newShares);
         return (0, 0, "");
     }
 
@@ -469,9 +470,7 @@ contract FVMRewardActor {
         if (!_admits(proposed)) return (USR_ILLEGAL_ARGUMENT, 0, "");
 
         delete _pendingShares[id];
-        for (uint256 i = 0; i < shares.length; i++) {
-            _pendingShares[id].push(shares[i]);
-        }
+        _pushNonBurnShares(_pendingShares[id], shares);
         _queueWrite(
             id,
             PendingOp.REGISTER,
@@ -600,6 +599,9 @@ contract FVMRewardActor {
             if (s.kind != DistributionKind.EXPLICIT) return (USR_ILLEGAL_ARGUMENT, 0, "");
         }
 
+        uint256 storedShareTotal;
+        if (!tombstoned) storedShareTotal = _storedShareTotal(s);
+
         uint256[] memory amounts = new uint256[](wallets.length);
         for (uint256 i = 0; i < wallets.length; i++) {
             address wallet = wallets[i];
@@ -615,7 +617,7 @@ contract FVMRewardActor {
             } else {
                 uint256 share = _shareOf(s, wallet);
                 uint256 claimed = s.claimedPeriod.amount[wallet];
-                uint256 grossLive = (share * s.accrued) / SHARE_TOTAL;
+                uint256 grossLive = storedShareTotal == 0 ? 0 : (share * s.accrued) / storedShareTotal;
                 uint256 live = grossLive > claimed ? grossLive - claimed : 0;
                 uint256 payableAmount = s.payableLedger.amount[wallet];
                 entitlement = live + payableAmount;
@@ -983,14 +985,16 @@ contract FVMRewardActor {
     /// @dev validate_weight_record: floor <= v_start <= cap <= DENOM. The lower bound on floor
     /// is implicit in f02, where these three are u64; here they are signed and it is not.
     /// @dev validate_shares: at most MAX_RECIPIENTS rows, every share nonzero, no repeated
-    /// recipient, and the whole map summing to one.
+    /// payee, and the whole wire map summing to one. Repeated burn instructions are equivalent.
     function _sharesValid(Share[] memory shares) internal pure returns (bool) {
         if (shares.length > MAX_RECIPIENTS) return false;
         uint256 total;
         for (uint256 i = 0; i < shares.length; i++) {
             if (shares[i].share == 0) return false;
-            for (uint256 j = 0; j < i; j++) {
-                if (shares[j].wallet == shares[i].wallet) return false;
+            if (shares[i].wallet != BURN_ADDRESS) {
+                for (uint256 j = 0; j < i; j++) {
+                    if (shares[j].wallet == shares[i].wallet) return false;
+                }
             }
             total += shares[i].share;
         }
@@ -1254,14 +1258,27 @@ contract FVMRewardActor {
         return 0;
     }
 
+    function _storedShareTotal(Stream storage s) internal view returns (uint256 total) {
+        for (uint256 i = 0; i < s.shares.length; i++) {
+            total += s.shares[i].share;
+        }
+    }
+
+    function _pushNonBurnShares(Share[] storage target, Share[] memory shares) internal {
+        for (uint256 i = 0; i < shares.length; i++) {
+            if (shares[i].wallet != BURN_ADDRESS) target.push(shares[i]);
+        }
+    }
+
     /// @dev Closes out the current period: each recipient's earned-minus-claimed amount moves
     /// into `payable` under the OLD map, the rounding residue burns, and accrual state resets.
     function _foldAndBurnResidue(Stream storage s) internal {
         uint256 pool = s.accrued;
+        uint256 shareTotal = _storedShareTotal(s);
         uint256 earnedSum;
         for (uint256 i = 0; i < s.shares.length; i++) {
             address wallet = s.shares[i].wallet;
-            uint256 earned = (s.shares[i].share * pool) / SHARE_TOTAL;
+            uint256 earned = (s.shares[i].share * pool) / shareTotal;
             earnedSum += earned;
             uint256 claimed = s.claimedPeriod.amount[wallet];
             if (earned > claimed) {

test/mocks/FVMRewardActor.t.sol

@@ -348,6 +348,36 @@ contract FVMRewardActorTest is MockRewardTest {
         assertEq(exitCode, USR_ILLEGAL_ARGUMENT);
     }
 
+    function test_RegisterStream_StripsBurnSentinels_AndFloorsSurvivorPool() public {
+        uint256 third = SHARE_TOTAL / 3;
+        Share[] memory shares_ = new Share[](4);
+        shares_[0] = Share({wallet: RECIPIENT_A, share: third});
+        shares_[1] = Share({wallet: BURN_ADDRESS, share: third});
+        shares_[2] = Share({wallet: RECIPIENT_B, share: third});
+        shares_[3] = Share({wallet: BURN_ADDRESS, share: SHARE_TOTAL - third * 3});
+
+        uint32 exitCode = swaCaller.registerStream(
+            SERVICE_ID, _constantRecord(WAD), address(writerCaller), shares_, uint64(block.number) + SWA_TIMELOCK
+        );
+        assertEq(exitCode, 0);
+        _warpPastTimelockAndSettle();
+
+        Share[] memory stored = rewardActor().getShares(SERVICE_ID);
+        assertEq(stored.length, 2);
+        assertEq(stored[0].wallet, RECIPIENT_A);
+        assertEq(stored[0].share, third);
+        assertEq(stored[1].wallet, RECIPIENT_B);
+        assertEq(stored[1].share, third);
+
+        (uint256 minerPortion, uint256 servicePortion, uint256 burnAmount) = rewardActor().mockAwardBlockReward(2);
+        assertEq(minerPortion, 0);
+        assertEq(servicePortion, 1, "floor the survivor pool before deriving burn");
+        assertEq(burnAmount, 1);
+        assertEq(_streams()[0].accrued, 1);
+        assertEq(rewardActor().totalServiceMinted(), 1);
+        assertEq(rewardActor().totalBurnMinted(), 1);
+    }
+
     // Zero is reserved and could come to signify the burn stream.
     function test_RegisterStream_ZeroId_IllegalArgument() public {
         assertEq(
@@ -621,6 +651,47 @@ contract FVMRewardActorTest is MockRewardTest {
         assertEq(got[0].wallet, RECIPIENT_B);
     }
 
+    function test_SetShares_BurnSentinelCarvesAccrual_AndNeverBecomesClaimable() public {
+        _registerExplicit(SERVICE_ID, address(writerCaller)); // weight 0.1e18
+
+        Share[] memory partialBurn = new Share[](3);
+        partialBurn[0] = Share({wallet: RECIPIENT_A, share: SHARE_TOTAL / 4});
+        partialBurn[1] = Share({wallet: BURN_ADDRESS, share: SHARE_TOTAL / 2});
+        partialBurn[2] = Share({wallet: RECIPIENT_B, share: SHARE_TOTAL / 4});
+        assertEq(writerCaller.setShares(SERVICE_ID, partialBurn), 0);
+
+        Share[] memory stored = rewardActor().getShares(SERVICE_ID);
+        assertEq(stored.length, 2);
+        assertEq(stored[0].wallet, RECIPIENT_A);
+        assertEq(stored[1].wallet, RECIPIENT_B);
+
+        (, uint256 servicePortion, uint256 burnAmount) = rewardActor().mockAwardBlockReward(1 ether);
+        assertEq(servicePortion, 0.05 ether);
+        assertEq(burnAmount, 0.95 ether);
+        assertEq(_streams()[0].accrued, 0.05 ether);
+
+        (, uint256[] memory firstClaim) = _claim(SERVICE_ID, _wallets(RECIPIENT_A));
+        assertEq(firstClaim[0], 0.025 ether, "live claims divide by the stored share total");
+
+        assertEq(writerCaller.setShares(SERVICE_ID, _shares(BURN_ADDRESS, SHARE_TOTAL)), 0);
+        assertEq(rewardActor().getShares(SERVICE_ID).length, 0);
+        LedgerRow[] memory payableRows = rewardActor().getPayable(SERVICE_ID);
+        assertEq(payableRows.length, 1);
+        assertEq(payableRows[0].wallet, RECIPIENT_B);
+        assertEq(payableRows[0].amount, 0.025 ether, "folds divide by the closing stored share total");
+        assertEq(BURN_ADDRESS.balance, 0.95 ether, "the exact survivor pool leaves no fold residue");
+
+        (, uint256[] memory finalClaims) = _claim(SERVICE_ID, _wallets(RECIPIENT_B, BURN_ADDRESS));
+        assertEq(finalClaims[0], 0.025 ether);
+        assertEq(finalClaims[1], 0, "the burn sentinel never has a claimable balance");
+
+        (, servicePortion, burnAmount) = rewardActor().mockAwardBlockReward(1 ether);
+        assertEq(servicePortion, 0);
+        assertEq(burnAmount, 1 ether);
+        assertEq(rewardActor().totalServiceMinted(), 0.05 ether);
+        assertEq(rewardActor().totalBurnMinted(), 1.95 ether);
+    }
+
     function test_RemoveStream_NotSwa_Forbidden() public {
         _registerExplicit(SERVICE_ID, address(writerCaller));
         uint32 exitCode = randomCaller.removeStream(SERVICE_ID);