Add GET Route /defi/rewards to Centralize DeFi Spring Reward Collection

[Marchand-Nicolas]

Add GET Route /defi/rewards to Centralize DeFi Spring Reward Collection

Issue Summary

We need to implement a new GET route /defi/rewards that accepts an addr parameter (user address) and returns:

• All available STARK rewards for the specified address.
• A calls array, where each call is an object containing:
  • entryPoint (function name, e.g., "claim")
  • contract (contract address)
  • callData (string array)

The primary goal is to centralize the collection of DeFi Spring rewards, enabling users to execute all claim calls in a single multicall transaction.

Background and Motivation

Currently, users have to interact with multiple protocols individually to claim their DeFi Spring rewards. By aggregating this process into a single API route, we can streamline reward collection, improve user experience, and reduce transaction overhead.

Protocols to Integrate

We need to fetch reward data from the following protocols:

1. ZkLend
2. Nostra
3. Nimbora
4. Ekubo

Each protocol provides an API to retrieve reward information and the necessary data to construct claim calls.

---

1. ZkLend

• Endpoint: GET https://app.zklend.com/api/reward/all/{address}

• Response Example:

  [
  {
    "amount": {
      "decimals": 18,
      "value": "0x201aeb1ca717e5e47"
    },
    "claim_contract": "0x01a9acedc9a858ec3a2b6e5b2540aab67c6fab3376c5d56b44dfc3c18d727663",
    "claim_id": 381,
    "claimed": false,
    "proof": ["0x3fe2045d6ab41b5981b14742ce2c7db0...", "..."],
    "recipient": "{address}",
    "token": {
      "decimals": 18,
      "name": "Starknet Token",
      "symbol": "STRK"
    },
    "type": "defispring"
  },
  ...
  ]

• Claim Function: Typically called claim on the claim_contract.

2. Nostra

• Endpoint: POST https://us-east-2.aws.data.mongodb-api.com/app/data-yqlpb/endpoint/data/v1/action/find

• Request Body:

  {
  "dataSource": "nostra-production",
  "database": "prod-a-nostra-db",
  "collection": "rewardProofs",
  "filter": {
    "account": "{address}"
  }
  }

• Response Example:

  {
  "documents": [
    {
      "_id": "660544c812ccdf78a8a06ba2",
      "id": "2024-03-14_2024-03-28-DEFISPRING-{address}",
      "account": "{address}",
      "proofs": ["169159593765095689312881262234915...", "..."],
      "reward": "8647713505617622833",
      "rewardFrom": "DEFISPRING",
      "rewardId": "2024-03-14_2024-03-28"
    },
    ...
  ]
  }

• Reward Contract: 0x008faa2edc6833a6ad0625f1128d56cf471c3f9649ff2201d9ef49d7e9bb18de

3. Nimbora

• Endpoint: GET https://strk-dist-backend.nimbora.io/get_calldata?address={address}

• Response Example:

  {
  "amount": "0xb038a62cf54f1cf",
  "proof": ["0x595490f7baf186ce2713083bc7fc79fa...", "..."]
  }

• Reward Contract: 0x07ed46700bd12bb1ee8a33a8594791003f9710a1ab18edd958aed86a8f82d3d1

4. Ekubo

• Endpoint: GET https://mainnetapi.ekubo.org/airdrops/{address}?token={token_address}

• Response Example:

  [
  {
    "contract_address": "0x0db7a187d50a4ca88396bb97dd375ae308f71e7a2eb7d2a1ce887b7f808c1a2",
    "token": "{token_address}",
    "start_date": "2024-06-13T00:00:00.000Z",
    "end_date": "2024-06-27T00:00:00.000Z",
    "claim": {
      "id": 158,
      "amount": "435891192382960959488",
      "claimee": "{address}"
    },
    "proof": ["0x4eacb55ec0f4127e47c8ff53217a93e7...", "..."]
  },
  ...
  ]

---

Proposed Implementation

1. Create the GET Route

• Endpoint: /defi/rewards
• Method: GET
• Parameters:
  • addr (string, required): User's wallet address.

2. Route Handler Logic

• Fetch Rewards:

  • For each protocol, send the appropriate API request to retrieve reward data for the provided addr.
  • Parse the responses to extract necessary information such as amount, proof, contract, etc.

• Construct the calls Array:

  • For each reward, build a call object with the following structure:

  {
    "entryPoint": "claim",
    "contract": "{contract_address}",
    "callData": ["{arguments_required_by_contract_function}"]
  }

  • The callData array should contain all the necessary arguments for the claim function, such as claim_id, amount, proof, etc.

