Skip to content

Commit

Permalink
Merge pull request #52 from ethena-labs/f/pe-87-add-delegated-l2-inte…
Browse files Browse the repository at this point in the history
…gration-examples-to-the-adapters-repo

F/pe 87 add delegated l2 integration examples to the adapters repo
  • Loading branch information
FJ-Riveros authored Dec 27, 2024
2 parents 28d9065 + f92a520 commit 7b5649e
Show file tree
Hide file tree
Showing 20 changed files with 3,408 additions and 22 deletions.
1 change: 1 addition & 0 deletions .env.example
Original file line number Diff line number Diff line change
Expand Up @@ -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=''
1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -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
70 changes: 59 additions & 11 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
28 changes: 28 additions & 0 deletions campaign/campaign.py
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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(
Expand Down
3 changes: 2 additions & 1 deletion constants/chains.py
Original file line number Diff line number Diff line change
Expand Up @@ -10,5 +10,6 @@ class Chain(Enum):
SCROLL = "Scroll"
MODE = "Mode"
OPTIMISM = "Optimism"
Lyra = "Lyra"
LYRA = "Lyra"
SWELL = "Swell"
SOLANA = "Solana"
4 changes: 4 additions & 0 deletions constants/example_integrations.py
Original file line number Diff line number Diff line change
Expand Up @@ -14,3 +14,7 @@
)

BEEFY_ARBITRUM_START_BLOCK_EXAMPLE = 219870802

KAMINO_SUSDE_COLLATERAL_START_BLOCK_EXAMPLE = 20471904

RATEX_EXAMPLE_USDE_START_BLOCK = 21202656
9 changes: 8 additions & 1 deletion constants/summary_columns.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
9 changes: 7 additions & 2 deletions integrations/integration.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
11 changes: 9 additions & 2 deletions integrations/integration_ids.py
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand All @@ -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
Expand Down
113 changes: 113 additions & 0 deletions integrations/kamino_l2_delegation_example_integration.py
Original file line number Diff line number Diff line change
@@ -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)
52 changes: 52 additions & 0 deletions integrations/l2_delegation_integration.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,52 @@
from typing import Callable, Dict, List, Optional, Set
from eth_typing import ChecksumAddress

from constants.summary_columns import SummaryColumn
from constants.chains import Chain
from integrations.cached_balances_integration import CachedBalancesIntegration
from integrations.integration_ids import IntegrationID as IntID


"""
This class serves as an example implementation for L2 delegation integration.
The methods defined here are used in our backend to handle layer 2 delegation data.
Actual implementation details have been removed for security purposes.
"""


class L2DelegationIntegration(CachedBalancesIntegration):
def __init__(
self,
integration_id: IntID,
start_block: int,
chain: Chain = Chain.SOLANA,
summary_cols: Optional[List[SummaryColumn]] = None,
reward_multiplier: int = 20,
balance_multiplier: int = 1,
excluded_addresses: Optional[Set[ChecksumAddress]] = None,
end_block: Optional[int] = None,
ethereal_multiplier: int = 0,
ethereal_multiplier_func: Optional[Callable[[int, str], int]] = None,
):
super().__init__(
integration_id=integration_id,
start_block=start_block,
chain=chain,
summary_cols=summary_cols,
reward_multiplier=reward_multiplier,
balance_multiplier=balance_multiplier,
excluded_addresses=excluded_addresses,
end_block=end_block,
ethereal_multiplier=ethereal_multiplier,
ethereal_multiplier_func=ethereal_multiplier_func,
)

def get_l2_block_balances(
self,
cached_data: Dict[int, Dict[str, float]],
blocks: List[int],
) -> Dict[int, Dict[str, float]]:
raise NotImplementedError

def get_participants_data(self, block: int) -> Dict[str, float]:
raise NotImplementedError
Loading

0 comments on commit 7b5649e

Please sign in to comment.