Merge pull request #90 from tellor-io/adr

Adr

adr/adr001 - dual delegation.md

@@ -0,0 +1,42 @@
+# ADR 001: Dual Delegation
+
+## Authors
+
+@themandalore
+
+## Changelog
+
+- 2024-02-21: initial version
+
+## Context
+
+Layer uses a delegated proof-of-stake(dPoS) model where there is a set number of validators, but all token holders can delegate to the top validators to share in rewards.  Tellor uses this delegation but adds a second delegation for token holders, reporting duties.  Each token can be used as a stake for reporting and for validating.  Parties can delegate both the reporting and validating to the same party, to different parties, or even to themselves.  The same token is subject to slashing by either method (reporting data or failing to honestly validate the chain) and the stake balance for both delegations is immediately upon either consequence.
+
+The reason for this dual delegation is threefold:
+
+    *  validator sets are capped in tendermint based systems, however we need to remove that cap to enable smaller and more reporters to help decentralize the data provider set.  
+    *  The cost of bridging is directly tied to the validator set size (verifying signatures for the light client bridges), so a large validator set such as Ethereum is unfeasible for our intended uses (the need for fast, cheap bridging of data).  
+    *  Reporting and validating are separate duties.  Cosmos validators for the most part just run hardware and have little interaction with the chain.  Running a reporter however is the hard part.  You must maintain lists of API's, monitor for disputes, and help users make sure they're getting the best data on-chain.  These roles should be separate so that each party can focus on what they do best.  
+
+
+## Alternative Approaches
+
+### Validators and Reporters are the same thing
+
+Another discussed approach to was that validators would be reporters.  This is the most straightforward implementation of an oracle in the cosmos sdk.  The benefit here is that tokens are not dual staked, but rather there is just one critical role for tellor.   It also plays nicely in that all rewards are kept within the reporting ecosystem and validation can almost be seen as an addon.  The downside here is that the set of reporters is limited to the validator set.  For smaller queries, you would need to get support of a giant validator in order to even get data on-chain.  This could be prohibitively expensive.  Many other chains do this, where they force validators to support each query.  We wanted to avoid this for decentralziation and robustness reasons (should your chain halt if people don't feel comfortable reporting?  What if certain jurisdictions don't have knowledge of a given piece of information).  
+
+### No dual delegation - competing staking
+
+This option is if you want two sets of participants, but you make them compete for stake.  This means that a token holder needs to decide to either validate the chain or report (or delegate to someone doing one or the other).  The pro is that tokens are locked for their own specific purpose.  The con is that validators and reporters are competing for tokens.  This means that if your chain is more secure, each report is less secure (less value locked there).  It would also be confusing to token holders who likely just want a return, whether to delegate to a validator or a reporter.  
+
+
+### Two token model
+
+Another option is to have a validating token and a reporting token for these two purposes.  Although it splits it in terms of the accounting pieces, the issue of where the value is driven is still the same problem as competing staking options.  New buyers of TRB could be confused as to which one holds value and dynamics of where returns are driven is still largely interdependent in how the system mints rewards.  
+
+## Issues / Notes on Implementation
+
+Handling disputes here is particularly tricky.  Making sure that the correct tokens are taken from the proper validator if a reporter is disputed must be handled correctly.  
+
+The risks here are presumed to be separate, but it should be noted that they may not be.  This is a sort of "restaking" where value is being locked for two separate purposes.  It must be monitored that reporting errors can affect the validator set and validator mishaps can affect the security of data reports.  Bribes to overtake the tellor chain can now be two fold also, where you could either bribe reporters OR bribe validators.  This risk is known, however the interconnectedness of each party should help keep the system in check as both are necessary to keep the system functioning properly.  Other restaking systems perform outside duties, where as this dual delegation is more for role separation within the same system, with both pieces being necessary for the chain to be valuable.  
+

adr/adr002 - handling of tips after report.md

