Merge branch 'main' of https://github.com/ethena-labs/ethena_sats_ada…

…pters

.env.example

@@ -2,3 +2,8 @@ ETH_NODE_URL='https://eth.llamarpc.com'
 MANTLE_NODE_URL='https://rpc.mantle.xyz'
 ARBITRUM_NODE_URL='https://arb1.arbitrum.io/rpc'
 SCROLL_NODE_URL='https://rpc.scroll.io'
+MODE_NODE_URL='https://mainnet.mode.network'
+FRAXTAL_NODE_URL='https://rpc.frax.com'
+LYRA_NODE_URL='https://rpc.derive.xyz'
+
+DERIVE_SUBGRAPH_API_KEY=''

.github/workflows/main-push-and-pr.yml

@@ -0,0 +1,42 @@
+# This workflow will install Python dependencies, run tests and lint with a single version of Python
+# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python
+
+name: Python application
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+    branches: ["main"]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python 3.10
+        uses: actions/setup-python@v3
+        with:
+          python-version: "3.10"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install flake8 mypy
+          if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
+          if [ -f requirements-dev.txt ]; then pip install -r requirements-dev.txt; fi
+
+      - name: Lint with flake8
+        run: |
+          # stop the build if there are Python syntax errors or undefined names
+          flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics
+          # exit-zero treats all errors as warnings. The GitHub editor is 127 chars wide
+          flake8 . --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics
+
+      - name: Type check with mypy
+        run: mypy . --explicit-package-bases --pretty --check-untyped-defs

.gitignore

@@ -61,6 +61,9 @@ local_settings.py
 db.sqlite3
 db.sqlite3-journal
 
+# VSCode
+.vscode/
+
 # Flask stuff:
 instance/
 .webassets-cache

README.md

@@ -1,24 +1,30 @@
 # Overview
 
-This repo offers a self service approach to Ethena Sats Campaign integrations.
+This repo offers a self service approach to Ethena Points Campaign integrations.
 
 # Instructions
 
-For your protocol to be included and your users to receive sats, you should submit a PR to this repo. Here some guidelines to follow:
+For your protocol to be included and your users to receive points, you should submit a PR to this repo. Here some guidelines to follow:
 
 1. Make a copy of `.env.example` and name it `.env`.
 2. Run `pip install -r requirements.txt` to install the required packages.
-3. Add your integration metadata to `constants/integration_ids.py`.
-4. Make a copy of `integrations/template.py`, naming the file `[protocol name].py` and place in the `integrations` directory.
-5. Your integration must be a class that inherits from `Integration` and implements the `get_balance` and `get_participants` methods.
-6. The `get_balance` method should return the balance of a given user at a given block.
-7. The `get_participants` method should return a list of all users that have interacted with the protocol.
+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.
 
 # 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_balance` and `get_participants` methods should be as efficient as possible.
-- We prefer that on chain RPC calls are used to get information as much as possible due to reliability and trustlessness. For example one could cycle through events for `get_participants` and read from a smart contract for `get_balance`. 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 sats.
+- 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.