First Full Epoch - Rerun for missing ETHx

.github/workflows/run_payment_round.yaml

@@ -21,7 +21,7 @@ jobs:
     - name: Setup Python 3.9
       uses: actions/setup-python@v2
       with:
-        python-version: 3.9
+        python-version: "3.10"
 
     - name: Generate Payload and report
       env:

README.md

@@ -1,20 +1,23 @@
-## Arbitrum Aidrop distribution program
+## Arbitrum Grants Distributor  - STIP-Bridge
+Distribution program pays out 50,000 ARB per week for 12 weeks based on veBAL voting for whitelisted pools on Arbitrum.
 
-Distribution program pays out 100k ARB per week based on veBAL voting for pools on Arbitrum.
+Pools are capped at 20% of the total weekly $ARB by default.
 
-Some pools have a boost factor, then ARB is distributed to all pools based on their relative boosted weight.
+$ARB to a pool is boosted by a dynamic boost (described below based on fees vs emissions), and a fixed boost that can be assigned by Balancer BD to support special initiatives.
 
-Pools are capped at 10% of the total weekly $ARB, except for ETH based LSD stableswap pools which are capped at 20%
+The pools participating in the program, as well as configuration around overriding caps and fixed boost can be found [here](https://github.com/BalancerMaxis/arbitrum_grants_distributor/blob/main/automation/arbitrum_stip_bridge_start_q2_2024.py#L29).
 
-Boosts and caps are defined per gauge in [arbitrumGrantGaugeMetadata.json](https://github.com/BalancerMaxis/data_automation/blob/main/data/arbitrumGrantGuageMetadata.json)
+Pools which are at least 50% interest bearing or deemed as strategic liquidity are eligible for whitelist addition.
+
+Balancer’s STIP.B application can be found [here[(https://forum.arbitrum.foundation/t/final-balancer-stip-addendum/23288).
 
 ---
 
 ## Configuration and Data
-- [Emissions per year config](https://github.com/BalancerMaxis/STIP_automation/blob/main/automation/emissions_per_year.py)
-- [Static Boost Info](https://github.com/BalancerMaxis/STIP_automation/blob/main/automation/static_boosts.py)
-- [ARB amounts emitted](https://github.com/BalancerMaxis/STIP_automation/blob/main/automation/constants.py#L58)
-- [Output Data](https://github.com/BalancerMaxis/STIP_automation/tree/main/output) is collected in output/ directory
+- [ARB amounts emitted](https://github.com/BalancerMaxis/arbitrum_grants_distributor/blob/main/automation/constants.py#L12)
+- [Pool Whitelist and Modifiers](https://github.com/BalancerMaxis/arbitrum_grants_distributor/blob/main/automation/arbitrum_stip_bridge_start_q2_2024.py)
+- [Output Data](https://github.com/BalancerMaxis/arbitrum_grants_distributor/tree/main/output) is collected in output/ directory
+- [BAL Emissions per Year](https://github.com/BalancerMaxis/arbitrum_grants_distributor/blob/main/automation/emissions_per_year.py)
 
 ---
 
@@ -26,38 +29,73 @@ Boost is based on 2 factors.
 2. A variable boost based on the efficiency of the pool (fees/emissions)
 
 ### Fixed boost
-By default, all pools have a fixed boost of 1.  The following table describes situations that receive a higher fixed boost:
+By default, all whitelisted pools have a fixed boost of 1.  Here are some examples of situations where fixed boost might be assigned and what it could be:
+
+| Desired Outcome/Activity                               | Fixed Boost |
+|--------------------------------------------------------|-------------|
+| 100% Intrest Bearing                                   | 1.5x        |
+| IB token Mintable on Arbitrum                          | 1.75x       |
+| Short term boost for a shared/major marketing campaign | 2x          |
 
-| Desired Outcome/Activity | Fixed Boost |
-|--------------------------|-------------|
-| Ecosystem Integration    | 1.5x        |
-| Core Infrastructure      | 1.75x       |
-| New and Novel AMM tech   | 2x          |
+Note that these values are not meant to be cumulative.  The highest one to apply would be used. 
 
-#### Ecosystem Integrations (1.5x)
-- Core pools that receive bribes from fees based on governance and with at least 1 million dollars in TVL.
-- Yield splitting protocols (such as Pendle) will have extra ARB allocated to the supported pools that have TVL >$1m
-- Concentrated liquidity pool types by Gyroscope 
-- FXPool https://docs.xave.co/product-overview-1/amm Pools meant to facilitate low slippage trades for assets the trade at a known exchange rate
-- Balancer LP Tokens (BPT) with significant TVL as collateral on lending markets 
+#### 100% Intrest Bearing    
+- 100% of the liqudity in this pool is interest bearing
+  - Get this by pairing your Intrest Bearing Token with other yield bearing tokens such as wstETH, sDAI, or sFRAX, etc. 
+  - Does not apply to weighted pools.  Intended for CL based approaches such as Stableswaps and Gyro. 
 
-#### Core Infra (1.75x)
-- LSTs
-- 80/20 based governance/incentive systems.
+#### IB Token Mintable on Arbitrum
+- To encourage a more native yield environment on Arbitrum, we are open to considering and granting boost to projects that enable native minting/burning of their yield bearing asset on Arbi.  
+  - In general, we would expect these pools to have at least 50% of the tokens in the pool mintable on Arbitrum.
+
+#### Short term boost for a shared/major marketing campaign
+- Sometimes the best way to grow a pool is fast, with lots of incentives and marketing push.
+  - In cases where it's all coming together like that, and we have a partner looking to also hit it hard, we may consider a short term but high boost or some fixed incentives to help kick things off.
 
-#### New and Novel AMM tech (2x)
-This is to help get attention to new Custom Pool types that have just launched.  
-Pools in this section may move to the "Integrations" category after some time.
 
 ### Variable Fee Based Boost (1-3x)
 The variable boost is determined by using the following formula:
 
-Variable Boost = ** (Fees Earned * 3) / (USD Value of BAL emitted + 1)**
+`Variable Boost = min(Fees Earned / (USD Value of BAL emitted + 1), 3)`
 
 The variable boosted is capped at 3 and has a minimum of 1.
 
 The fee based boost is added to the fixed boost, so:
 
-Total Boost = **_Fixed Boost + Variable Boost - 1_** 
+### Calculating the final boost
+Total Boost = Fixed Boost + Variable Boost - 1
+
+where both boosts will always be >=1.  The final boost will be automatically computed by the distribution process and applied.
+
+## Fixed Incentives
+While everything above describes the system whereby $ARB follows voting, the Council also has the ability to assign fixed incentives to pools. Fixed incentives involve allocating an exact amount of $ARB per week to a gauge, regardless of veBAL voting. 
+they are included in cap calculations, but not considered when allocating the rest of the $ARB which follows voting.  Fixed incentives are cumulative on top of standard, vote following incentives.  
+
+The budget for weekly fixed incentives is taken from the total available incentives per week.
+
+This capability should be used sparingly, and primarily to direct incentives towards more quickly bootstrapping pools that have been added to the program but have not yet received votes due to process constraints around adding gauges to veBAL.
+
+
+## Advice for DAOs that have their own $ARB from grants to distribute to Balancer pools
+
+Balancer will be distributing $ARB via direct payments on the Balancer Gauge.  In order to keep accounting clear, and based on the way the gauge functions, it would be quite difficult to add other streams of STIP to this process.  As a result, we recommend the following 2 methods for distributing $ARB to Balancer pools during STIP.
+
+- You can place a vote incentive on one of the Arbitrum Incentive markets: [HiddenHand](https://hiddenhand.finance/aura), [Paladin](https://quest.paladin.vote/#/create), [Vote Market](https://votemarket.stakedao.org/?market=bal).  
+  - This will trigger voting, which will trigger BAL and AURA emissions as well as create more signaling for $ARB flows from this program.
+
+- You can pay direct incentives into Aura, which will stream with no fees taken to depositors.
+  - To do so go to your pool on Aura, go to info, go to dev-mode, scroll down and you’ll see a tab to schedule extra incentive flows to depositors. 
+  - For example going to https://app.aura.finance/#/42161/pool/50 
+
+<img src="images/aura_direct_deposit_flow.png" width=500>
+
+_Pass ARB for the token, 0x912ce59144191c1204e64559fe8253a0e49e6548, follow the workflow to schedule how much for how long_ 
+
+
+**Get in contact with Aura or Balancer BD or the Balancer Maxis (can find us on discord) if you need help figuring this out.**
+
+## Example outputs
+
+The CSV [here](output/arbitrum_stip_bridge_start_q2_2024_2024-05-17_2024-05-31.csv) shows the output of the model for the pools on Arbitrum using past data. The amounts distributed are for a 2 week epoch.  The outputs are based on the current core pools list, and the parameters defined above.  The whitelist, and parameters above are subject to change.
 
-where both boosts are >=1 it will be automatically computed by the model and applied. 
+![img.png](images/exampleOutputsImage.png)

automation/arbitrum_stip_bridge_start_q2_2024.py

@@ -0,0 +1,174 @@
+from web3 import Web3
+from automation.constants import (
+    FIXED_INCENTIVE_TOKENS_PER_EPOCH,
+    DESIRED_DEFAULT_VOTE_CAP,
+    DEFAULT_PCT_TO_AURA,
+)
+
+#####
+# Notes for the maintainers of this config file
+#####
+# Default cap was set to 10% when this comment was written, will be used if not overridden. (see constants.py)
+# Default fixedBoost is 1 if not specified
+# Default pctToAura is 0 if not specified
+# Default fixexEmissions is 0 if not specified
+# All fixedEmissions should equal up to under constants.py/FIXED_INCENTIVE_TOKENS_PER_EPOCH
+
+# meta information is not required to run, and you can put whatever you want there in json format as notes.
+# gauge
+
+# {
+#         "pool_id": "0x5f8893506ddc4c271837187d14a9c87964a074dc000000000000000000000106",
+#         "meta": {"symbol": "eth-trip", "boostReason": "100% LST"},
+#         "fixedBoost": 1.5,
+#         "capOverride": 20,
+#         "fixedEmissions": 3_000,
+#         "percent_to_aura": 0, #set to 0.5 to send 50% to aura direct
+#     },
+
+#  THIS CONFIG IS FOR ARBITRUM CHAIN - includes all current core pools with no modifiers
+ACTIVE_POOLS_AND_OVERRIDES = [
+    ## for each pool in core_pools_arbi, add a dict with pool_id and symbol/meta
+    ## like the example above
+    ## {
+    ##     "pool_id": "0x125bc5a031b2db6733bfa35d914ffa428095978b000200000000000000000514",
+    ##     "meta": {"symbol": "ECLP-AUSDC-AUSDT"},
+    ## },
+    ## {
+    {
+        "pool_id": "0x90e6cb5249f5e1572afbf8a96d8a1ca6acffd73900000000000000000000055c",
+        "meta": {"symbol": "rsETH-wETH"},
+        "fixedEmissions": 4000,
+    },
+    {
+        "pool_id": "0xcdcef9765d369954a4a936064535710f7235110a000200000000000000000558",
+        "meta": {"symbol": "weETH-wstETH ECLP"},
+        "fixedBoost": 1.5,
+        "fixedEmissions": 4000,
+    },
+    {
+        "pool_id": "0x7967fa58b9501600d96bd843173b9334983ee6e600020000000000000000056e",
+        "meta": {"symbol": "wstETH-wETH-ECLP"},
+        "fixedBoost": 2,
+        "fixedEmissions": 10000,
+    },
+    {
+        "pool_id": "0x5b89dc91e5a4dc6d4ab0d970af6a7f981971a443000000000000000000000572",
+        "meta": {"symbol": "instETH-wstETH"},
+        "fixedBoost": 1.5,
+        "fixedEmissions": 1000,
+    },
+    {
+        "pool_id": "0xb8cb384e65096386c1edaaf784e842c957fa3645000000000000000000000571",
+        "meta": {"symbol": "inETH-wstETH"},
+        "fixedBoost": 1.5,
+        "fixedEmissions": 1000,
+    },
+    {
+        "pool_id": "0x7b54c44fbe6db6d97fd22b8756f89c0af16202cc00000000000000000000053c",
+        "meta": {"symbol": "ETHx-wstETH-ETH"},
+        "fixedBoost": 1.5,
+    },
+    {
+        "pool_id": "0x7272163a931dac5bbe1cb5fefaf959bb65f7346f000200000000000000000549",
+        "meta": {"symbol": "GYD-AUSDT-ECLP"},
+        "fixedBoost": 1.75,
+    },
+    {
+        "pool_id": "0x6e822c64c00393b2078f2a5bb75c575ab505b55c000200000000000000000548",
+        "meta": {"symbol": "GYD-AUSDC-ECLP"},
+        "fixedBoost": 1.75,
+    },
+    {
+        "pool_id": "0x46472cba35e6800012aa9fcc7939ff07478c473e00020000000000000000056c",
+        "meta": {"symbol": "GHO-AUSDC-ECLP"},
+        "fixedBoost": 1.75,
+    },
+    {
+        "pool_id": "0x125bc5a031b2db6733bfa35d914ffa428095978b000200000000000000000514",
+        "meta": {"symbol": "ECLP-AUSDC-AUSDT"},
+        "fixedBoost": 1.75,
+    },
+    {
+        "pool_id": "0x260dbd54d87a10a0fc9d08622ebc969a3bf4e6bb000200000000000000000536",
+        "meta": {"symbol": "jitoSOL/wstETH"},
+        "fixedBoost": 1.5,
+    },
+    {
+        "pool_id": "0x2ce4457acac29da4736ae6f5cd9f583a6b335c270000000000000000000004dc",
+        "meta": {"symbol": "sFRAX/4POOL"},
+    },
+    {
+        "pool_id": "0x2d6ced12420a9af5a83765a8c48be2afcd1a8feb000000000000000000000500",
+        "meta": {"symbol": "cbETH/rETH/wstETH"},
+        "fixedBoost": 1.5,
+    },
+    {
+        "pool_id": "0x3fd4954a851ead144c2ff72b1f5a38ea5976bd54000000000000000000000480",
+        "meta": {"symbol": "ankrETH/wstETH-BPT"},
+        "fixedBoost": 1.5,
+    },
+    {
+        "pool_id": "0x451b0afd69ace11ec0ac339033d54d2543b088a80000000000000000000004d5",
+        "meta": {"symbol": "plsRDNT-Stable"},
+    },
+    {
+        "pool_id": "0x9791d590788598535278552eecd4b211bfc790cb000000000000000000000498",
+        "meta": {"symbol": "wstETH-WETH-BPT"},
+    },
+    {
+        "pool_id": "0xb61371ab661b1acec81c699854d2f911070c059e000000000000000000000516",
+        "meta": {"symbol": "ezETH/wstETH"},
+        "fixedBoost": 1.5,
+    },
+    {
+        "pool_id": "0xc2598280bfea1fe18dfcabd21c7165c40c6859d30000000000000000000004f3",
+        "meta": {"symbol": "wstETH/sfrxETH"},
+        "fixedBoost": 1.5,
+    },
+    {
+        "pool_id": "0xd0ec47c54ca5e20aaae4616c25c825c7f48d40690000000000000000000004ef",
+        "meta": {"symbol": "rETH/wETH BPT"},
+    },
+    {
+        "pool_id": "0xef0c116a2818a5b1a5d836a291856a321f43c2fb00020000000000000000053a",
+        "meta": {"symbol": "ECLP-WOETH-WETH"},
+    },
+    {
+        "pool_id": "0x9f8ed1acfe0c863381b9081aff2144fc867aa7730002000000000000000004d4",
+        "meta": {"symbol": "ANKR:ankrETH"},
+    },
+]
+
+
+# assert that the total sum of all fixedEmissions is equal to FIXED_INCENTIVE_TOKENS_PER_EPOCH
+total_fixed_emissions = sum(
+    [x.get("fixedEmissions", 0) for x in ACTIVE_POOLS_AND_OVERRIDES]
+)
+assert (
+    total_fixed_emissions == FIXED_INCENTIVE_TOKENS_PER_EPOCH
+), f"Sum of fixed emissions configured:{total_fixed_emissions} does not equal FIXED_INCENTIVE_TOKENS_PER_EPOCH:{FIXED_INCENTIVE_TOKENS_PER_EPOCH} configured in constants.py"
+
+# Load static boost data
+boost_data = {}
+cap_override_data = {}
+fixed_emissions_per_pool = {}
+percent_to_aura = {}
+# Load static boost here
+for pooldata in ACTIVE_POOLS_AND_OVERRIDES:
+    pool_id_lower = pooldata.get("pool_id")
+    if pool_id_lower:
+        pool_id_lower = pool_id_lower.lower()
+    else:
+        print(
+            f"WARNING: Skipping pool_id {pool_id_lower} because it is not found in {pooldata}"
+        )
+        continue
+    percent_to_aura[pool_id_lower] = pooldata.get(
+        "percent_to_aura", DEFAULT_PCT_TO_AURA
+    )
+    boost_data[pool_id_lower] = pooldata.get("fixedBoost", 1)
+    cap_override_data[pool_id_lower] = pooldata.get(
+        "capOverride", DESIRED_DEFAULT_VOTE_CAP
+    )
+    fixed_emissions_per_pool[pool_id_lower] = pooldata.get("fixedEmissions", 0)

automation/constants.py

@@ -0,0 +1,64 @@
+from web3 import Web3
+
+# There should be a pool_config file named $FILE_PREFIX.py in the automation directory that holds the running pool config
+# Outputs will also use this prefix
+FILE_PREFIX = "arbitrum_stip_bridge_start_q2_2024"
+
+CHAIN_NAME = "arbitrum"
+CURRENT_YEAR = 2024
+# How many incentives should be taken away from vote following to be distributed as fixed incentives?  Per 2 week epoch
+FIXED_INCENTIVE_TOKENS_PER_EPOCH = 20_000  ## Max 10k per 2 weeks or 20k per epoch
+# Total number of tokens available per 2 week epoch
+## TODO remove -12_000 this is order to manually handle fixed incentives on gauges not yet added to voting as part of getting STIP running.
+TOTAL_TOKENS_PER_EPOCH = (600_000 / (12 / 2)) - 12_000  # 100k per epoch, 50k per week
+DYNAMIC_BOOST_CAP = 3
+MIN_BAL_IN_USD_FOR_BOOST = 200
+TOKENS_TO_FOLLOW_VOTING = TOTAL_TOKENS_PER_EPOCH - FIXED_INCENTIVE_TOKENS_PER_EPOCH
+DESIRED_DEFAULT_VOTE_CAP = 20
+DEFAULT_PCT_TO_AURA = (
+    0  # Insufficent support from Aura team to execute a split well for this grant
+)
+BALANCER_GAUGE_CONTROLLER_ABI = [
+    {
+        "stateMutability": "view",
+        "type": "function",
+        "name": "gauge_relative_weight",
+        "inputs": [{"name": "addr", "type": "address"}],
+        "outputs": [{"name": "", "type": "uint256"}],
+    },
+    {
+        "stateMutability": "view",
+        "type": "function",
+        "name": "gauge_relative_weight",
+        "inputs": [
+            {"name": "addr", "type": "address"},
+            {"name": "time", "type": "uint256"},
+        ],
+        "outputs": [{"name": "", "type": "uint256"}],
+    },
+]
+
+# TODO at some point snapshot queries should be moved to bal_tools  also lstGrant.py to think about.
+# Query to fetch pool snapshots
+POOLS_SNAPSHOTS_QUERY = """
+{{
+  poolSnapshots(
+    first: {first}
+    skip: {skip}
+    orderBy: timestamp
+    orderDirection: desc
+    where: {{timestamp_gte: {start_ts}, timestamp_lt: {end_ts}}}
+  ) {{
+    pool {{
+      address
+      id
+      symbol
+    }}
+    timestamp
+    protocolFee
+    swapFees
+    swapVolume
+    liquidity
+  }}
+}}
+"""