@@ -0,0 +1,27 @@
+# ADR 002: Handling of tips after report
+
+
+## Authors
+
+@themandalore
+
+## Changelog
+
+- 2024-02-21: initial version
+
+## Context
+
+In layer, when a user sends free floating tokens as a tip, the party(ies) that report for that queryId next cycle are given the tip.  Once reported for, these tips are locked as reporting stake.  This is because of how tellor governance is structured, namely to prevent people from farming voting power.  
+
+If they were not locked, a party could tip a random query that only they know how to report for.  They could report, then tip those exact same tokens, thus looping them in order to look like there is ton of tip demand for this query.  The two methods to prevent this are a) a 2% fee on tips and b) locking the tip as a reporting stake.  Now if the party wishes to withdraw that tip, they will have to wait the 21 day unbonding period.  
+
+
+## Alternative Approaches
+
+### Higher fee burn on tips
+
+The other method we could do is just increase that 2% fee to something like 5 or 10%, thus completely draining the attacker if they did this method.  Although this could be a solution, limiting that fee is important because it supports having on-chain tips (can be tracked for governance/ usage purposes) vs off-chain.  
+
+
+## Issues / Notes on Implementation
+

adr/adr003 - nonces for bridging.md

@@ -0,0 +1,33 @@
+# ADR 003: Nonces for Bridging
+
+## Authors
+
+@themandalore
+@tkernell
+
+## Changelog
+
+- 2024-02-26: unbonding period 
+- 2024-02-21: initial version
+
+## Context
+
+We include a timestamp as one of the parameters used in bridge validator set updates in place of a nonce. This is separate than the original blobstream which also had a univesal nonce. Each time the bridge validator set changes, all validators sign a hash of multiple parameters, including the new validator set timestamp. The bridge contract enforces that this timestamp is greater than the previous one. The bridge contract also uses this timestamp to determine whether a given validator set record is stale by comparing the timestamp to the Layer unbonding period. We use the stricly increasing timestamp rule to prevent the bridge from accepting old validator set attestations, and it also allows the bridge to save gas costs by skipping blocks. In addition, we use the age of a validator set attestation to determine whether that validator set's tokens are still locked as stakes and thus eligible for slashing.
+
+We do not include a nonce for oracle data attestations. We use attestation timestamps and report timestamps instead to determine the ages of these, respectively. We do not necessarily need every single oracle attestation to be bridged to every single user chain, and they do not have to be bridged in the order in which they were created. We include `nextTimestamp` and `previousTimestamp` in each oracle attestion to determine ordering properties of oracle reports.
+
+
+## Alternative Approaches
+
+### require a universal nonce
+
+This requires pushing of each request.
+
+
+## Issues / Notes on Implementation
+
+The validator set can change significantly very quickly due to disputes and slashing events, so comparing a validator set's age to the unbonding period does not ensure that a given validator still has tokens at stake. 
+
+## Links
+
+https://github.com/celestiaorg/blobstream-contracts 

adr/adr004 - time based rewards eligibility.md

