ClaimReward

[Source]

(Added by the [BalanceRewards amendment][].)

Opt-in + Claim (XAH genesis rewards)

{
    "TransactionType": "ClaimReward",
    "Account": "rWYkbWkCeg8dP6rXALnjgZSjjLyih5NXm",
    "Issuer": "rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh"
}

Opt-out (XAH genesis rewards)

{
    "TransactionType": "ClaimReward",
    "Account": "rWYkbWkCeg8dP6rXALnjgZSjjLyih5NXm",
    "Flags": 1
}

IOU Reward Claim

(Requires the [IOURewardClaim amendment][].)

{
    "TransactionType": "ClaimReward",
    "Account": "rWYkbWkCeg8dP6rXALnjgZSjjLyih5NXm",
    "Issuer": "rIssuerAccountXXXXXXXXXXXXXXXXXXX",
    "ClaimCurrency": {
        "currency": "USD",
        "issuer": "rIssuerAccountXXXXXXXXXXXXXXXXXXX"
    }
}

Fields

Field	JSON Type	Internal Type	Description
Account	String	AccountID	The address of the account that is claiming the reward.
Flags	Number	UInt32	(Optional) Can have flag 1 set to opt-out of rewards.
Issuer	String	AccountID	(Optional) The genesis account (XAH rewards) or an IOU account (IOU rewards).
ClaimCurrency	Object	Issue	(Optional, IOURewardClaim) The IOU currency to claim rewards for, as {"currency": "...", "issuer": "..."}. Cannot be XAH. The issuer must not be the genesis account and must not equal Account. Requires a trustline to exist between Account and the issuer.

ClaimReward Flags

Transactions of the ClaimReward type support additional values in the Flags field, as follows:

Flag Name	Hex Value	Decimal Value	Description
tfOptOut	0x00000001	1	Opts the account out of rewards by removing reward-related fields from the account’s ledger object.

Special Transaction Cost

The ClaimReward transaction has a standard transaction cost, which is the minimum transaction cost required for all transactions.

IOU Reward Behaviour

(Requires the [IOURewardClaim amendment][].)

When ClaimCurrency is specified, the transaction follows the IOU reward path:

1. The Issuer account must have a Hook installed that fires on a ClaimReward transaction. The Hook is responsible for calculating and distributing the reward payout.
2. On first claim, a LowReward or HighReward reward-tracking object is initialised on the trustline (RippleState ledger object) between Account and the issuer. Which side is used depends on the canonical high/low ordering of the two accounts.
3. After every subsequent transaction that changes the trustline balance, the ledger automatically updates TrustLineRewardAccumulator inside the tracking object using the same area-under-the-curve formula as genesis XAH rewards.
4. When a ClaimReward with ClaimCurrency is submitted, the ledger resets the reward counters on the trustline and fires the issuer’s Hook, which reads the accumulated value and emits a reward payment.

The IOU reward counters are entirely independent of the genesis XAH reward fields on the AccountRoot object.

Error Cases

Besides errors that can occur for all transactions, ClaimReward transactions can result in the following transaction result codes:

Error Code	Description
temDISABLED	Occurs if the required amendment (BalanceRewards or IOURewardClaim) is not enabled.
temINVALID_FLAG	Occurs if the flag is set to a value other than 1. (Requires the [fixRewardClaimFlags amendment][].)
temMALFORMED	Occurs if ClaimCurrency is a non-currency or XAH type, if the issuer equals Account, or if the transaction fields are otherwise incorrectly set.
temBAD_ISSUER	Occurs if ClaimCurrency is set but the issuer is the genesis account, or if Issuer is the genesis account but ClaimCurrency is also set.
terNO_ACCOUNT	Occurs if the sending account does not exist.
tecNO_ISSUER	Occurs if the Issuer account does not exist.
tecNO_PERMISSION	Occurs if the issuer account is an AMM account. AMM accounts cannot have reward Hooks.
tecNO_TARGET	Occurs if the issuer account has no Hooks, or none of its Hooks fires on a ClaimReward transaction.
tecNO_LINE	Occurs if no trustline exists between Account and the issuer for the specified ClaimCurrency.