# Overview of Yearn V3 Web Ecosystem
## Tech stack
### Lens
#### Block Diagram

#### Links
- [Documentation](https://hackmd.io/hwsCCUjlS8ux6dJxE528Zg?view)
- [Contracts](https://hackmd.io/UaNoIilwSL-KDqCehIIXhw?view)
- [Source Code](https://github.com/yearn/yearn-lens/)

Maintainer: x48

#### Features
- Aggregates on-chain data to make it easily consumable
- Components
- Oracle
- Calculations
- Registries
- Addresses generators
- Registry Adapters
- Lens
- Helpers
- TVL Adapters
- Delegation mapping
- Management list
- Configurable
- Add and update calculations individually
- All adapters are extendable (cascading fallback proxy supports new extensions)
- All storage variables can be updated (replace oracle, addresses generator, etc)
- Deprecate assest
- Assign an asset or strategy as delegated
- Adjust asset allowance addresses (zap out, migrate, etc)
- Supports pagination
- This is important for futureproofing
- Information scoped to user
- Per asset (user deposits, borrow or lend, etc)
- Per protocol (total user deposits, total user supply/borrow/borrow utilization ratio, etc.)
- Information scoped to asset (vault/IB market)
- Information scoped to protocol (total protocal statistics)
- Use cases
- Normalize all asset values to USDC
- User balances
- Vault balances
- On-chain TVL for DeFi Pulse
- Use TVL oracle to detect bad zaps via transaction simulation
- General purpose helper utilities are useful for Yearn partners and wider ecosystem
- Sushiswap - Sushi calculations
- Cream - Iron Bank calculations
- Luciano/Keep3r oracle
- Poolpi/LP calculations
- Will likely lower our Alchemy usage
- Fetch information much faster using Lens
- Should lower our CUPS (compute units per second)
- Save money
- Rapid integration
- Strategists use the strategists helper on their dashboard
- Utility will be backed into harvest simulation tool to prevent on-chain problems
- Simple integration point for any B2B who wish to pull Yearn data on-chain quickly
- Read-only

### SDK
#### Block Diagram

#### Links
- [High Level Documentation](https://hackmd.io/xQzyAoMwRdKQ62uE9rusCQ)
- [Autogenerated Documentation](https://yearn.github.io/yearn-sdk)
- [Source Code](https://github.com/yearn/yearn-sdk)

Maintainer: nymmrx

#### Features
- Aggregates on-chain and off-chain data to serve to front-ends and B2B integrations
- Fetches data from
- Lens
- Yearn-exporter
- Subgraph
- Yearn-meta (IPFS)
- Zapper
- Supports read and write
- Event driven architecture
- User deposits and then the user receives the appropriate state updates
- Underlying token balance update
- Vault balance update
- Vault TVL updates
- Every method can be called synchronously or asynchronously using the event architecture
- Events are built into every method programmatically
- Supports API caching layer
- All data that is not scoped to a user will be cached using the SDK caching layer
- Historic graphs (vault/protocol earnings)
- Any chart from yearn-exporter
- Can probably leverage yearn-exporter cache directly in this case
- Vault/IB data that is not scoped to a user (TVL)
- This will decrease Alchemy load limits (substansially for the graphs)
- Save money
- Maintains close parity to the lens contracts
- Important from a maintainence standpoint
- Supports a variety of new metrics powered by subgraph
- A few new KPIs
- Historical earnings over time (past)
- Per user
- Per vault
- Per protocol
- Spot earnings (historical earnings + current earnings)
- Per user
- Per vault
- Per protocol (protocol revenue)
- Balance weighted aggregate APY (estimated future earnings)
- Per user
- Per vault
- Per protocol
- Cross-chain support
- Reinitialize the SDK with the updated chain and the SDK will change lens contract addresses, chain ID and block explorer URL
- Written in typescript
- Can be used in JS or Typescript FE
- Supports autocompletion, type checking and documentation auto-generation
- Typescript was chosen for accessibility
- Use cases
- V3 front-end
- B2B integrators
- Strategist dashboard
- Vault management and configuration is taken care of for integrator
- An update in the data our SDK fetches means integrators are automatically taken care of
- Vault or IB market is deprecated
- Oracle calculations change
- Vault needs to be disabled entirely
- Vault needs to have APY disabled
- Deposit into a vault
- Via zap or directly
- Borrow or lend in IB

### IPFS Metadata


#### Links
[IPFS Directory Listing](http://meta.yearn.network/)
[Source Code](https://github.com/yearn/yearn-meta)

Maintainer: nymmrx

#### Features
- All _non-critical metadata_ is managed in an IPFS metadata repository
- Primary use case is to allow front-end vault settings to be tweaked very quickly without requiring users to edit code
- Instead an organization memeber can edit a JSON file in a github repository that will automatically build and deploy the updated IPFS metadata files
- Currently supported schemas and features
- Vaults
- Disable a vault completely
- Disable withdrawals from a vault
- Disable deposits to a vault
- Temporarily hide a vault (this can also be done via lens address generators)
- Configure APY calculation type
- Configure APY calculation paramaters (harvest number at which we wish to show APY)
- Vault name alias
- Vault symbol alias
- Custom vault token icon
- Temporarily hide APY
- Vault tagging
- Strategies
- Strategy name
- Strategy description
- Strategy authors
- Strategy image
- Generated with [new tool](https://usdml.nymm.app/) by nymmrx
- Tokens
- Token alias
- Token symbol alias
- Custom token image
- Use cases
- Quickly configure many aspects of a vault even if you are not a programmer (still requires PR review)
- Context: In the past several months there have been many instances where various instances where the front-end has been asked to tweak vault settings (typically in emergency situations where loss of funds could be made worse if we don't act quickly)
- Edit configuration in one place and then all integrators will get the update as well
- Redundancy through decentralization (Github assets has gone down several times causing token icons to fail)
- Maintain control over token icons
- CI is set up to automatically validate schemas and publish new pinned IPFS files with metadata
- IPNS (InterPlanetary Name System) is utilized to keep DNS links consistent
- Entire V3 front-end will also be hosted via IPFS

### Yearn-exporter
#### Links
[yearn.vision](https://yearn.vision)
[Source](https://github.com/yearn/yearn-exporter)

Maintainer: banteg

#### Features
- APY & TVL calculations have been ported to yearn-exporter
- Majority of calculation logic is moving from the existing API to yearn-exporter
- Intention is to collaborate and integrate with yearn-exporter team to allow both teams to leverage the work of one another
- Use yearn exporter for fine-grained/easily-updatable access to any on-chain data that subgraph does not provide
- Eventually utilize yearn-exporter for real-time notifications system
- Use cases
- Visually chart state changes in yearn vaults and strategies
- Cache historical charts
- Alerting

### Subgraph
#### Links
- [Documentation](https://github.com/yearn/yearn-subgraph)
- [Current subgraph explorer](https://thegraph.com/explorer/subgraph/tomprsn/yearn-vaults-v2-subgraph-mainnet?version=current)
- [Current subgraph API endpoint](https://api.thegraph.com/subgraphs/name/tomprsn/yearn-vaults-v2-subgraph-mainnet)
- [Source Code](https://github.com/yearn/yearn-vaults-v2-subgraph/)

Maintainer: salazarguille

#### Features
- Primary use case is to aggregate and transform historical on-chain data and to make easily queryable
- New subgraph supports many new long sought-after features
- Detailed view of strategies
- Historical strategy state
- Losses, gains and debt over time
- Configuration settings (debt limit)
- Historical deposits/withdraws/transfers
- In shares and underlying
- Historical balances of a vault
- Historical balances of a vault scoped to a user
- Historical total deposits/withdraw per user
- Historical price per share
- Historical earnings scoped to a vault
- Historical earnings scoped to a user (aggregated within subgraph itself)
- Returns generated in underlying tokens
- Endorsed and experimental vaults
- Historical management fees
- Use cases
- Provide users with meaningful metrics that are difficult to query on-chain
- Subgraph is our primary historical blockchain aggregation mechanism
- Allows historical aggregated data to be queried in bulk without affecting Alchemy dependence
- Saves money

### V3 Front-end
#### Block Diagram

#### Links
[Source Code](https://github.com/yearn/yearn-finance-v3/)

Maintainers: Gotzen, Turtle, Gambito

#### Features
- Complete SDK Integration
- Utilize SDK as primary source of truth (all read transactions)
- Utilize SDK for all write transactions
- Integration with SDK's event driven architecture
- Receive state updates from SDK any time an action is submitted
- Automatic integration with future event driven updates
- Receive realtime data
- Firehose (token vault/balances)
- Updates from yearn-exporter
- Notifications from SDK or any source
- Clean lightweight repository that learns from all of the lessons of v2
- Vaults are completely configurable via IPFS meta repo by proxy of the SDK
- Automatic support for disabling deposits/withdraws/APY, etc
- Supports localization
- Easy for anyone to add new languages
- Application error tracking
- Redux middleware integration with Sentry
- Analytics
- High level analytics using Plausible
- Fine grained analytics and support for custom user action events
- User settings
- Allow users to edit default slippage
- Allow users to edit accessibility options (increase font-size)
- Allow user to select or import a theme
- Allow user to set a language
- Allow user to set a default time range
- Transaction simulation
- Simulate a deposit, withdraw, borrow or lend before submitting a transaction
- Call out to Tenderly API
- This will potentially protect yearn users from transactions that could cost them a lot of money due to error somewhere along the chain
- The intention is to prevent this before it happens which is important for yearn's reputation and trust
- Utilize lens TVL oracle to detect estimated value of deposit token and estimated shares (or market position value)
- If the simulation detects an anomoly
- Warn the user before allowing them to submit the transaction
- Alert telegram group via webhook (infrastructure TBD)
- Service layer
- The front-end utilizes an intermediary "service layer" inbetween SDK and redux state
- Services implementations can easily be swapped and injected through the app
- Services execute core business logic and map external data providers to the app entities
- Generally the front-end maintains tight parity with the SDK and Lens
- In the event of unpredictable randomizations the service layer acts as a lightweight easily upgradable shim that can manage randomizations (short term fixes) until a long term fix can be implemented
- The service layer is our major protection layer to keep our front-end clean regardless of randomizations
- V2 is full of hard-coded hot-fixes at this point. Now most will be abstracted away and new hot-fixes we haven't accounted for will live here and then get migrated to the IPFS repo
- Repo is written in Typescript
- Although Typescript is slower than javascript for new projects it is the logical choice for large repositories with shared contributors (particularly open source repos)
- Javascript is generally faster because it lets you do anything with data
- Because it lets you do anything with data it's much more prone to errors
- Typescript will make it more difficult for contributors to cause regressions
- Separation of UI with V3 core business logic
- It's easy to implement alternative front-ends while re-using the core v3 logic
- Implementation of multiple layers that can be unit tested and mocked
- We currently support a complete data mocking layer that can be turned on or off for quick debugging
- Better error handling and status updates
- Every dispatched action comes complete with loading/status and error state
- This means the app can provide meaningful errors to the user in the event anything goes wrong
- Cross-chain support
- Reinitialize the SDK with the updated chain and the SDK will change lens contract addresses, chain ID and block explorer URL
- Support custom themes
- Hot switch themes
- Eventually we could allow anyone to set or import custom themes similar to how linear does
- The idea is to drive user engagement and to enable users to feel at home at yearn (it's their own custom workspace for managing assets)
- Don't like how it looks? Change it
- Will support custom background images as well, though it is not MVP
- Use cases
- Create a clean front-end that is capable of handling the scale and speed at which yearn innovates
- Serve as a template for B2B integrators
- SDK usage example
- B2B usage
- Forkable repository written with the most popular DeFi tech stack aims to make the V3 UI an accessible demonstration of how to integrate with Yearn

## Designs
- Research
- Extensively analyze [Gravity's VOC](https://miro.com/app/board/o9J_kmk6x_4=/) and [x48's Customer Feedback document](https://hackmd.io/K2askVsDSVCuRx9mHqo4MQ) to identify all primary use cases and most requested features
- Compare and contrast x48 and Gravity's document to find the most common requests
- High level goals
- Provide an onboarding experience for new users
- Provide a guided experience
- Provide recommendations everywhere
- Provide users with the information they need without cluttering the UI or overloading the user
- Intention is to explain core concepts succuciently while allowing users who want to learn more to dive deeper
- Allow users to quickly understand their position in the Yearn ecosystem (in vaults, iron bank, and in total)
- Allow users to understand how much they've earned
- Historical earnings and current earnings
- Allow users to understand how much they should expect to earn (projected earnings/balance weighted aggregate APY based on their positions)
- Allow users to quickly find the best earning opportunity based on their wallet or risk tolerance
- Allow users to explore all opportunities (with context and information about each opportunity)
- What is the underlying vault token?
- Is it a stablecoin?
- Where can I find more information about it?
- What does this vault do?
- High level summary of strategy with most balance
- Opportunity to view all strategies, descriptions and charts for the curious user
- Easily deposit and withdraw into a vault
- Easily borrow or lend assets with Iron Bank
- Allow users to view their wallet and perform actions directly from their wallet
- "I have this, I want to do this (invest/borrow/lend)"
- Understand fee structure and APY breakdown
- Progressive design that changes as the user utilizes the app

### Key user interface use cases (from x48's customer feedback document)
#### Statistics
##### Past earnings
- How much have I earned
- Show historical earnings normalized to USD/ETH (vaults)
- Total (top of page)
- Per vault (vault row)
- How has my portfolio changed over time
- Show graph of portfolio earnings over time
- Total
- Per vault
- How has each asset performed
- Show graph of historical vault earnings over time

##### Present earnings
- How much am I earning currently ($/week) (vault)
- Show balance-weighted aggregate APY normalized to USD/ETH (vaults/dashboard)
- Total
- Per vault
- How much do I have deposited (what is my current position)
- Show vault balance normalized to USD/ETH
- Order vaults by normalized vault balance (high value vault shown first)
- Show vaults a user has deposited in separate from a list of opportunities (don't group deposits with investment opportunities)

##### Future earnings
- How much do I expect to earn based on my current position
- Show estimated earnings per week based on aggregate APY
- What are good investment opportunities
- What is the risk vs reward
- Show whether or not the vault token is a stable coin
- Allow users to quickly find vaults that match tokens they hold
- Allow users to find highest APY stablecoin vault
- Allow users to find highest APY vault in general
- Allow users to filter vaults by tags
- Suggest opportunities to users rather than showing them a giant list of derivative vaults
- Allow users to enter any vault with ETH or stablecoins
- Show a description of what each vault/strategy does
- Show a chart for each strategy

#### Deposit/Withdraw
- Vastly simplified deposit/withdraw interface
- Quick deposit/withdraw concept
- User is shown a transaction modal scoped to their action rather than hiding UI behind a tab, or showing all inputs at the same time
- Allow user to approve a vault deposit transaction or alternatively infinite approve
- Show useful information about the transaction before the user submits
- Show deposit value normalized to USDC
- Show estimated output value before submitting a transaction (using simulation)
- Show users maximum slippage (allow them to configure it)
- Make interface clear and easy to understand

#### Key concepts
- Wallet based approach (I have these tokens, what can I do with them)
- Onboarding on every page
- Recommendations everywhere
- Prioritize showing user's current positions
- Ability to explore opportunities (user must be able to explore all vaults)
- Quick deposit/withdraw/lend/borrow
- Actions are inline with each asset row
- This allows users to very quickly load a transaction modal that is directly scoped to the action (deposit/withdraw/borrow/lend/repay)
- Showing inline actions helps to orient the user
- A user looks at an asset and they immediately know what they can do with the asset
- Action buttons are not hidden behind an accordion view
- Action buttons are not hidden behind a tabular view
- Every input for deposit and withdraw is not shown at the same time (instead they are appropritely scoped to the action)
- Movement as a visual aid
- Room is allocated to show warning messages
- User must have a clear indication of transaction progress (what is happening)
- Visual hierarchy should very quickly guide the user to the appropriate place
- Transaction amount is front-and-center and appropriately sized
- Consideration is given to how we deal with large asset amounts
- Information tooltips everywhere
- USDC normalized values everywhere (with ability to see token amounts as well)
- Ability to dive deeper into a vault
- Understand what a vault's token is
- Understand what a vault is doing (strategy information)
- Meaningful metrics
- Number goes up, what is my number (earnings)?
- How much has the whole protocol earned?
- At what rate am I earning based on my position?
- How much do I have deposited?
- How much does the protocol have deposited?
- How much can I deposit?
- How much can I earn given what I have?
- Simple/module approach
- Mobile layout is a first class citizen
- Standardized page layout for products and dashboard
- Useful metrics scoped to the page the user is on
- If I'm on the dashboard I will see metrics scoped to the user's entire portfolio
- If I'm on valuts I will see metrics scoped to all vaults
- If I'm on detailed vault view I will see metrics scoped to a vault
- Onboarding (user can close onboarding or they can hide it indefinitely)
- Recommendations
- Scoped to a user's wallet
- Based on risk
- Stable recommendation
- Eth recommendation
- Derivative token recommendation
- User's position
- Concept and categories borrowed from thorough analysis of Zapper front-end and API data structures
- Categories
- Deposited (vaults)
- Lending (IB)
- Borrowing (IB)
- Claimable Yield (pickle/veCRV)
- Staked (pickle/veCRV)
- Opportunities
- Vaults
- All vaults paginated and sortable
- Ordered by user's underlying token balance by default
- Filter by tag (updatable in IPFS metadata)
- Iron Bank
- All Iron Bank markets paginated and sortable
- Ordered by user's underlying token balance by default
- Ability to zoom into an asset
- Standardized page layout
- Easy for the user to understand the UI when switching between products
- Layout
- High level metrics associated with the asset
- Information about the asset to help guide the user
- Ability to interact directly with the asset
- Chart of asset performance over time
- My transaction history associated with the asset
- Standalone vault page
- Allows user to link directly to an asset
- Allows more curious users to obtain more information and context about the vault and underlying token
- Shows metrics that are useful to a user when deciding whether or not do deposit
- Total earnings over time
- My earnings
- APY
- Ability to understand how my position has changed over time
- Previous transactions
- Earnings over time
- Customize look and feel

### Historical Context
- V1 UX was not great (it was ok for a few vaults but it did not scale well)
- V2 UX mimicked V1 UX
- x48 and Gravity spent an extensive amount of time researching UX and soliciting feedback from customers
- We are building a highly scalable foundational architecture that is more advanced, adaptable and maintainable than many competitors
- Our focus is on simplicity, ease-of-use, guiding the user and providing the user with useful information
- We are building for the future
- The architecture we've built is based on our experiences building and maintaing the V2 web ecosystem (and adjacent projects)
- The architecture and designs are based on VOC from Gravity and x48's research