@@ -0,0 +1,43 @@
+# ADR 004: Time based rewards eligibility
+
+## Authors
+
+@themandalore
+
+## Changelog
+
+- 2024-02-22: initial version
+
+## Context
+
+Currently time based rewards (inflationary rewards for reporters) go only to cycle list queries. Ideally we support any query, basically just adding a small amount of inflationary rewards to each piece of data.  The rationale is two fold:
+a) subsidizes users needing to tip
+b) provides a heart beat for the system in absence of tips (reporters are then around ready to report and we can all see they are reporting accurately)
+
+
+The issue in just distributing inflationary rewards to all reported data is that there becomes an incentive to report more (unneeded) data in order to increase the amount of rewards given to your reporter.  For instance if you have 10 reporters (equal weight) and they all report for BTC/USD, then they would split the inflationary rewards (if they have unequal weight it would be distributed based upon reporting weight).  The problem is what happens when one of those parties reports for TRB/BTC (imagine a query that only they support)?  For calculation purposes, let's say they report for 9 new queries that only they support.  If the inflation is split based on total reported queries, they had 9 reports and all other reporters (equal weight) also had 9, so our attacker would get 50% of the rewards.   
+
+In order to prevent this we only give inflationary rewards to cycle list queries ( queries that have been voted on by governance that everyone should support at a base level).  
+
+
+## Alternative Approaches
+
+### tbr directly tied to tips
+
+We could solve this by having it be directly tied to tips.  For this solution, you double tips with inflationary rewards.  This would work like if a tip comes in for BTC/USD for 2 TRB, you add 2 TRB as rewards.  The problem again here is that it incentivizes tipping (an extra step) for a query no one wants (reporters just tip to get the reward) and is hard to police that parties aren't just tipping lowly supported queries to boost their own rewards.  
+
+### only inflation for validators
+
+An easy solution is to keep the inflation for validators and not reporters.  This could be an option, but would not incentivize parties to keep the chain active unless tipped, something we had hoped to do with inflationary rewards. 
+
+### only cycle rewards if consensus reached 
+
+A discussed option was to only provide inflationary rewards to queries that hit consnensus.  This sort of solves the problem, but there would still be the issue that some parties would want to support queries that had 66% support vs those with 100% support.  There would also be a race to submit for more things, (e.g. if I do more than everyone else I'll get more), which is both good, but also fills up the chain unnecessarilty.  
+
+### weight only used once
+
+You could solve the problem by only counting the weight once.  The problem here is that you may be more likely to submit for things that no one can dispute (e.g. we'll just do EVM queries or a static answer like (who is the president?)).  This would take risk away but would not help the chain in anyway.  
+
+
+## Issues / Notes on Implementation
+

adr/adr005 - dispute levels.md

@@ -0,0 +1,47 @@
+# ADR 005: Dispute Levels
+
+## Authors
+
+@themandalore
+
+## Changelog
+
+- 2024-02-22: initial version
+
+## Context
+
+Tellor disputes have three categories:  warning, minor, and major.  The decision for three is even arbitrary.  The point is to separate out major disputes (e.g. attacks) from minor disputes such as being slightly off for a calculation or having a single API failure.  To three categories are as follows:
+
+    * Warning (dispute fee is 1% of stake)- jail, but no lock, can call a function to be released from jail and begin reporting again
+    * Minor Infraction (dispute fee is 5% of stake) - jailed for 10 minutes and out when they call the release from jail function
+    * Major Infraction (dispute fee is 100% of stake) - jail until dispute over ( since 100% of stake).
+
+A release function has to be called after a warning or minor infraction to ensure the staker has looked at the dispute and implemented a fix as necessary. Infractions in these lower two tiers can generally be assumed to not be malicious. 
+
+
+After specifying the dispute category, the disputer will submit an amount of TRB up to the minimum slashing amount before the dispute can initiate. If they don’t have enough funds themselves, for up to one day, others can add to the pot until they hit the slashing amount(1, 5, or 100 percent depending on the slashing category).  Once the amount is hit (could be hit instantly upon proposing the dispute, or could take up to a day), the potential slashing amount will be taken from the disputed validator and placed into a locked stake.
+
+To clarify, a warning is more of a pause.  For example, your machine submitted a bad value.  Address it and click "unjail" to resume again.  
+A minor infraction will usually come after a warning, for example, you're submitting 1% under everyone else repeatedly and threatining to pull down the median.  
+Finally a major infraction should be saved for attacks.  The reporter is slashed entirely.  For example, if a bad value is submitted for (e.g. BTC 1M), we can assume it's not an attack and submit a warning.  If however, they unjail themselves and continue to submit bad values, they run the risk of being slashed entirely. 
+
+
+
+## Alternative Approaches
+
+### no categories - free floating percentages
+
+One option is to just have the disputer pick a percent of the reporters stake and submit for a dispute.  Then jail time could be also be on a scale (up to 2 days (vote time) as a percent of stake).  This would be relatively straight forward to code, but we'd expect categories and norms to pop up similar to what we proposed.  For new repoters and disputers it could also be unclear as to how much to dispute. By having clear categories with examples, we hope to minimize the chance of full disputes being open for minor issues. 
+
+### different weights for each category
+
+1,5,and 100 we're picked relatively arbitrarily.  The 100% is obviously correct for stopping an attack, but we went back and forth between 1 and 5 vs higher numbers like 5,10 or even 10,25.  Ultimately the cosmos ecosystem is much more exposed to smaller slashing penalities and the larger amounts seem unecessary if we have a sufficiently decentralized reporter set.  Additionaly, these levels can be adjusted by ogvernance if they seem insufficient. 
+
+## Issues / Notes on Implementation
+
+One issue to keep in mind w/regard to jail times and slashing is that it is likely that LST's pop up for reporter/validator stakes.  Should this happen, reporters will likely have little lock up with regard to posting bad prices and we can opt for faster freezing as its not their stake that they are actually losing.  This is a problem with any delegated system and must be monitored that incentives and slashing conditions properly discentive operators even if it is not their capital.  
+
+
+## References / Links
+
+[https://forum.celestia.org/t/defending-against-lst-monopolies/1554/27](https://forum.celestia.org/t/defending-against-lst-monopolies/1554/27)

adr/adr006 - usage of staked tokens for disputes.md

@@ -0,0 +1,33 @@
+# ADR 006: Usage of Staked Tokens for Disputes
+
+## Authors
+
+@themandalore
+
+## Changelog
+
+- 2024-02-22: initial version
+
+## Context
+
+In tellor's dual delegation model, the question arises who can use tokens to initiate the dispute?  Can the validator or reporter use tokens delegated to them?  Can staked tokens even be used?
+
+The current implementation is that only reporters can use the ones delegated for disputes.  Not only does this make the code more straightforward, but it helps to separate the tasks - validators do chain stuff, reporters are in charge of whether the data is accurate.  
+
+
+## Alternative Approaches
+
+### Only the validator can use them for a dispute
+
+This option would also work.  More for us, just keeping it consistent with the separation of duties. 
+
+### both reporter and validator can use them for a dispute
+
+We had thought about this, but we don't want it to be too much of a race.  If validators and reporters are racing to start a dispute, it could be seen as a negative where they're not thinking out the situation fully. 
+
+### Neither can use them for a dispute (only free floating tokens)
+
+This is how old tellor works.  This option is fine, but in a world where we hope that a high (>50%) of tokens are staked, starting a major dispute could become infeasible.  Consensus assumes that up to 1/3 could be compromised.  If we assume that 1/3 of staked tokens is malicous, we need to have that amount of tokens available to dispute in the case of an attack.  If those tokens are all locked on CEX's or not just waiting to dispute, there could be a costly delay to the dispute.  By allowing staked parties to initiate the dispute, you will always have enough tokens as long as the consensus 50% is not breached.  
+
+## Issues / Notes on Implementation
+

adr/adr007 - fees on tips.md

@@ -0,0 +1,26 @@
+# ADR 007: Fees on Tips
+
+## Authors
+
+@themandalore
+
+## Changelog
+
+- 2024-02-21: initial version
+
+## Context
+
+Why 2% fee on tips
+
+
+## Alternative Approaches
+
+### No Fee
+
+### Higher fee
+
+We could just increase that 2% fee to something like 5 or 10%.  Although this could be a solution, limiting that fee is important because it supports having on-chain tips (can be tracked for governance/ usage purposes) vs off-chain.  
+
+
+## Issues / Notes on Implementation
+

adr/adr008 - validator set size.md

@@ -0,0 +1,28 @@
+# ADR 008: Validator Set Size
+
+## Authors
+
+@themandalore
+
+## Changelog
+
+- 2024-02-21: initial version
+
+## Context
+
+Why 100 Validators
+
+
+## Alternative Approaches
+
+### More validators
+
+More decentralized
+
+### Less validators
+
+Cheaper bridging, faster blocktimes
+
+
+## Issues / Notes on Implementation
+