Vaults v3 update

docs/contributing/contribute.md

@@ -2,7 +2,7 @@
 
 ## Yearn Contributors
 
-Help build the future of finance, shape your skills, and grow the Yearn ecosystem. Before joining our community, take some time to understand the philosophy behind Yearn through the [The Bluepill](https://yfistory.org/thebluepill) and [Yearn Manifesto](https://gov.yearn.fi/t/how-we-think-about-yearn/7137).
+Help build the future of finance, shape your skills, and grow the Yearn ecosystem. Before joining our community, take some time to understand the philosophy behind Yearn through the [The Bluepill](https://bluepill.yearn.dev/) and [Yearn Manifesto](https://gov.yearn.fi/t/how-we-think-about-yearn/7137).
 
 ## How to Contribute
 

docs/contributing/governance/proposal-process.md

@@ -1,6 +1,6 @@
 # Proposal Process
 
-[veYFI](/contributing/governance/veyfi) token holders control the Yearn ecosystem through off-chain proposals and votes via [Snapshot](https://snapshot.org/#/ybaby.eth). Proposals that generate majority support (>50% of the vote) are implemented by a 9-member multi-signature wallet, and 6 out of 9 wallet signers must sign for a change to be implemented. The [members of the multi-signature wallet](/developers/security/multisig#members) were voted in by YFI holders and are subject to change from future governance votes.
+[veYFI](/contributing/governance/veyfi) token holders control the Yearn ecosystem through off-chain proposals and votes via [Snapshot](https://snapshot.org/#/s:veyfi.eth). Proposals that generate majority support (>50% of the vote) are implemented by a 9-member multi-signature wallet, and 6 out of 9 wallet signers must sign for a change to be implemented. The [members of the multi-signature wallet](/developers/security/multisig#members) were voted in by YFI holders and are subject to change from future governance votes.
 
 ## Discussion
 

docs/developers/addresses/v3-contracts.md

@@ -76,7 +76,7 @@ For a more complete list of all available periphery contracts visit the [Periphe
 
 Yearn Specific contracts and roles, as well as the most up to date V3 registry can be retrieved on chain from the Role Manager.
 
-To find individual vaults, use the V3 Registry below or refer to https://yearn.fi
+To find individual vaults, use the V3 Registry below or refer to https://yearn.fi/v3
 
 ### EVM Stable Addresses
 

docs/developers/data-services/yearn-stack.md

@@ -59,17 +59,17 @@ Yearn SDK integrates several components, both on-chain and off-chain.
 ### Historical APY and TVL
 
 - Yearn Exporter provides a simple backend solution for storing real-time stats from yearn products.
-- Metrics are stored in a timeseries database and will be exposed by an api, accessible by SDK and third-party.
+- Metrics are stored in a time series database and will be exposed by an API, accessible by SDK and third-party.
 
-### SDK, aggregator of many datasources
+### SDK, aggregator of many data sources
 
 - SDK will provide a simple interface for all integrators, including ourselves.
-- Read methods will seamlessly integrate with all datasources, while keeping coherent datastructures.
+- Read methods will seamlessly integrate with all data sources, while keeping coherent data structures.
 - Write methods talk directly to assets on chain. Execution of write transactions will trigger refresh events so data freshness of frontend (or other integration platforms) will still be preserved.
 
 ### Historical User Earnings
 
-- Yearn Subgraph leverages thegraph to store historical user data that can be aggregated to display historical earnings.
+- Yearn Subgraph leverages The Graph to store historical user data that can be aggregated to display historical earnings.
 
 ### Metadata
 
@@ -122,4 +122,4 @@ We can store Asset informations so in critical situations we can toggle interact
 
 <p align="center">
   <img src="https://i.imgur.com/LfJmzkK.png" alt="Frontend Chart"/>
-</p>
+</p>

docs/developers/smart-contracts/deprecated/V3/version-3.0.2/periphery/CommonReportTrigger.md

@@ -160,7 +160,7 @@ function setCustomVaultBaseFee(address _vault, address _strategy, uint256 _baseF
 
 ### strategyReportTrigger
 
-Returns wether or not a strategy is ready for a keeper to call `report`.
+Returns whether or not a strategy is ready for a keeper to call `report`.
 
 *Will first check if a custom trigger is set. If not it will use
 the default trigger flow.*
@@ -217,7 +217,7 @@ function defaultStrategyReportTrigger(address _strategy) public view virtual ret
 
 ### vaultReportTrigger
 
-Return wether or not a report should be called on a vault for
+Return whether or not a report should be called on a vault for
 a specific strategy.
 
 *Will first check if a custom trigger is set. If not it will use
@@ -323,7 +323,7 @@ function getCurrentBaseFee() public view virtual returns (uint256);
 
 ### isCurrentBaseFeeAcceptable
 
-Returns wether or not the current base fee is acceptable
+Returns whether or not the current base fee is acceptable
 based on the default `acceptableBaseFee`.
 
 *Can be used in custom triggers to easily still use this contracts

docs/developers/smart-contracts/deprecated/V3/version-3.0.3/Periphery/CommonReportTrigger.md

@@ -161,7 +161,7 @@ function setCustomVaultBaseFee(address _vault, address _strategy, uint256 _baseF
 
 ### strategyReportTrigger
 
-Returns wether or not a strategy is ready for a keeper to call `report`.
+Returns whether or not a strategy is ready for a keeper to call `report`.
 
 *Will first check if a custom trigger is set. If not it will use
 the default trigger flow.*
@@ -218,7 +218,7 @@ function defaultStrategyReportTrigger(address _strategy) public view virtual ret
 
 ### vaultReportTrigger
 
-Return wether or not a report should be called on a vault for
+Return whether or not a report should be called on a vault for
 a specific strategy.
 
 *Will first check if a custom trigger is set. If not it will use
@@ -324,7 +324,7 @@ function getCurrentBaseFee() public view virtual returns (uint256);
 
 ### isCurrentBaseFeeAcceptable
 
-Returns wether or not the current base fee is acceptable
+Returns whether or not the current base fee is acceptable
 based on the default `acceptableBaseFee`.
 
 *Can be used in custom triggers to easily still use this contracts

docs/developers/smart-contracts/deprecated/V3/version-3.0.3/Periphery/DebtAllocator.md

@@ -540,7 +540,7 @@ function getStrategyMaxRatio(address _vault, address _strategy) public view virt
 
 ### isCurrentBaseFeeAcceptable
 
-Returns wether or not the current base fee is acceptable
+Returns whether or not the current base fee is acceptable
 based on the `maxAcceptableBaseFee`.
 
 ```solidity

docs/developers/v3/Integrating_v3.md

@@ -82,16 +82,16 @@ There are multiple periphery contracts that can be helpful to get information ab
 Retrieve all of the endorsed vaults on a specific chain.
 
 - `getAllEndorsedVaults()` Returns a nested array sorted by vaults `asset` of all endorsed vaults in that registry.
-- `getEndorsedVaults(address _asset)` Returns and array of all endorsed vaults for that asset
+- `getEndorsedVaults(address _asset)` Returns an array of all endorsed vaults for that asset
 - `vaultInfo(address _vault)` Return the [`Info`](/developers/smart-contracts/V3/Periphery/Registry#structs) struct for an endorsed vault that includes its underlying asset, release version, deployment timestamp, vault 'type' (i.e. multi-strategy or single-strategy) and any tag.
 
 ### Role Manager
 
 Manages all of the multi-strategy vaults on a chain, and holds the `role_manager` position for those vaults.
 
-All the other periphery contracts and Yearn multisigs can be retrieved from the Role manager as well using the getter functions, such as `getBrain()`/`getPositionHolder(keccak256("Brain"))`, `getRegistry()`/`getPositionHolder(keccak256("Registry"))`, `getDebtAllocator(vault)`, .
+All the other periphery contracts and Yearn multisigs can be retrieved from the Role manager as well using the getter functions, such as `getBrain()`/`getPositionHolder(keccak256("Brain"))`, `getRegistry()`/`getPositionHolder(keccak256("Registry"))`, `getDebtAllocator(vault)`.
 
-- [`getAllVaults()`](/developers/smart-contracts/V3/Periphery/RoleManager#getallvaults) Returns and array for all multi-strategy vaults the contract is the role manager for.
+- [`getAllVaults()`](/developers/smart-contracts/V3/Periphery/RoleManager#getallvaults) Returns an array for all multi-strategy vaults the contract is the role manager for.
 - [`getVault(asset, apiVersion, category)`](/developers/smart-contracts/V3/Periphery/RoleManager#getvault) Returns the vault if any based on the inputs.
 
 #### Category

docs/developers/v3/periphery.md

@@ -6,8 +6,8 @@ This is a non-exhaustive list of the current periphery contracts developed or de
 
 For the most updated contracts visit:
 
-Vault Periphery Repo: https://github.com/yearn/vault-periphery
-TokenizedStrategy Periphery: https://github.com/yearn/tokenized-strategy-periphery
+- Vault Periphery Repo: https://github.com/yearn/vault-periphery
+- TokenizedStrategy Periphery: https://github.com/yearn/tokenized-strategy-periphery
 
 The deployed address of most periphery contracts or their corresponding factories can be found on chain from the Protocol Address provider: `0x775F09d6f3c8D2182DFA8bce8628acf51105653c`
 

docs/developers/v3/protocol_fees.md

@@ -1,10 +1,13 @@
 # Protocol Fees
 
-The V3 system sees the introduction of "Protocol Fees" to the stack, a percentage charged each time a V3 vault or strategy "reports".
+V3 introduces a **protocol fee** that is applied by the **vault** on each strategy
+`report()`. This fee is a **percentage of the total fees** returned by the
+Accountant (management/performance fees), not a direct percentage of profit.
 
-Protocol fees give the managers of vaults and strategies complete control over the fees charged while rewarding Yearn for supplying the infrastructure those vaults are built on.
-
-Yearn Governance dictates the amount of the Protocol fee and can be set anywhere between 0 - 50%. Yearn governance also holds the ability to set custom protocol fees for individual vaults and strategies. Allowing full customization of the system.
+The protocol fee is configured in the VaultFactory (default + optional per‑vault
+custom overrides). Governance controls the allowed values, which can be set anywhere
+from 0% to 50%. The protocol fee recipient is stored in the VaultFactory and is the
+default recipient even when a custom protocol fee is set for a specific vault.
 
 ```markdown title="Example"
 profit = 100
@@ -19,12 +22,16 @@ performance_fees = total_fees - protocol_fees = 18
 2 would get paid to the Yearn Treasury.
 ```
 
-You can retrieve both the default protocol fee as well as if a custom config has been set for a specific vault or strategy using the Vault Factory that corresponds to that vault's API.
+You can retrieve both the default protocol fee and a vault‑specific override using
+the VaultFactory that corresponds to that vault’s API.
 
 ``` solidity title="Examples"
 # Retrieve the default config.
 vaultFactory.protocol_fee_config()
 
 # Check a specific vault current config to be used
 vaultFactory.protocol_fee_config(vault_address)
+
+# Check whether a custom override is active for a vault
+vaultFactory.use_custom_protocol_fee(vault_address)
 ```

docs/developers/v3/strategy_writing_guide.md

@@ -338,7 +338,7 @@ function availableDepositLimit(
     **Returns**: NONE.
 
     **Good to Know**:
-    - This can only be called once a strategy is shut down.
+    - This can only be called after a strategy is shut down.
     - The `_amount` can be more than is available to pull.
     - The totalAssets will be the same before and after this call.
 

docs/developers/v3/yield_accrual.md

@@ -0,0 +1,83 @@
+# Yield Accrual in V3 Strategies
+
+This page describes how yield accrues and is accounted in Yearn V3. Yield can accrue continuously in external protocols, but it is only recognized in accounting when `report()` runs, with `tend()` available for maintenance between reports. For the broader system context, see [V3 Overview](/developers/v3/overview).
+
+## Overview
+
+1. Yield accrues off-chain or in external protocols. This changes the strategy's real holdings but not its recorded accounting.
+2. `strategy.report()` is called by a keeper or management. The strategy harvests, computes a total asset value, and updates internal accounting.
+3. `vault.process_report(strategy)` is called by the vault’s reporting manager. The vault reads the strategy’s ERC-4626 value and realizes gain or loss against its recorded debt, charging fees and locking profits at the vault level.
+
+`tend()` fits between reports as a maintenance hook and does not change PPS or recorded profits until the next `report()`.
+
+## Strategy accounting (Tokenized Strategy)
+
+### `report()`
+
+In `TokenizedStrategy.sol`, `report()`:
+
+- Calls `BaseStrategy.harvestAndReport()` to harvest, reinvest, and return a trusted `totalAssets` snapshot.
+- Compares the new `totalAssets` to the previous value to derive profit or loss.
+- Applies performance fees (and [protocol fee](/developers/v3/protocol_fees) on those fees).
+- Locks profit in shares so PPS doesn’t jump, then unlocks over `profitMaxUnlockTime`.
+- Updates `totalAssets` and `lastReport`.
+
+Profits do not exist in accounting until `report()` is run. Losses can be realized on `report()` or during `withdraw()`/`redeem()`.
+
+Key code references:
+
+- `TokenizedStrategy.sol` → `report()`
+- `BaseStrategy.sol` → `harvestAndReport()`
+
+### `tend()`
+
+In `TokenizedStrategy.sol`, `tend()`:
+
+- Requires a keeper or management role.
+- Calls `BaseStrategy.tendThis(_totalIdle)`, passing the strategy’s current idle balance.
+- Does not change `totalAssets`, PPS, or accounting.
+
+This is meant for actions like harvesting rewards or repositioning that should not yet be realized as profit or loss. A later `report()` finalizes accounting. For implementation details, see the [Strategy Writing Guide](/developers/v3/strategy_writing_guide).
+
+Key code references:
+
+- `TokenizedStrategy.sol` → `tend()`
+- `BaseStrategy.sol` → `tendThis()` and `_tend()`
+
+## Vault accounting (Allocator Vault)
+
+V3 vaults treat strategies as ERC-4626 positions. In `VaultV3.vy`, `process_report(strategy)`:
+
+- Reads the vault’s strategy share balance and uses the strategy’s `convertToAssets()` to compute current position value.
+- Compares that value to the vault’s recorded debt for the strategy to compute gain or loss.
+- Invokes the accountant (if set) to calculate fees or refunds. See [Periphery Contracts](/developers/v3/periphery#accountant) for how the accountant is configured.
+- Locks profit at the vault level using vault shares and `profit_max_unlock_time`.
+- Updates per-strategy accounting (including `last_report`) and vault totals.
+
+This means a strategy’s profit only becomes visible to vault depositors after `process_report()` is called, even if the strategy already reported.
+
+Key code references:
+
+- `VaultV3.vy` → `_process_report()`
+- `VaultV3.vy` → `process_report()`
+
+## Recommended cadence
+
+- Report cadence should align with `profitMaxUnlockTime` (strategy) and `profit_max_unlock_time` (vault) so users see smooth, predictable unlocks.
+- Call order in practice:
+  1. `strategy.report()`
+  2. `vault.process_report(strategy)`
+- Use `tend()` when needed for maintenance that should not immediately affect PPS.
+
+## Notes for strategists
+
+- Only `report()` realizes profit. Losses can be realized on `report()` or during `withdraw()`/`redeem()`. Your `_harvestAndReport()` implementation defines what “realized” means for your strategy.
+- `tend()` is for safety and efficiency, not accounting. Use it for rebalances, reward compounding, or moving idle funds when a full report would be premature. For more guidance, see the [Strategy Writing Guide](/developers/v3/strategy_writing_guide).
+- ERC-4626 conversion accuracy matters because the vault uses `convertToAssets()` to determine gains or losses against debt.
+
+## Implementation checklist
+
+- Implement `_harvestAndReport()` to return a trusted, accurate total asset value.
+- If you use `_tend()`, also implement `_tendTrigger()` and expect no accounting change until report.
+- Ensure keepers call `report()` and `vault.process_report()` on a consistent schedule.
+- Consider how profit locking interacts with your reporting frequency and strategy liquidity.

docs/getting-started/guides/using-yearn-v3.md

@@ -1,6 +1,6 @@
 # Using Yearn's V3 Vaults
 
-So you want to deposit into on of Yearn's V3 Vaults? You are in the right spot. Keep reading for a full walkthrough on how to use them.
+So you want to deposit into one of Yearn's V3 Vaults? You are in the right spot. Keep reading for a full walkthrough on how to use them.
 
 ## Connect your Wallet
 
@@ -14,7 +14,7 @@ There is a big button, anon!
 
 ![image](/img/guides/using-yearn/v3/image2.png)
 
-Our V3 vaults are currently on Ethereum, Arbitrum, and Polygon with more to come. Click on this button to select the network you would like to interact with:
+Our V3 vaults are currently on Ethereum, Arbitrum, Polygon, Base, and Katana, with more chains to come. Click on this button to select the network you would like to interact with:
 
 ![image](/img/guides/using-yearn/v3/image3.png)
 
@@ -57,12 +57,4 @@ When you're ready to withdraw:
 
 ## Tools to track your funds
 
-If you would like to see how your USD balance changes while your assets are in a vault, connect your wallet to [Zapper.xyz](https://zapper.xyz) or a similar portfolio-tracking product. This is also the easiest way to tell how much profit the vault has made for you.
-
-Your balance WILL NOT increase continuously. Profit will be distributed to your share of the vault when the harvest() function is called, which happens on a fluctuating basis.
-
-Community resources to monitor your returns:
-
-- [Zapper](https://zapper.xyz/)
-- [Zerion](https://app.zerion.io/)
-- [DeBank](https://debank.com/)
+If you would like to see how your USD balance changes while your assets are in a vault, connect your wallet to [DeBank](https://debank.com/), [Zerion](https://app.zerion.io/), [Zapper.xyz](https://zapper.xyz), or a similar portfolio-tracking product. This is also the easiest way to tell how much profit the vault has made for you.