• Return Response:

  • Respond with a JSON object containing:
  • rewards: Detailed reward information from all protocols.
  • calls: The array of call objects ready for multicall execution.

3. Example Response

{
  "rewards": [
    {
      "protocol": "ZkLend",
      "amount": "0x201aeb1ca717e5e47",
      "token": "STRK",
      "contract": "0x01a9acedc9a858ec3a2b6e5b2540aab67c6fab3376c5d56b44dfc3c18d727663",
      "claimId": 381,
      "claimed": false,
      "proof": ["0x3fe2045d6ab41b5981b14742ce2c7db0...", "..."]
    },
    ...
  ],
  "calls": [
    {
      "entryPoint": "claim",
      "contract": "0x01a9acedc9a858ec3a2b6e5b2540aab67c6fab3376c5d56b44dfc3c18d727663",
      "callData": [
        "381", // claim_id for ZkLend
        "{address}",
        "0x201aeb1ca717e5e47", // amount
        ["0x3fe2045d6ab41b5981b14742ce2c7db0...", "..."] // proof array
      ]
    },
    ...
  ]
}

Implementation Steps

1. Setup Route

   Add the new route to the API using the existing framework (e.g., Axum for Rust).

   #[route(get, "/defi/rewards")]
   pub async fn get_defi_rewards(
      State(state): State<Arc<AppState>>,
      Query(params): Query<HashMap<String, String>>,
   ) -> impl IntoResponse {
      // Handler logic here
   }

2. Validate Input

   • Ensure the addr parameter is provided and is a valid address format.

3. Fetch Data from Protocols

   • ZkLend:

     let zklend_url = format!("https://app.zklend.com/api/reward/all/{}", addr);
     let zklend_response = client.get(&zklend_url).send().await?;
     let zklend_rewards = zklend_response.json::<Vec<ZkLendReward>>().await?;

   • Nostra:

     let nostra_request_body = serde_json::json!({
      "dataSource": "nostra-production",
      "database": "prod-a-nostra-db",
      "collection": "rewardProofs",
      "filter": { "account": addr.to_lowercase() }
     });
     let nostra_response = client
      .post("https://us-east-2.aws.data.mongodb-api.com/app/data-yqlpb/endpoint/data/v1/action/find")
      .json(&nostra_request_body)
      .send()
      .await?;
     let nostra_rewards = nostra_response.json::<NostraResponse>().await?;

   • Nimbora:

     let nimbora_url = format!("https://strk-dist-backend.nimbora.io/get_calldata?address={}", addr);
     let nimbora_response = client.get(&nimbora_url).send().await?;
     let nimbora_reward = nimbora_response.json::<NimboraReward>().await?;

   • Ekubo:

     let ekubo_url = format!(
      "https://mainnetapi.ekubo.org/airdrops/{}?token={}",
      addr, ekubo_token_address
     );
     let ekubo_response = client.get(&ekubo_url).send().await?;
     let ekubo_rewards = ekubo_response.json::<Vec<EkuboReward>>().await?;

4. Construct Rewards

   • Array containing one element per protocol

   • Each element correspond to one line of the following modal:

     

   • In each element, just set the field required by the modal (protocol name, image, reward amounts & tokens).

5. Construct Calls

   • For each protocol, map the reward data to a call object.

   • Example for ZkLend:

     let zklend_calls: Vec<Call> = zklend_rewards
      .iter()
      .filter(|reward| !reward.claimed)
      .map(|reward| Call {
          entry_point: "claim".to_string(),
          contract: reward.claim_contract.clone(),
          call_data: vec![
              reward.claim_id.to_string(),
              addr.clone(),
              reward.amount.value.clone(),
              serde_json::to_string(&reward.proof).unwrap(),
          ],
      })
      .collect();

6. Aggregate Results

   • Combine rewards and calls from all protocols.

   let all_rewards = vec![/* rewards from all protocols */];
   let all_calls = vec![/* calls from all protocols */];

7. Return the Response

   let response = serde_json::json!({
      "rewards": all_rewards,
      "calls": all_calls
   });
   (StatusCode::OK, Json(response)).into_response()

Error Handling

• External API Failures: Implement retries and fallback mechanisms for API calls.
• Invalid Data: Validate and sanitize all external data before processing.
• Timeouts: Set appropriate timeouts for HTTP requests.

Testing

• Integration Tests:

  • End-to-end tests hitting the actual APIs (consider rate limits and API usage policies).

Additional Notes

