Merge pull request #52 from ethena-labs/f/pe-87-add-delegated-l2-integration-examples-to-the-adapters-repo

F/pe 87 add delegated l2 integration examples to the adapters repo

Author: FJ-Riveros

.env.example

@@ -6,5 +6,6 @@ MODE_NODE_URL='https://mainnet.mode.network'
 FRAXTAL_NODE_URL='https://rpc.frax.com'
 LYRA_NODE_URL='https://rpc.derive.xyz'
 SWELL_NODE_URL='https://rpc.ankr.com/swell'
+SOLANA_NODE_URL='https://api.mainnet-beta.solana.com'
 
 DERIVE_SUBGRAPH_API_KEY=''

.gitignore

@@ -163,3 +163,4 @@ cython_debug/
 #  and can be added to the global gitignore or merged into this file.  For a more nuclear
 #  option (not recommended) you can uncomment the following to ignore the entire idea folder.
 #.idea/
+node_modules

README.md

@@ -8,23 +8,71 @@ For your protocol to be included and your users to receive points, you should su
 
 1. Make a copy of `.env.example` and name it `.env`.
 2. Run `pip install -r requirements.txt` to install the required packages.
+   - If using TypeScript scripts (recommended for L2 delegated integrations), also run `pnpm install` or `npm install` in the root directory.
 3. Add your integration metadata to `integrations/integration_ids.py`.
 4. Create a new summary column in `constants/summary_columns.py`.
-5. Make a copy of [Template](integrations/template.py), naming the file `[protocol name]_integration.py` and place in the `integrations` directory.
-6. Your integration must be a class that inherits from `CachedBalancesIntegration` and implements the `get_block_balances` method.
-7. The `get_block_balances` method should return a dict of block numbers to a dict of user addresses to balances at that block. (Note: Not all blocks are queried by this service in production- only a sampling, but your code should be capable of handling any block number.)
-8. Write some basic tests at the bottom of the file to ensure your integration is working correctly.
-9. Submit a PR to this repo with your integration and ping the Ethena team in Telegram.
+5. Choose your integration type:
+   - For EVM compatible chains: Copy [CachedBalancesTemplate](integrations/template.py)
+   - For non-EVM chains (e.g. Solana): Copy [L2DelegationTemplate](integrations/l2_delegation_template.py)
+     - We strongly recommend using a TypeScript script or similar to fetch balances for better reliability and maintainability
+     - See [KaminoL2DelegationExampleIntegration](integrations/kamino_l2_delegation_example_integration.py) for the recommended TypeScript approach
+       - Create your TypeScript script in the `ts/` directory
+       - Use the Kamino example as a reference for calling your script from Python
+     - API integration is also supported but less preferred (see [RatexL2DelegationExampleIntegration](integrations/ratex_l2_delegation_example_integration.py))
+6. Name your file `[protocol name]_integration.py` and place it in the `integrations` directory.
+7. Your integration must inherit from either:
+   - `CachedBalancesIntegration` and implement the `get_block_balances` method
+   - `L2DelegationIntegration` and implement the `get_l2_block_balances` and `get_participants_data` methods
+8. The integration should return user balances:
+   - For CachedBalances: Return a dict of {block_number: {checksum_address: balance}}
+   - For L2Delegation: Return a dict of {block_number: {address: balance}}
+9. Write some basic tests at the bottom of the file to ensure your integration is working correctly.
+10. Submit a PR to this repo with your integration and ping the Ethena team in Telegram.
 
 # Guidelines
 
 - Integrations must follow this architecture and be written in python.
-- Pendle integrations are included as examples of functioning integrations. Run `python -m integrations.pendle_lpt_integration` to see the output.
 - The `get_block_balances` method should be as efficient as possible. So the use of the cached data from previous blocks if possible is highly encouraged.
 - We prefer that on chain RPC calls are used to get information as much as possible due to reliability and trustlessness. Off chain calls to apis or subgraphs are acceptable if necessary. If usage is not reasonable or the external service is not reliable, users may not receive their points.
 
