First pass on veocean and farming docs.

SUMMARY.md

@@ -52,7 +52,14 @@
   * [Contributing](core-concepts/contributing.md)
     * [Contributor Code of Conduct](core-concepts/code-of-conduct.md)
     * [Legal Requirements](core-concepts/legal-reqs.md)
-  * [Partners & Collaborators](building-with-ocean/projects-using-ocean.md)
+  * [Projects using Ocean Protocol](building-with-ocean/projects-using-ocean.md)
+* [veOCEAN](veOcean/veOcean.md)
+  * [veOCEAN](veOcean/veOcean.md)
+  * [Data Farming Intro](veOcean/data-farming-intro.md)
+  * [Data Farming Advanced](veOcean/data-farming.md)
+  * [Emissions & APYs](veOcean/emissions-apys.md)
+  * [Contracts & Formuls](veOcean/definitions.md)
+  * [FAQ](veOcean/faq.md)
 * [Rewards](rewards/veOcean-Data-Farming-Tutorial.md)
 * [API References](api-references/README.md)
   * [Aquarius REST API](api-references/aquarius-rest-api.md)

veOcean/contracts-formulas.md

@@ -0,0 +1,28 @@
+## Contract Deployments
+
+The [veOCEAN & DF contracts](https://github.com/oceanprotocol/contracts/tree/main/contracts/ve) are deployed to Ethereum mainnet, alongside other Ocean contract deployments. [Full list](https://github.com/oceanprotocol/contracts/blob/main/addresses/address.json).
+
+```
+{
+ “veOCEAN”: “0xE86Bf3B0D3a20444DE7c78932ACe6e5EfFE92379”,
+ “veAllocate”: “0x55567E038b0a50283084ae773FA433a5029822d3”,
+ “veDelegation”: “0xc768eDF2d21fe00ef5804A7Caa775E877e65A70E”,
+ “veFeeDistributor”: “0x256c54219816603BB8327F9019533B020a76e936”,
+ “veDelegationProxy”: “0x45E3BEc7D139Cd8Ed7FeB161F3B094688ddB0c20”,
+ “veFeeEstimate”: “0xe97a787420eD263583689Bd35B7Db1952A94710d”,
+ “SmartWalletChecker”: “0xd7ddf62257A41cc6cdAd7A3d36e4f1d925fD142a”,
+ “DFRewards”: “0xFe27534EA0c016634b2DaA97Ae3eF43fEe71EEB0”,
+ “DFStrategyV1”: “0x545138e8D76C304C916B1261B3f6c446fe4f63e3”,
+}
+```
+
+veFeeDistributor has a start_time of 1663804800 (Thu Sep 22 2022 00:00:00)
+
+## Formulas
+
+### veOcean
+
+**veOCEAN Liner Decay**  
+```
+veOcean_balance = OCEAN_amount_locked * (your_unlock_timestamp — current_unix_timestamp ) / 60 * 60 * 24 * 7 * 52 (that is 4 years)
+```

veOcean/data-farming-intro.md

@@ -0,0 +1,56 @@
+# Rewards
+
+Data Farming (DF) incentivizes for growth of Data Consume Volume (DCV) in the Ocean ecosystem.
+
+It rewards OCEAN to pool liquidity providers (stakers) as a function of consume volume and liquidity. It’s like DeFi liquidity mining, but tuned for data consumption. DF’s aim is to achieve a minimum supply of data for network effects to kick in, and once the network flywheel is spinning, to increase growth rate.
+
+## Reward Categories
+Rewards are paid in OCEAN and distributed every week on Thursday as follow:  
+**Passive Rewards** : 50% Emissions Reserved  
+**Active Rewards**: 50% Emissions Reserved. Defined by the **Reward Function**.
+
+You can claim rewards from [within our webapp](https://df.oceandao.org/rewards).
+
+**Final Caveat:** We reserve the right to make reasonable changes to these plans, if unforeseen circumstances emerge.
+
+## Reward Function
+
+The Reward Function (RF) governs how active rewards are allocated to stakers.
+
+Rewards are calculated as follows:
+
+First, distribute OCEAN across each asset based on rank: highest-DCV asset gets most OCEAN, etc.
+Then, for each asset and each veOCEAN holder:
+– If the holder is a publisher, 2x the effective stake
+– Baseline rewards = (% stake in asset) * (OCEAN for asset)
+– Bound rewards to the asset by 125% APY
+– Bound rewards by asset’s DCV * 0.1%. This prevents wash consume.
+
+Here is the code from [calcrewards.py](https://github.com/oceanprotocol/df-py/blob/main/util/calcrewards.py) in the Ocean Protocol [df-py repo](https://github.com/oceanprotocol/df-py/)
+
+## 3 Phases of Data Farming
+
+**DF Alpha** - Counting starts Thu June 16. 10K OCEAN rewards are budgeted per week. Rewards are distributed at the end of every week, for the activity of the previous week. It runs 4 weeks. The aim is to test technology, learn, and onboard data publishers.
+
+**DF Beta** - Counting starts Thu July 14. Rewards are up to 100K OCEAN per week. It runs up to 20 weeks. The aim is to test the effect of larger incentives, learn, and refine the technology.
+
+**DF Main** - Immediately follows DF Beta. Rewards are up to 718K OCEAN per week. DF Main emits 503.4M OCEAN worth of rewards and lasts for decades. Expected APY is 125% over many months (once fully ramped), staying generous over the long term.
+
+The amount of OCEAN released is determined by the emission schedule as defined in the [DF Main Blog Post](https://blog.oceanprotocol.com/ocean-data-farming-main-is-here-49c99602419e).
+
+## DF Main
+
+DF Main starts Mar 16, 2023 in DF Round 29. DF29 has 150K OCEAN rewards available (a 2x increase from DF28). As DF Main progresses, rewards will increase to 300K (another 2x), then 600K (another 2x), then beyond 1.1M OCEAN/week (near 2x) then decaying over time.
+
+As of DF29, wash consuming will no longer be profitable. So, organically-generated Data Consume Volume will be the main driver of active DF rewards.
+
+Typical APYs are 5–20%.
+
+Full implementation of DF Main will be over many months, after which DF will be decentralized. DF Main lasts for decades.
+
+## Reward Schedule
+
+The table below cross-references DF Round Number, Start Date, Phase & Week, Sub-Phase & Week, and OCEAN Rewards/Week.
+
+![](./images/reward_schedule.png)
+_Ocean Reward Schedule for the next 20+ years_

veOcean/data-farming.md

@@ -0,0 +1,35 @@
+
+## On Claiming DF Rewards
+
+How to claim? Go to the DF Webapp at [df.oceandao.org/activerewards](df.oceandao.org/activerewards)
+
+”Rewards” page at Data Farming webapp
+Where to claim? All earnings for veOCEAN holders are claimable in Ethereum mainnet. Though, data assets for DF may published in any [network where Ocean’s deployed in production](https://docs.oceanprotocol.com/core-concepts/networks): Eth mainnet, Polygon, etc.
+
+When to claim? There are fresh rewards available every Thursday. If you wish, you can wait for many weeks to accumulate before claiming. (It’s all on-chain.)
+
+When to do a first claim? From the time you lock OCEAN, you must wait at least a week, and up to two weeks, to be able to claim rewards. The nerdy version: if you lock OCEAN on day x, you’ll be able to claim rewards on the first weekly ve “epoch” that begins after day x+7. This behavior is inherited from [veCRV](https://curve.readthedocs.io/dao-fees.html); [here’s the code](https://github.com/oceanprotocol/contracts/blob/main/contracts/ve/veFeeDistributor.vy#L240-L256).
+
+
+## Data Assets that Qualify for DF
+
+Data assets that have veOCEAN allocated towards them get DF rewards.
+
+The data asset may be of any type — dataset (for static URIs) or algorithm for Compute-to-Data. The data asset may be fixed price or free price. If fixed price, any token of exchange is alright (OCEAN, H2O, USDC, ..).
+
+To qualify for DF, a data asset must also:
+
+Have been created by Ocean smart contracts, [deployed](https://github.com/oceanprotocol/contracts/blob/v4main/addresses/address.json) by OPF to [production networks](https://docs.oceanprotocol.com/core-concepts/networks)
+Be visible on [Ocean Market](https://market.oceanprotocol.com/)
+Can’t be in [purgatory](https://github.com/oceanprotocol/list-purgatory/blob/main/policies/README.md)
+
+## Active Work to Drive APY
+
+Data Farming is not a wholly passive activity. The name of the game is to drive data consume volume (DCV). High APYs happen only when there is sufficiently high DCV. High DCV means publishing and consuming truly useful datasets (or algorithms).
+
+Thus, if you really want to max out your APY:
+- create & publish datasets (and make $ in selling them) — or work with people who can
+- consume the datasets (to make $) — or work with people who can
+- go stake on them, and finally claim the rewards.
+
+Driving DCV for publishing & consuming is your challenge. It will take real work. And then the reward is APY. It’s incentives all the way down:)

veOcean/emissions-apys.md

@@ -0,0 +1,48 @@
+# Emissions & APYs
+
+The baseline emissions schedule determines the weekly OCEAN budget for this phase. The schedule is like Bitcoin, including a half-life of 4 years. Unlike Bitcoin, there is a burn-in period to ratchet up value-at-risk versus time:
+- The curve initially gets a multiplier of 10% for 12 months (DF Main 1)
+- Then, it transitions to multiplier of 25% for 6 months (DF Main 2)
+- Then, a multiplier of 50% for 6 months (DF Main 3)
+- Finally, a multiplier of 100%. (DF Main 4)
+
+We implement the first three phases as constants, because they are relatively short in duration. We implement the fourth phase as a Bitcoin-style exponential: constant, with the constant dividing by two (“halvening”) every four years.
+
+Let’s visualize!
+
+## Emissions — first 5 years.
+
+The image below shows the first 5 years. The y-axis is OCEAN released each week. It’s log-scaled to easily see the differences. The x-axis is time, measured in weeks. In weeks 0–29, we can see the distinct phases for DF Alpha (DF1 // week 0), DF/VE Alpha (DF5 // week 4), DF Beta (DF9 // week 8), DF Main 1 (DF29 // week 28), DF Main 2 (DF80 // week 79), DF Main 3 (DF106 // week 105), and DF Main 4 (DF132 // week 131).
+
+![](./images/emissions_first_5years.png)
+_OCEAN released to DF per week — first 5 years_
+
+## Emissions — First 20 years.
+
+The image below is like the previous one: OCEAN released per week, but now for the first 20 years. Week 131 onwards is DF Main 4. We can see that the y-value divides by two (“halvens”) every four years.
+
+![](./images/emissions_first_20years.png)
+_OCEAN released to DF per week — first 20 years_
+
+## Total OCEAN released.
+
+The image below shows the total OCEAN released by DF for the first 20 years. The y-axis is log-scaled to capture both the small initial rewards and exponentially larger values later on. The x-axis is also log-scaled so that we can more readily see how the curve converges over time.
+
+![](./images/emissions_lifetime.png)
+_Total OCEAN released to DF — first 20 years_
+
+## Example APYs
+
+The plot below shows estimated APY over time. Green includes both passive and active rewards; black is just passive rewards. As of DF29, wash consume is no longer profitable, so we should expect a large drop in DCV and therefore in active rewards. So passive rewards (black) provides a great baseline with upside in active rewards (green).
+
+APYs are an estimate because APY depends on OCEAN locked. OCEAN locked for future weeks is not known precisely; it must be estimated. The yellow line is the model for OCEAN locked. We modeled OCEAN locked by observing linear growth from week 5 (when OCEAN locking was introduced) to week 28 (now): OCEAN locked grew from 7.89M OCEAN to 34.98M OCEAN respectively, or 1.177M more OCEAN locked per week.
+
+![](./images/example_apys.png)
+_Green: estimated APYs (passive + active). Black: estimated APYs (just passive). Yellow: estimated staking_
+The plots are calculated from [this Google Sheet](https://docs.google.com/spreadsheets/d/1F4o7PbV45yW1aPWOJ2rwZEKkgJXbIk5Yq7tj8749drc/edit#gid=1051477754).
+
+OCEAN lock time affects APY. The numbers above assume that all locked OCEAN is locked for 4 years, so that 1 OCEAN → 1 veOCEAN. But APY could be much worse or more if you lock for shorter durations. Here are approximate bounds.
+
+If you lock for 4 years, and everyone else locks for 2, then multiply expected APY by 2. If you lock for 4 years and others for 1, then multiply by 4.
+Conversely, if you lock for 2 years and everyone else for 4, then divide your expected APY by 2. If you lock for 1 year and others for 4, then divide by 4.
+The numbers assume that you’re actively allocating veOCEAN allocation towards high-DCV data assets. For passive locking or low-DCV data assets, divide APY by 2 (approximate).

veOcean/faq.md

@@ -0,0 +1,16 @@
+# Data Farming FAQ
+
+_Q: I staked for just one day. What rewards might I expect?_
+
+At least 50 snapshots are randomly taken throughout the week. If you’ve staked just one day, and all else being equal, you should expect 1/7 the rewards compared to the full 7 days.
+
+_Q: The datatoken price may change throughout the week. What price is taken in the DCV calculation?_
+
+The price is taken at the same time as each consume. E.g. if a data asset has three consumes, where price was 1 OCEAN when the first consume happened, and the price was 10 OCEAN when the other consumes happened, then the total DCV for the asset is 1 + 10 + 10 = 21.
+
+_Q: Can the reward function change during a given week?
+
+No. At the beginning of a new DF round (DF1, DF2, etc), rules are laid out, either implicitly if no change from previous round, or explicitly in a blog post if there are new rules. This is: reward function, bounds, etc. Then teams stake, buy data, consume, etc. And LPs are given DF rewards based on staking, DCV, etc at the end of the week. Overall cycle time is one week.
+
+Caveat: it’s no at least in theory! Sometimes there may be tweaks if there is community consensus, or a bug.
+

veOcean/veOcean.md

@@ -0,0 +1,67 @@
+# veOCEAN
+
+veOCEAN is a fork of veCRV and uses the same parameters. Nearly 500 million USD is locked across all forks of veCRV, with the leading DeFi protocols adopting this standard. By leveraging this, Ocean Protocol takes one step further towards decentralization by streaming incentives towards contributors that are aligned with delivering fundamental protocol traction.
+
+veOCEAN stands for “vote escrowed” OCEAN. By holding veOCEAN you become a governance participant, eligible to receive rewards and engage with many different protocol mechanisms.
+
+You must lock up your OCEAN into the vault for to obtain veOCEAN.
+
+After creating your lock you will be credited veOCEAN. We sometimes refer to veOCEAN as your “voting power”.
+
+**WARNING:** You will not be able to retrieve your original OCEAN deposit until the lock ends.
+
+## What is time locking?
+
+Users can lock their OCEAN for different lengths of time to gain voting power. Our app is configured to lock OCEAN for a minimum of 2 weeks and a maximum of four years for max benefit.
+
+Users that lock their OCEAN for a longer period of time receive more veOCEAN to reflect their conviction in the system.
+
+| Year | Lock Multiplier | veOCEAN |
+| ---- | ----------| ------- |
+| 1    | 0.25x     | 0.25    |
+| 2    | 0.50x      | 0.50     |
+| 3    | 0.75x     | 0.75    |
+| 4    | 1.00x      | 1.00     |
+
+_The Lock Multiplier. Amount of veOCEAN received per OCEAN locked._
+
+If you’ve locked OCEAN for 4 years, you will be unable to retrieve your deposit until this time expires.
+
+After choosing your lock period and locking up your OCEAN into the vault, you will be credited with veOCEAN.
+
+veOCEAN is non-transferable. You can’t sell it or send it to other addresses.
+
+## Linear Decay
+
+Your veOCEAN balance will slowly start declining as soon as you receive it.
+
+veOCEAN balance decreases linearly over time until the Lock End Date. When your lock time has lapsed by 50%, you will have 50% of your original veOCEAN balance.
+
+When your lock time ends your veOCEAN balance will hit 0, and your OCEAN tokens can be withdrawn.
+
+If you lock 1.0 OCEAN for 4 years, you get 1.0 veOCEAN at the start.
+
+| Years Passed | veOCEAN Left |
+| ---- | ---- |
+| 1 year | 0.75 |
+| 2 years | 0.50 |
+| 3 years | 0.25 |
+| 4 years | 0.00 |
+
+At the end of your 4 years, your OCEAN is unlocked [1]
+
+## Replenishing your veOCEAN
+
+You can choose to update your lock and replenish your veOCEAN balance at any time.
+
+To maximize rewards, participants would need to update their 4-year lock every week in order to maintain their veOCEAN balance as high as possible.
+
+## What can I do with veOCEAN?
+
+veOCEAN allows you to engage with the protocol and benefit from the reward programs available.
+
+There are 4 things you can do with veOCEAN.
+1. **Hold it.** veOCEAN pays **Passive Rewards** every week.
+2. **Allocate it.** veOCEAN pays **Active Rewards** every week to the top performing Datasets, Algorithms, dApps, and more.
+3. **Delegate it.** You can delegate veOCEAN to other Data Farmers who can curate Datasets for you. In return for their services, these farmers may charge you a fee for helping you receive APY on **Active Rewards**. The Delegate feature has just been recently released and enables veOCEAN holders to more easily access rewards. 
+4. **2x Boost.** If you are a publisher, allocating veOCEAN to your own Dataset gives your veOCEAN a 2x Boost. This is an incentive for publishers to engage with their assets and benefit from from the protocol further.