create a new page for the Yield Bridge

[0xallan]

Thank you for contributing to our docs!

Please fill out the form below to ensure your doc gets quickly approved and merged.

Description

Adding a new page for the Yield Bridge, a new kind of bridge that allows chain operators to earn yield on the assets locked in the bridge on the parent chain.

Document type

• Gentle introduction
• Quickstart
• How-to
• Concept
• FAQ
• Troubleshooting
• Reference
• Third-party content
• Codebase changes
• Not applicable

Checklist

• I have read the CONTRIBUTE.md guidelines
• My changes follow the style conventions outlined in CONTRIBUTE.md
• I have used sentence-case for titles and headers
• I have used descriptive link text (not "here" or "this")
• I have separated procedural from conceptual content where appropriate
• I have tested my changes locally with yarn start or yarn build
• My code follows the existing code style and conventions
• I have added/updated frontmatter for new documents
• I have checked for broken links
• I have verified that my changes don't break the build
• Third-party docs only: Do you agree to the third-party content policy outlined within CONTRIBUTE.md?
  • Yes
  • Not applicable

Additional Notes

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
arbitrum-docs	Ready	Preview	Aug 7, 2026 12:38pm

[waelsy123]

Deposits never move capital into the sub-vault, and rebalancing is the only operation that does. Withdrawals pull from the sub-vault only to cover a shortfall in the idle balance.

[godzillaba]

Suggested change

**Depositing from the parent chain.** The user calls the gateway router as they would for any bridged token. The gateway pulls the underlying asset from the user, deposits it into that token's `MasterVault`, and holds the shares it receives as escrow. A retryable ticket mints the child chain token to the user. Shares are issued one-for-one with the asset, so the child chain balance matches what the user deposited. The router also exposes a deposit entrypoint that takes a minimum amount to be received on the child chain and reverts if the vault would issue fewer shares than that. This is useful when the vault may be carrying a loss.

**Depositing from the parent chain.** The user calls the gateway router as they would for any bridged token. The gateway pulls the underlying asset from the user, deposits it into that token's `MasterVault`, and holds the shares it receives as escrow. A retryable ticket mints child chain tokens to the user 1 for 1 with `MasterVault` shares. Unless the `MasterVault` has suffered losses, shares are issued one-for-one with the asset, so the child chain balance matches what the user deposited. The router also exposes a deposit entrypoint that takes a minimum amount to be received on the child chain and reverts if the vault would issue fewer shares than that. This is useful when the vault may be carrying a loss, because the exchange rate can change in that situation.

i think my suggested wording isn't very good, but basically wanted to make the fact that L2 token is 1 to 1 with MV shares, and MV shares are usually 1-1 with asset. the slippage tolerance is useful when MV is trading at less than 1 asset, and it suddenly spikes in value before the user lands their deposit