-# Example Integrations
-- [ClaimedEnaIntegration](integrations/claimed_ena_example_integration.py): This integration demonstrates how to track ENA token claims using cached balance snapshots for improved performance. It reads from previous balance snapshots to efficiently track user claim history.
-- [BeefyCachedBalanceExampleIntegration](integrations/beefy_cached_balance_example_integration.py): This integration is an example of a cached balance integration that is based on API calls.
-- [PendleLPTIntegration](integrations/pendle_lpt_integration.py): (Legacy Example) A basic integration showing Pendle LPT staking tracking. Note: This is a non-cached implementation included only for reference - new integrations should use the cached approach for better efficiency.
-- [PendleYTIntegration](integrations/pendle_yt_integration.py): (Legacy Example) A basic integration showing Pendle YT staking tracking. Note: This is a non-cached implementation included only for reference - new integrations should use the cached approach for better efficiency.
+# L2 Delegation Setup Requirements
+
+For non-EVM chain integrations (like Solana) or users that don't control the same addresses in the L2 and Ethereum, your users must complete an additional delegation step to receive points. This process links their L2 wallet to their Ethereum address:
+
+1. Visit the [Ethena UI](https://app.ethena.fi) and connect your Ethereum wallet
+2. Navigate to [Ethena Delegation Section](https://app.ethena.fi/delegation)
+3. Click "Select Chain" and select.
+<img src="readme_assets/select_chain.png" alt="Select Chain" style="float: left; clear: left;">
+
+4. Click "Signing With" and select your wallet type.
+<img src="readme_assets/select_wallet_type.png" alt="Select Wallet Type" style="float: left; clear: left;">
+
+5. Connect your wallet and sign a message to prove ownership
+6. Once delegated, your L2 balances will be attributed to your Ethereum address for points calculation
+
+**Important Notes:**
+- Users can delegate at any moment and they won't miss any past points.
+
+# Examples
+## Cached Balances Integrations (Default)
+- [ClaimedEnaIntegration](integrations/claimed_ena_example_integration.py): This integration demonstrates how to track ENA token claims using cached balance 
+snapshots for improved performance. It reads from previous balance snapshots to efficiently track user claim history.
+- [BeefyCachedBalanceExampleIntegration](integrations/beefy_cached_balance_example_integration.py): This integration is an example of a cached balance integration 
+that is based on API calls.
+
+## L2 Delegation Examples (For non-EVM chains)
+- [KaminoL2DelegationExampleIntegration](integrations/kamino_l2_delegation_example_integration.py)
+  - Example of L2 delegation for Solana chain
+  - Uses TypeScript script to query Kamino balances
+  - Demonstrates cross-chain integration pattern
+
+- [RatexL2DelegationExampleIntegration](integrations/ratex_l2_delegation_example_integration.py)
+  - Example of L2 delegation using API calls
+  - Shows how to integrate external API data sources
+  - Demonstrates proper API response handling
+
+## Legacy Integrations (Don't use, just for reference)
+- [PendleLPTIntegration](integrations/pendle_lpt_integration.py): (Legacy Example) A basic integration showing Pendle LPT staking tracking. Note: This is a 
+non-cached implementation included only for reference - new integrations should use the cached approach for better efficiency.
+- [PendleYTIntegration](integrations/pendle_yt_integration.py): (Legacy Example) A basic integration showing Pendle YT staking tracking. Note: This is a non-cached 
+implementation included only for reference - new integrations should use the cached approach for better efficiency.

campaign/campaign.py

@@ -2,11 +2,19 @@
 from constants.example_integrations import (
     ACTIVE_ENA_START_BLOCK_EXAMPLE,
     BEEFY_ARBITRUM_START_BLOCK_EXAMPLE,
+    KAMINO_SUSDE_COLLATERAL_START_BLOCK_EXAMPLE,
+    RATEX_EXAMPLE_USDE_START_BLOCK,
 )
 from integrations.beefy_cached_balance_example_integration import (
     BeefyCachedBalanceIntegration,
 )
 from integrations.claimed_ena_example_integration import ClaimedEnaIntegration
+from integrations.kamino_l2_delegation_example_integration import (
+    KaminoL2DelegationExampleIntegration,
+)
+from integrations.ratex_l2_delegation_example_integration import (
+    RatexL2DelegationExampleIntegration,
+)
 from utils import pendle
 from web3 import Web3
 
@@ -49,6 +57,26 @@
         chain=Chain.ARBITRUM,
         reward_multiplier=1,
     ),
+    # L2 Delegation example for non EVM chains, based on ts script
+    KaminoL2DelegationExampleIntegration(
+        integration_id=IntegrationID.KAMINO_SUSDE_COLLATERAL_EXAMPLE,
+        start_block=KAMINO_SUSDE_COLLATERAL_START_BLOCK_EXAMPLE,
+        market_address="BJnbcRHqvppTyGesLzWASGKnmnF1wq9jZu6ExrjT7wvF",
+        token_address="EwBTjwCXJ3TsKP8dNTYnzRmBWRd6h48FdLFSAGJ3sCtx",
+        decimals=9,
+        chain=Chain.SOLANA,
+        reward_multiplier=1,
+    ),
+    # L2 Delegation example for non EVM chains, based on API calls
+    RatexL2DelegationExampleIntegration(
+        integration_id=IntegrationID.RATEX_USDE_EXAMPLE,
+        start_block=RATEX_EXAMPLE_USDE_START_BLOCK,
+        summary_cols=[
+            SummaryColumn.RATEX_EXAMPLE_PTS,
+        ],
+        chain=Chain.SOLANA,
+        reward_multiplier=1,
+    ),
     # Simple Integration class examples (outdated),
     # don't use these anymore
     PendleLPTIntegration(

constants/chains.py

@@ -10,5 +10,6 @@ class Chain(Enum):
     SCROLL = "Scroll"
     MODE = "Mode"
     OPTIMISM = "Optimism"
-    Lyra = "Lyra"
+    LYRA = "Lyra"
     SWELL = "Swell"
+    SOLANA = "Solana"

constants/example_integrations.py

@@ -14,3 +14,7 @@
 )
 
 BEEFY_ARBITRUM_START_BLOCK_EXAMPLE = 219870802
+
+KAMINO_SUSDE_COLLATERAL_START_BLOCK_EXAMPLE = 20471904
+
+RATEX_EXAMPLE_USDE_START_BLOCK = 21202656

constants/summary_columns.py

@@ -39,9 +39,16 @@ class SummaryColumn(Enum):
         "beefy_cached_balance_example",
         SummaryColumnType.ETHENA_PTS,
     )
