STFIL tokens integration guide
This document is intended for developers looking to integrate STFIL's stFIL or wstFIL as a token into their dApp, with a focus on money markets, DEXes and blockchain bridges.
STFIL Protocol
STFIL Protocol is a family of liquid staking protocols across multiple blockchains, with headquarters on Filecoin. Liquid refers to the ability of a user’s stake to become liquid. Upon the user's deposit STFIL Protocol issues stToken, which represents the deposited tokens along with all the rewards & penalties accrued through the deposit's staking. Unlike the staked funds, this stToken is liquid — it can be freely transferred between parties, making it usable across different DeFi applications while still receiving staked rewards. It is paramount to preserve this property when integrating stTokens into any DeFi protocol.
This guide refers to STFIL Protocol on Filecoin (hereinafter referred to as STFIL).
STFIL Protocol Tokens
stTokens: stFIL and wstFIL
For filecoin staked in STFIL, the STFIL Protocol gives users stFIL that is equal to the amount staked. For easier DeFi integrations, stFIL has a non-rebasable value-accruing counterpart called 'wrapped stFIL' (or just wstFIL).
STFIL's ERC-20 compatible stTokens will widely adopted across the Filecoin ecosystem:
The most important on-chain liquidity venues include:
STF
STF is a STFIL governance ERC-20 compliant token. Thus, STF holder can obtain voting rights and dividend rights.
stFIL vs. wstFIL
There are two versions of STFIL's stTokens, namely stFIL and wstFIL. Both are fungible tokens, but they reflect the accrued staking rewards in different ways. stFIL is similar to Aave's a-token which means the stFIL balance increases over time. On the contrary, wstFIL balance is constant, while the token increases in value eventually (denominated in stFIL). At any moment, any amount of stFIL can be converted to wstFIL via a trustless wrapper and vice versa, thus tokens effectively share liquidity.
stFIL
What is stFIL?
stFIL is a a-token complies with ERC-20 standards that represents filecoin staked with STFIL. Unlike staked filecoin, it is liquid and can be transferred, traded, or used in DeFi applications. The total supply of stFIL reflects the amount of filecoin deposited into protocol combined with staking rewards, minus potential validator penalties. stFIL tokens are minted upon filecoin deposit at 1:1 ratio. It is also possible to redeem filecoin by burning stETH at the same 1:1 ratio (It always remains 1:1 ratio).
stFIL is a a-token complies with ERC-20 standards. Normally, the stFIL token balances will increase every second.
Do stFIL rewards compound?
Yes, stFIL rewards do compound.
wstFIL
Due to the rebasing nature of stFIL, the stFIL balance on the holder's address is not constant, it changes daily. Although rebasable tokens/a-tokens are becoming a common thing in DeFi recently, many dApps do not support rebasing. For example, Maker, UniSwap, and SushiSwap are not designed for rebasable tokens. Listing stFIL on these apps can result in holders not receiving their daily staking rewards which effectively defeats the benefits of liquid staking. To integrate with such dApps, there's another form of STFIL stTokens called wstFIL(wrapped staked filecoin).
What is wstFIL?
wstFIL is an ERC20 token that represents the account's share of the stFIL total supply (stFIL token wrapper with static balances). For wstFIL, 1 atto in shares equals to 1 atto in balance. The wstFIL balance can only be changed upon transfers, minting, and burning. wstFIL balance does not rebase, wstFIL's price denominated in stFIL changes instead. At any given time, anyone holding wstFIL can convert any amount of it to stFIL at a fixed rate, and vice versa. The rate is the same for everyone at any given moment. Normally, the rate gets updated once a day, when stFIL undergoes a rebase. The current rate can be obtained by calling wstFIL.stFILPerToken()
Wrap & Unwrap
When wrapping stFIL to wstFIL, the desired amount of stFIL is locked on the wstFIL contract balance, and the wstFIL is minted according to the share bookkeeping formula.
When unwrapping, wstFIL gets burnt and the corresponding amount of stFIL gets unlocked.
Thus, the amount of stFIL unlocked when unwrapping is different from what has been initially wrapped (given a rebase happened between wrapping and unwrapping stFIL).
wstFIL shortcut
Note, that the WstFIL contract includes a shortcut to convert FIL to wstFIL under the hood, which allows you to effectively skip the wrapping step and stake filecoin for wstFIL directly. Keep in mind that when using the shortcut, the staking rate limits still apply.
Rewards accounting
Since wstFIL represents the holder's share in the total amount of STFIL-controlled filecoin, rebases don't affect wstFIL balances but change the wstFIL price denominated in stFIL.
Basic example:
User wraps 1 stFIL and gets 0.9803 wstFIL (1 stFIL = 0.9803 wstFIL)
As the number of stFIL increases, the wstFIL price goes up by 5%
User unwraps 0.9803 wstFIL and gets 1.0499 stFIL (1 stFIL = 0.9337 wstFIL)
STF
What is STF?
STF is a governance token used for the STFIL DAO's voting process (both off-chain and on-chain). The token will widely available in DeFi and CeFi ecosystems.
Governance: Users holding STF tokens can participate in the protocol's governance and decision-making process using their tokens.
Security Module: Users provide security for the protocol by staking STF tokens and receive STF rewards in return.
Incentivizing Staking: Users can obtain STF as rewards based on the amount of FIL staked and the period of staked.
Last updated