• Contract Entry Points: While the common function name is claim, verify each protocol's contract to confirm the correct entry point using Voyager or StarkScan.
• Call Data Formatting: Ensure that the callData arrays are correctly formatted according to each contract's ABI.
• Dependency Management: Add any new dependencies required for HTTP requests or JSON parsing if not already present.

Example Code Snippet

#[route(get, "/defi/rewards")]
pub async fn get_defi_rewards(
    State(state): State<Arc<AppState>>,
    Query(params): Query<HashMap<String, String>>,
) -> impl IntoResponse {
    let addr = match params.get("addr") {
        Some(address) => address,
        None => return get_error("Missing 'addr' parameter".to_string()),
    };

    // Initialize HTTP client
    let client = reqwest::Client::new();

    // Fetch and process rewards from all protocols
    // ...

    // Aggregate rewards and calls
    let response = serde_json::json!({
        "rewards": all_rewards,
        "calls": all_calls
    });

    (StatusCode::OK, Json(response)).into_response()
}

---

Action Items

• [ ] Implement the /defi/rewards GET route with the specified functionality.
• [ ] Test the route thoroughly with various addresses and scenarios.

References

• Existing API Code: Refer to the provided example route from our API for structure and best practices.
• Testing Tools: Utilize HTTPie for testing API endpoints during development.

[0xdevcollins]

Hello @Marchand-Nicolas, I would like to work on this task. Could you please assign it to me?

Here’s how I’ll approach the issue:

Create the /defi/rewards GET Accept a user's wallet address (addr). Return STARK rewards and the necessary claim data for a multicall transaction.

Fetch rewards from four protocols: ZkLend: Retrieve rewards using the API and parse response. Nostra: Use a POST request to fetch reward proofs. Nimbora: Send a GET request to get calldata. Ekubo: Fetch airdrop rewards with token information.

Construct response: Build the rewards and calls objects with entry points, contract addresses, and call data for each protocol.

Handle errors: Validate input, retry failed API calls, and handle timeouts.

Test thoroughly: Use various addresses and edge cases, ensuring proper functionality across all integrated protocols.

[Benjtalkshow]

Hello @Marchand-Nicolas Please kindly assign this task to me. i will make sure a deliver a quality work. I am a Full Stack Developer with extensive experience in blockchain development, specializing in Next.js, TypeScript, Node.js, and Rust. With over 18 contributions across projects in the OnlyDust ecosystem, I’ve developed a strong proficiency in delivering high-quality solutions and tackling complex issues under tight deadlines. My experience spans frontend, backend, smart contract development, and a deep understanding of optimizing and maintaining scalable codebases.

The goal of this task is to implement a new GET route /defi/rewards that simplifies the process of claiming DeFi Spring rewards by centralizing everything into one call.

1. Users currently need to interact with multiple protocols to claim their rewards, which can be time-consuming and inefficient. This route will accept a user address and fetch available rewards from various DeFi protocols like ZkLend, Nostra, Nimbora, and Ekubo.
2. It will return both the detailed rewards data and a set of claim call objects, each containing the necessary contract information, function entry points, and call data. By bundling these claim calls into a single multicall transaction, users can execute all reward claims at once, improving the overall user experience and reducing transaction overhead. This centralized approach streamlines the reward collection process and provides a more efficient way for users to manage their DeFi Spring rewards.

How i plan to tackle it

• I'll begin by creating a new GET route that accepts a user’s address as input. The route will fetch available rewards from DeFi protocols like ZkLend, Nostra, Nimbora, and Ekubo using their APIs or SDKs. Once the data is gathered,
• I'll generate claim call objects, each containing contract details, function entry points, and required call data for reward claims. These objects will be bundled into a multicall transaction, allowing users to claim all rewards in one go.
• The route’s response will include both a reward breakdown and the multicall transaction, streamlining the process for users. Testing will be done to ensure accurate reward fetching and claiming, with the API working as expected.

The route will be added under the endpoints directory, and main.rs will be updated to register the route. Also, Helper functions will be placed in utils.rs for code reusability.

[od-hunter]

Can I be assigned this please @Marchand-Nicolas ? I’ve gone through the proposed implementation and I’m ready to do just that. Please

[Ugo-X]

@Marchand-Nicolas , I would love to work on this. I have experience working with this pools from issues i worked on, in starkfarm, and i will be able to send a PR in line with the time schedule.

[GideonBature]

I would love to work on this. I have some experience building APIs using Actix-web, I believe my knowledge of Rust and Actix-web is also applicable in Axum. I also made my first contribution to the Starknet Quest in the just concluded ODhack8.0

[JoE11-y]

Applying for this task. Would love to take it on.