-    
+
     TEMPEST_SWELL_SHARDS = ("tempest_swell_shards", SummaryColumnType.ETHENA_PTS)
 
+    KAMINO_DELEGATED_PTS_EXAMPLE = (
+        "kamino_delegated_pts_example",
+        SummaryColumnType.ETHENA_PTS,
+    )
+
+    RATEX_EXAMPLE_PTS = ("ratex_example_pts", SummaryColumnType.ETHENA_PTS)
+
     def __init__(self, column_name: str, col_type: SummaryColumnType):
         self.column_name = column_name
         self.col_type = col_type

integrations/integration.py

@@ -39,15 +39,20 @@ def __init__(
     def get_balance(self, user: str, block: int) -> float:
         raise NotImplementedError
 
-    # either get_participants OR get_block_balances must be implemented
     def get_participants(
         self,
         blocks: Optional[List[int]],
     ) -> Set[str]:
         raise NotImplementedError
 
-    # either get_participants OR get_block_balances must be implemented
     def get_block_balances(
         self, cached_data: Dict[int, Dict[ChecksumAddress, float]], blocks: List[int]
     ) -> Dict[int, Dict[ChecksumAddress, float]]:
         raise NotImplementedError
+
+    def get_l2_block_balances(
+        self,
+        cached_data: Dict[int, Dict[str, float]],
+        blocks: List[int],
+    ) -> Dict[int, Dict[str, float]]:
+        raise NotImplementedError

integrations/integration_ids.py

@@ -394,10 +394,18 @@ class IntegrationID(Enum):
         "Beefy Cached Balance Example",
         Token.USDE,
     )
+
+    KAMINO_SUSDE_COLLATERAL_EXAMPLE = (
+        "kamino_susde_collateral_example",
+        "Kamino sUSDe Collateral Example",
+        Token.SUSDE,
+    )
+
+    RATEX_USDE_EXAMPLE = ("ratex_usde_example", "Ratex USDe Example", Token.USDE)
+
     # Upshift sUSDe
     UPSHIFT_UPSUSDE = ("upshift_upsusde", "Upshift upsUSDe", Token.SUSDE)
 
-
     # Tempest Finance
     TEMPEST_SWELL_USDE = (
         "tempest_swell_usde_held",
@@ -412,7 +420,6 @@ class IntegrationID(Enum):
         Token.USDE,
     )
 
