Read and Claim Rewards

Same-chain reward claim

If the ZK-attested rewards information is submitted to the same chain that hosts the campaign for users to claim rewards, the reward claim process is straightforward: call the following functions.

// claim reward, send reward token to the earner
function claim(address earner) external;

// claim reward, send reward token to address specified by the earner (msg.sender)
function claimWithRecipient(address to) external;

One can obtain a user's cumulative rewards and unclaimed rewards through the following view functions.

struct AddrAmt {
    address token;
    uint256 amount;
}

// get cumulative rewards
function viewTotalRewards(address user) external view returns (AddrAmt[] memory) ;
// get unclaimed rewards
function viewUnclaimedRewards(address earner) external view returns (AddrAmt[] memory);

Cross-chain reward claim

To reduce the gas cost of the campaign on an expensive chain (e.g., Ethereum), we can configure the system to submit ZK-attested rewards on a more affordable chain (e.g., Optimism, Arbitrum), then bridge the Merkle root of all rewards back to the campaign chain.

In this case, there are 2 contracts:

Rewards Submission contract where the ZK-proved rewards are submitted. The Rewards Submission contract builds and stores the entire reward Merkle tree.
Rewards Claim contract that synchronizes the Merkle root from the Rewards Submission contract. Users interact with this contract to claim their rewards by providing a Merkle proof. This contract also escrows the rewards and stores each user’s already-claimed reward amount.

To claim rewards, the user needs to

Obtain the reward information along with the Merkle proof by calling the Get Reward Merkle Proof API.
Submit the reward information along with the Merkle proof to the Reward Claim contract.

NOTE: There is also a "ClaimAll" contract which can help claim a user's rewards from multiple campaigns in a single transaction. See here for details.

// claim reward, send reward token to the earner
function claim(
    address earner, 
    uint256[] calldata cumulativeAmounts, 
    uint64 epoch, 
    bytes32[] calldata proof) external;

// claim reward, send reward token to address specified by the earner (msg.sender)    
function claimWithRecipient(
    address to,
    uint256[] calldata cumulativeAmounts,
    uint64 _epoch,
    bytes32[] calldata proof
) external

To get a user's claimable reward amount:

A user's currently claimable reward amount and the cumulative reward amount can be obtained by calling the Get Reward Merkle Proof API (enclosed together with the Merkle proof) or Get Reward Balance API (an API dedicated to display a user's reward balances).

Get Reward Merkle Proof API

This API returns the reward info and the corresponding Merkle proofs of a specific user in multiple campaigns that the user has participated in (i.e., has non-zero cumulative rewards in the campaign) and match the supplied filters in the request. The data included in the response can be used to call the claim or claimWithRecipient functions of the claim chain contract.

Endpoint

POST https://incentra-prd.brevis.network/v1/getMerkleProofsBatch

Request Fields

The request data should specify a user address and multiple filters for the campaign.

NOTE: user_addr is a required field while other filters are optional. If any filter is not specified in the request, it means no constraint for the filter.

Field

Type

Description

user_addr

string

The user address.

types

[CampaignType]

The campaign types (the detailed enum will be specified later).

chain_id

[uint64]

The chain IDs where the DEX pools/Euler vaults/tokens are deployed.

status

[CampaignStatus]

The campaign statuses with enum: INACTIVE = 3

ACTIVE = 4

ENDED = 5

campaign_id

[string]

The campaign IDs.

CampaignType enum:

Liquidity campaign (Uniswap v3) = 1
Liquidity campaign (PancakeSwap v3) = 3
Liquidity campaign (QuickSwap v3) = 5
Token holding campaign = 1001
Euler borrow campaign = 2001
Euler lend campaign = 2002

Response Fields

Field

Type

Description

err

ErrMsg

Error details if the request failed.

rewardsBatch

[SingleCampaignMerkle]

An array that includes the details about rewards info and the corresponding Merkle proofs of the user in all the campaigns that user has participated in and match the filters.

