Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update wstETH docs #242

Merged
merged 2 commits into from
Aug 7, 2023
Merged

Update wstETH docs #242

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
815b5d2
Better docs for wsteth
folkyatina Jul 28, 2023
9864d8c
after-review fixes
folkyatina Aug 4, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
57 changes: 38 additions & 19 deletions docs/contracts/wsteth.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,25 +3,44 @@
- [Source Code](https://github.com/lidofinance/lido-dao/blob/master/contracts/0.6.12/WstETH.sol)
- [Deployed Contract](https://etherscan.io/token/0x7f39c581f595b53c5cb19bd0b3f8da6c935e2ca0)

It's an ERC20 token that represents the account's share of the total
supply of stETH tokens. WstETH token's balance only changes on transfers,
unlike StETH that is also changed when oracles report staking rewards and
penalties. It's a "power user" token for DeFi protocols which don't
support rebasable tokens.
## What is wrapped stETH (wstETH)?

The contract is also a trustless wrapper that accepts stETH tokens and mints
wstETH in return. Then the user unwraps, the contract burns user's wstETH
and sends user locked stETH in return.
It's an [ERC-20](https://eips.ethereum.org/EIPS/eip-20) value-accruing token
wrapper for `stETH`. Its balance does not change with each oracle report, but its
value in `stETH` does. Internally, it represents the user's [share](../guides/steth-integration-guide#steth-internals-share-mechanics) of the total
supply of `stETH` tokens.
folkyatina marked this conversation as resolved.
Show resolved Hide resolved

The contract provides the staking shortcut: user can send ETH with regular
transfer and get wstETH in return. The contract will send ETH to Lido submit
method, staking it and wrapping the received stETH.
## Why use wstETH?

`wstETH` is mainly used as a layer of compatibility to integrate `stETH` into other
DeFi protocols, that do not support rebasable tokens, especially bridges to L2s and
other chains, as rebases don't work for bridged assets by default.

## How to use wstETH?

The contract can be used as a trustless wrapper that accepts stETH tokens and mints
folkyatina marked this conversation as resolved.
Show resolved Hide resolved
wstETH in return. When the user unwraps, the contract burns the user's `wstETH`,
and sends the user locked `stETH` in return.

### Staking shortcut
folkyatina marked this conversation as resolved.
Show resolved Hide resolved

The user can send ETH with regular transfer to the address of the contract and
get wstETH in return. The contract will send ETH to Lido submit method,
staking it and wrapping the received stETH seamlessly under the hood.

## Standards
folkyatina marked this conversation as resolved.
Show resolved Hide resolved

Contract implements the following Ethereum standards:

- [ERC-20: Token Standard](https://eips.ethereum.org/EIPS/eip-20)
- [ERC-2612: Permit Extension for ERC-20 Signed Approvals](https://eips.ethereum.org/EIPS/eip-2612)
- [EIP-712: Typed structured data hashing and signing](https://eips.ethereum.org/EIPS/eip-712)

## View Methods

### getWstETHByStETH()

Returns amount of wstETH for a given amount of stETH
Returns amount of `wstETH` for a given amount of `stETH`

```sol
function getWstETHByStETH(uint256 _stETHAmount) returns (uint256)
Expand All @@ -35,7 +54,7 @@ function getWstETHByStETH(uint256 _stETHAmount) returns (uint256)

### getStETHByWstETH()

Returns amount of stETH for a given amount of wstETH
Returns amount of `stETH` for a given amount of `wstETH`

```sol
function getStETHByWstETH(uint256 _wstETHAmount) returns (uint256)
Expand All @@ -49,15 +68,15 @@ function getStETHByWstETH(uint256 _wstETHAmount) returns (uint256)

### stEthPerToken()

Returns the amount of stETH tokens corresponding to one wstETH
Returns the amount of stETH tokens corresponding to one `wstETH`

```sol
function stEthPerToken() returns (uint256)
```

### tokensPerStEth()

Returns the amount of wstETH tokens corresponding to one stETH
Returns the number of `wstETH` tokens corresponding to one `stETH`

```sol
function tokensPerStEth() returns (uint256)
Expand All @@ -67,7 +86,7 @@ function tokensPerStEth() returns (uint256)

### wrap()

Exchanges stETH to wstETH
Exchanges `stETH` to `wstETH`

```sol
function wrap(uint256 _stETHAmount) returns (uint256)
Expand All @@ -94,7 +113,7 @@ Amount of wstETH user receives after wrap

### unwrap()

Exchanges wstETH to stETH
Exchanges wstETH to `stETH`

```sol
function unwrap(uint256 _wstETHAmount) returns (uint256)
Expand All @@ -116,11 +135,11 @@ Requirements:

#### Returns:

Amount of stETH user receives after unwrap
Amount of stETH user receives after unwrapping

### receive()

Shortcut to stake ETH and auto-wrap returned stETH
Shortcut to stake ETH and auto-wrap returned `stETH`

```sol
receive() payable
Expand Down
Loading