-
     def __init__(self, column_name: str, description: str, token: Token = Token.USDE):
         self.column_name = column_name
         self.description = description

integrations/kamino_l2_delegation_example_integration.py

@@ -0,0 +1,113 @@
+import logging
+import os
+import subprocess
+import json
+import time
+
+from typing import Dict, List
+from dotenv import load_dotenv
+from constants.summary_columns import SummaryColumn
+from constants.example_integrations import (
+    KAMINO_SUSDE_COLLATERAL_START_BLOCK_EXAMPLE,
+)
+from constants.chains import Chain
+from integrations.integration_ids import IntegrationID as IntID
+from integrations.l2_delegation_integration import L2DelegationIntegration
+
+load_dotenv()
+
+
+class KaminoL2DelegationExampleIntegration(L2DelegationIntegration):
+    def __init__(
+        self,
+        integration_id: IntID,
+        start_block: int,
+        token_address: str,
+        market_address: str,
+        decimals: int,
+        chain: Chain = Chain.SOLANA,
+        reward_multiplier: int = 1,
+    ):
+
+        super().__init__(
+            integration_id=integration_id,
+            start_block=start_block,
+            chain=chain,
+            summary_cols=[SummaryColumn.KAMINO_DELEGATED_PTS_EXAMPLE],
+            reward_multiplier=reward_multiplier,
+        )
+        self.token_address = token_address
+        self.market_address = market_address
+        self.decimals = str(decimals)
+        self.kamino_ts_location = "ts/kamino_collat.ts"
+
+    def get_l2_block_balances(
+        self, cached_data: Dict[int, Dict[str, float]], blocks: List[int]
+    ) -> Dict[int, Dict[str, float]]:
+        logging.info("Getting block data for Kamino l2 delegation example...")
+        block_data: Dict[int, Dict[str, float]] = {}
+        for block in blocks:
+            block_data[block] = self.get_participants_data(block)
+        return block_data
+
+    def get_participants_data(self, block: int) -> Dict[str, float]:
+        logging.info(
+            f"Getting participants data for Kamino l2 delegation example at block {block}..."
+        )
+        max_retries = 3
+        retry_count = 0
+
+        while retry_count < max_retries:
+            try:
+                logging.info(
+                    f"Getting participants data for Kamino l2 delegation example at block {block}... (Attempt {retry_count + 1}/{max_retries})"
+                )
+                response = subprocess.run(
+                    [
+                        "ts-node",
+                        os.path.join(
+                            os.path.dirname(__file__), "..", self.kamino_ts_location
+                        ),
+                        self.market_address,
+                        self.token_address,
+                        self.decimals,
+                    ],
+                    capture_output=True,
+                    text=True,
+                    check=True,
+                    env=os.environ.copy(),
+                )
+                balances = json.loads(response.stdout)
+                return balances
+            except Exception as e:
+                retry_count += 1
+                if retry_count == max_retries:
+                    err_msg = f"Error getting participants data for Kamino l2 delegation example after {max_retries} attempts: {e}"
+                    logging.error(err_msg)
+                    return {}
+                else:
+                    logging.warning(
+                        f"Attempt {retry_count}/{max_retries} failed, retrying..."
+                    )
+                    time.sleep(5)  # Add a small delay between retries
+        return {}
+
+
+if __name__ == "__main__":
+    example_integration = KaminoL2DelegationExampleIntegration(
+        integration_id=IntID.KAMINO_SUSDE_COLLATERAL_EXAMPLE,
+        start_block=KAMINO_SUSDE_COLLATERAL_START_BLOCK_EXAMPLE,
+        market_address="BJnbcRHqvppTyGesLzWASGKnmnF1wq9jZu6ExrjT7wvF",
+        token_address="EwBTjwCXJ3TsKP8dNTYnzRmBWRd6h48FdLFSAGJ3sCtx",
+        decimals=9,
+        chain=Chain.SOLANA,
+        reward_multiplier=5,
+    )
+
+    example_integration_output = example_integration.get_l2_block_balances(
+        cached_data={}, blocks=[21209856, 21217056]
+    )
+
+    print("=" * 120)
+    print("Run without cached data", example_integration_output)
+    print("=" * 120, "\n" * 5)