ErrMsg Fields

Field

Type

Description

code

string

Error code

msg

string

Error reason

SingleCampaignMerkle Fields

Fileld

Type

Description

campaignId

string

The campaign ID.

epoch

string

The rewards in the Merkle tree is accumulated up to this epoch number.

claimChainId

string

The claim chain ID.

claimContractAddr

string

The claim contract address.

cumulativeRewards

[string]

The cumulative reward amount earned by the user in the campaign so far.

merkleProof

[string]

The Merkle path proof to be submitted to the claim contract.

claimableRewards

string

The claimable reward amount of this user in the campaign.

Example Request (curl)

curl --location 'https://incentra-prd.brevis.network/v1/getMerkleProofsBatch' \
--header 'Content-Type: application/json' \
--data '{
    "user_addr": "0x0195b198088e464103e3840f52a1fa9ea81de84b",
    "types": [
        1001
    ],
    "chain_id": [
        1
    ],
    "status": [],
    "campaign_id": []
}'

Get Reward Balance API

This API returns the cumulative and claimable reward balances of a specific user in all campaigns the user has participated in and match the specified filters.

Endpoint

POST https://incentra-prd.brevis.network/v1/getUserRewardsBatch

Request Fields

The request data should specify a user address and multiple filters for the campaign.

NOTE: user_addr is a required field while other filters are optional. If any filter is not specified in the request, it means no constraint for the filter.

Field

Type

Description

user_addr

string

The user address.

types

[CampaignType]

The campaign types (the detailed enum will be specified later).

chain_id

[uint64]

The chain IDs where the DEX pools/Euler vaults/tokens are deployed.

status

[CampaignStatus]

The campaign statuses with enum: INACTIVE = 3

ACTIVE = 4

ENDED = 5

campaign_id

[string]

The campaign IDs.

CampaignType enum:

Liquidity campaign (Uniswap v3) = 1
Liquidity campaign (PancakeSwap v3) = 3
Liquidity campaign (QuickSwap v3) = 5
Token holding campaign = 1001
Euler borrow campaign = 2001
Euler lend campaign = 2002

Response Fields

Field

Type

Description

err

ErrMsg

Error details if the request failed.

rewardsBatch

[SingleCampaignReward]

An array that contains the reward balances of the user in all the campaigns that user has participated in and match the filters.

ErrMsg Fields

Field

Type

Description

code

string

Error code.

msg

string

Error reason.

SingleCampaignReward Fields

Fileld

Type

Description

cumulative

string

The cumulative reward amount earned by the user in the campaign.

claimable

string

The claimable reward amount of the user in the campaign.

campaignId

string

The campaign ID.

claimChainId

string

The claim chain ID.

Example Request (curl)

curl --location 'https://incentra-prd.brevis.network/v1/getUserRewardsBatch' \
--header 'Content-Type: application/json' \
--data '{
    "user_addr": "0x0195b198088e464103e3840f52a1fa9ea81de84b",
    "types": [
        1001
    ],
    "chain_id": [
        1
    ],
    "status": [],
    "campaign_id": []
}'

Claim all rewards in a single transaction

A user can claim all rewards from all participated campaigns on a given chain in a single transaction by calling the following functions of the ClaimAll contract deployed on that chain:

// claim all same-chain rewards
function claimAll(address earner, address[] calldata campaignAddrs) external;

// claim all cross-chain rewards 
// calldata can be fetched using the getMerkleProofsBatch API
struct CampaignReward {
    address campaignAddr; // the campaign claim contract address
    uint256[] cumulativeAmounts;
    uint64 epoch;
    bytes32[] proof;
}
function claimAll(address earner, CampaignReward[] calldata campaignRewards) external;

// claim all same-chain and cross-chain rewards
function claimAll(
    address earner, 
    address[] calldata sameChainCampaignAddrs, 
    CampaignReward[] calldata crossChainCampaignRewards) external;