Skip to main content
RewardCovenant distributes variable-amount rewards per event. The authority controls the exact amount per reward, bounded by maxRewardAmount. Contract path: contracts/core/distribution/RewardCovenant.cash CashScript version: ^0.13.0

​
Constructor Parameters (Bytecode-Embedded)

ParameterTypeDescription
vaultIdbytes32Links to source vault
authorityHashbytes20Issues all rewards
maxRewardAmountintUpper bound per single reward
totalPoolintTotal reward budget
startTimestampintWhen rewards open. 0 = immediate.
endTimestampintWhen rewards close. 0 = no expiry.

​
NFT State (40 bytes)

[0]:    status
[1]:    flags
[2]:    reward_category (1=ACHIEVEMENT, 2=REFERRAL, 3=LOYALTY, 4=CUSTOM)
[3-10]: total_distributed (uint64)
[11-18]: rewards_count (uint64)
[19-23]: last_reward_timestamp (5 bytes)
[24-39]: reserved

​
Transaction Structure

All entrypoints spend reward state from tx.inputs[0].
FunctionRequired outputsNotes
rewardtx.outputs[0] recipient payout, tx.outputs[1] updated covenant UTXOVariable payout amount chosen per call, bounded on-chain.
pausetx.outputs[0] updated covenant UTXOStatus ACTIVE -> PAUSED.
resumetx.outputs[0] updated covenant UTXOStatus PAUSED -> ACTIVE.
canceltx.outputs[0] authority payoutConsumes reward UTXO.

​
Functions

​
reward(sig authSig, pubkey authPubkey, bytes20 recipientHash, int rewardAmount)

Authority-only reward issuance. Validation
  • Authority identity/signature check.
  • Status must be ACTIVE.
  • Optional time-window checks (startTimestamp, endTimestamp) via tx.locktime.
  • 0 < rewardAmount <= maxRewardAmount.
  • newTotalDistributed = totalDistributed + rewardAmount must be <= totalPool.
Output rules
  • tx.outputs[0] pays recipientHash with rewardAmount (BCH or FT mode by flag bit2).
  • tx.outputs[1] must preserve covenant bytecode/token category and commit:
    • updated total_distributed
    • updated rewards_count
    • last_reward_timestamp = tx.locktime
    • status = COMPLETED when pool is exhausted

​
pause() / resume() / cancel()

Authority-only admin paths. Pause / Resume
  • pause requires ACTIVE plus cancelable flag bit0.
  • resume requires PAUSED.
  • Both require output 0 as covenant continuation output with updated status.
Cancel
  • Requires status ACTIVE or PAUSED, plus cancelable flag bit0.
  • Computes remainingPool = totalPool - totalDistributed, requires remainingPool > 0.
  • tx.outputs[0] must pay authority with remaining BCH/FT.