Balance Rewards
The Balance Rewards feature is a unique aspect of the Xahau network that allows users to accumulate and claim rewards based on their account balance. This feature is implemented through a combination of native code (BalanceRewards Amendment) and hook code (Genesis Account’s Reward Hook).
Transaction Types
Section titled “Transaction Types”ClaimReward
Section titled “ClaimReward”A ClaimReward transaction allows an account to claim the rewards it has accumulated. The rewards can be claimed by the account owner or by a specified issuer. The account can also opt-out of rewards by setting the Flags field to 1.
GenesisMint
Section titled “GenesisMint”The GenesisMint transaction type is also associated with the Balance Rewards feature. This is an Emitted transaction that is executed through the Reward Hook every time a user claims balance rewards.
IOU Reward Claim
Section titled “IOU Reward Claim”(Requires the IOURewardClaim amendment.)
The IOURewardClaim amendment extends the reward mechanic to IOU currencies issued by any account. The same area-under-the-curve calculation (hold time × hold amount) that governs XAH genesis rewards is applied to IOU token holders, with the issuer’s Hook controlling payout logic.
How it works
Section titled “How it works”- Opt-in: A token holder submits a
ClaimRewardtransaction with theClaimCurrencyfield specifying the IOU. This initialises reward-tracking counters (LowRewardorHighReward) directly on the trustline (RippleState ledger object). - Accumulation: After every transaction that modifies the trustline balance, the ledger automatically updates the
TrustLineRewardAccumulatorfield. This tracks the cumulative product of balance × ledgers elapsed since the last reset. - Claim: When the holder submits another
ClaimRewardwithClaimCurrency, the ledger resets the counters and fires the issuer’s Hook (which must be installed and must fire onClaimRewardtransaction). The Hook reads the accumulated value and emits a reward payment in whatever form the issuer chooses.
Key differences from XAH genesis rewards
Section titled “Key differences from XAH genesis rewards”| XAH Genesis Rewards | IOU Rewards | |
|---|---|---|
| Amendment | BalanceRewards | IOURewardClaim |
| Counters stored on | AccountRoot | RippleState (trustline) |
| Accumulator type | UInt64 (drops / 1,000,000) | Amount (in the token’s units) |
| Payout handled by | Genesis account Hook | Issuer account Hook |
| Issuer restriction | Must be genesis account | Any account with a Hook on ClaimReward transaction, except AMM accounts |