Compound v3 accrued rewards and claim payout reconciliation

Compound v3 pays claimable rewards through a separate rewards contract using the account's accrued entitlement and previously claimed balance. A claim can update accrual before calculating the unpaid amount, so an earlier preview may differ from the eventual transfer. To reconcile a payout, keep the market, source account, reward token, and recipient consistent. Then compare the transaction's reward event with the token transfer and updated claim accounting.

Supply and borrow tracking behind the reward balance

Base-asset suppliers and borrowers accumulate reward tracking through separate indices, with each side subject to its configured speed and aggregate participation threshold. The supply index advances when total supply principal meets baseMinForRewards; the borrow index uses total borrow principal. A positive speed and elapsed time also matter. This threshold concerns the relevant market total, rather than a universal minimum reward balance for an individual claim. Collateral deposits alone do not produce this base-asset tracking.

The account's recorded accrual connects that participation history to its reward entitlement. Its position today does not, by itself, explain everything that accrued earlier. Repayment or withdrawal can change future participation while an unpaid entitlement remains.

A positive entitlement still requires a funded payout

The rewards contract needs enough of the configured reward token to complete its transfer, even when its accounting shows a positive unpaid amount. Accrual records and token inventory serve different purposes. Calculating what an account is owed does not reserve tokens for it or demonstrate that payment will succeed.

Open full-size image

A failed transfer reverts the claim's state changes. The attempted increase in claimed rewards therefore does not survive that reverted call. An executed failure can still consume transaction fees, which makes repeated submissions costly when the underlying funding or transfer problem remains unchanged.

A starting record tied to the actual market and account

A useful starting record identifies the network, Comet market, rewards contract, source account, and configured token alongside the block used for each read. These details prevent a comparison between unrelated balances. Record the recipient separately whenever it differs from the source account. A wallet that submits a transaction is not necessarily the account that earned the rewards or the address that receives them.

Keep the raw stored accrual, previously claimed amount, and refreshed amount owed distinguishable. Their labels can look similar in an interface, although they answer different questions. The stored figure describes recorded tracking; the owed figure accounts for conversion and previous claims.

Block context matters. A later read can include activity that an earlier preview could not contain.

Refreshed accrual and stored accrual produce different comparisons

The shouldAccrue argument controls whether the claim updates the account before calculating payment, making it central to any comparison with a preview.

Claims that update the account first

When shouldAccrue is true, the claim calls accrueAccount before calculating the unpaid reward amount. This includes the account update in the claim transaction. An older displayed amount can therefore differ from the execution amount without indicating a transfer error. The relevant comparison uses the accounting that applies when the transaction executes.

Claims that use existing storage

With shouldAccrue set to false, the claim uses the accrual already recorded for that account. By contrast, getRewardOwed calls the accrual function before returning its calculation. A simulated read of that function does not persist the update on-chain. Consequently, its refreshed result can exceed what a subsequent claim using unchanged storage calculates. The preview and claim must use compatible accrual assumptions.

The recipient follows the claim function and its permissions

The standard claim function sends rewards to the source account, while claimTo accepts a separate recipient and checks the caller's account permission. This distinction determines where the payout should appear. The outer transaction's destination identifies the contract being called; the reward recipient comes from the claim's arguments and resulting event.

For claimTo, the account owner or an authorized manager can select the destination. Manager permission extends beyond reward collection and can permit withdrawals or transfers from the account. It should not be treated as a narrowly scoped claim approval. An address that merely triggers a standard claim cannot use that function to redirect the payment.

A completed transfer has no claim-level undo operation. Recipient selection must be settled before submission.

Tracking units need conversion before subtraction

The raw value returned by baseTrackingAccrued is an accounting quantity that the rewards contract converts before comparing it with previously claimed tokens. Its configuration specifies the token and rescaling direction. Implementations with a configured multiplier apply that factor after rescaling. Integer division can discard fractional remainder, so a calculation using rounded display values may disagree with contract arithmetic.

Let A denote cumulative accrued rewards after the applicable conversion, expressed in the token's smallest units. Let C denote rewardsClaimed for the same market and account. The unpaid amount is max(A - C, 0). Token decimals then determine its human-readable representation. Apply the deployed contract's conversion rules before subtracting; do not subtract token-denominated claims directly from an unconverted tracking balance.

The payout record connects accounting with token movement

The RewardClaimed event identifies the source account, recipient, token, and amount, allowing a completed payout to be matched to its intended destination. Inspect the event from the correct rewards contract within the successful transaction. The token's Transfer event supplies a separate record of token movement. Compare raw amounts before applying display rounding.

A recipient balance change offers further confirmation, provided other transfers or token-specific balance changes do not distort the comparison. For a straightforward transfer, the increase should match the received amount. A wallet's displayed portfolio value cannot substitute for this check because valuation and token quantity measure different things.

Transaction success alone is insufficient. If converted accrual does not exceed the claimed balance, the claim can finish without a payout event.

A payout mismatch needs a transaction-level explanation

A mismatch between displayed rewards and received tokens should first be classified as a failed claim, an empty claim, or a completed transfer with different expectations. A reverted claim requires attention to its failure reason. An empty claim calls for comparing converted accrual with the existing claimed balance. A completed transfer requires matching the actual token and recipient before investigating the amount.

Timing can explain an otherwise valid discrepancy. Another claim may have consumed the unpaid balance after the preview, or fresh accrual may have increased it before execution. Decimal conversion can also change the displayed number. Reconstruct the calculation at the transaction's execution point rather than treating every difference as missing funds.

Before resubmitting, identify why the previous claim failed, paid nothing, or paid a different amount. It cannot retrieve tokens that already reached another recipient.

Administrative accounting can affect historical reconciliation

The rewards contract's governor can set claimed amounts for accounts, so the stored claimed balance need not equal only the payouts visible in a selected transaction history. The contract emits RewardsClaimedSet for those adjustments. This matters when reconciling an opening balance or investigating why a present entitlement differs from a sum of previously observed claim events.

Separate administrative adjustments from ordinary payouts in the record. Neither a configuration entry nor an accounting adjustment proves that tokens reached the recipient. The transfer transaction supplies that evidence. Likewise, a source-code feature does not establish that every deployed rewards contract uses identical conversion settings.

Transaction cost and the next claim decision

A claim consumes network execution resources, and its cost depends on the network's fee conditions and the work that the transaction performs. Updating accrual adds work relative to using existing storage, although a fixed saving cannot be assumed. Compare the estimated transaction cost with the unpaid reward quantity using a consistent valuation basis when deciding whether to submit.

After a reconciled payout, the remaining question is whether another payable balance exists. Use a fresh amount-owed calculation with its block context. Further participation may create additional rewards; a repeated submission against an unchanged, fully claimed entitlement has no additional tokens to distribute.

Compound v3 FAQ