Skip to content

Commit

Permalink
feat: add Features tabs(#239)
Browse files Browse the repository at this point in the history
* feat: add feat nav bar

* feat: add cl

"

* feat: fix nav bar

* feat: add eip 1559

* feat: more features

* feat: fix CI

* feat: add proto rev

* feat: add index and TOC

* feat: remove duplciated IBC Hooks

* feat: eip 1559 params fix
  • Loading branch information
mattverse authored Jan 18, 2024
1 parent 34fc64d commit 6e634f1
Show file tree
Hide file tree
Showing 13 changed files with 1,921 additions and 291 deletions.
13 changes: 13 additions & 0 deletions docs/overview/features/_category_.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
{
"position": 6,
"label": "Features",
"collapsible": true,
"collapsed": true,
"className": "red",
"link": {
"title": "Features"
},
"customProps": {
"description": "Listing different endpoints available for different sources for Osmosis"
}
}
Original file line number Diff line number Diff line change
@@ -1,21 +1,8 @@
---
sidebar_position: 3
sidebar_position: 2
---

# Overview

## Index
- [Overview](#Overview)
- [Background](#background)
- [Notable Features](#notable-features)
- [Our Implementation](#our-implementation)
- [Incentives](#Incentive-Creation-and-Querying)
- [Reward Splitting Between Classic and CL pools](#Reward-Splitting-Between-Classic-and-CL-pools)
- [TWAP Integration](#twap-integration)
- [Precision Issues With Price](#precision-issues-with-price)
- [Solution](#solution)
- [Terminology](#terminology)
- [External Sources](#external-sources)
# Concentrated Liquidity
## Background

Concentrated liquidity is a novel Automated Market Maker (AMM) design introduced
Expand Down Expand Up @@ -272,3 +259,6 @@ Note, that the current tick of 155 is defined inside the bucket over a range of

- [Uniswap V3 Whitepaper](https://uniswap.org/whitepaper-v3.pdf)
- [Technical Note on Liquidity Math](https://atiselsts.github.io/pdfs/uniswap-v3-liquidity-math.pdf)

## Repository
For more an in-depth docs and implementation, please visit: https://github.com/osmosis-labs/osmosis/tree/main/x/concentrated-liquidity
42 changes: 42 additions & 0 deletions docs/overview/features/eip-1559.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,42 @@
---
sidebar_position: 3
---

# EIP-1559

## Introduction
The following documentation explains the logic behind the Osmosis EIP-1559 fee market implementation. This implementation is designed to prevent spam attacks on the network by dynamically adjusting transaction fees based on network congestion.

## Base Fee Adjustment

The heart of the EIP-1559 fee market is the adjustment of the base fee. The base fee represents the minimum fee required to include a transaction in a block.

The base fee adjustment is based on the concept of "block space competition." If the network is congested and more users want to send transactions, the base fee increases to allocate block space to the highest bidders. Conversely, if the network is underutilized, the base fee decreases to reduce transaction costs.

The adjustment is calculated using the formula:
```
baseFeeMultiplier = 1 + (gasUsed - targetGas) / targetGas * maxChangeRate
newBaseFee = baseFee * baseFeeMultiplier
```
- gasUsed: The total gas used in a block.
- targetGas: The target gas wanted per block, defined as 75,000,000.
- maxChangeRate: The maximum allowable change rate for the base fee, defined as 1/10.
The calculated baseFeeMultiplier is then used to update the CurBaseFee.

The base fee is constrained by minimum and maximum values defined as MinBaseFee (0.0025) and MaxBaseFee (5), respectively.

## Integration
The current chain base fee can be retrieved from the following end point:
`${LCD_ENDPOINT}/osmosis/txfees/v1beta1/cur_eip_base_fee`

User txs will get priced at `multiplier` * B_t, where B_t is base fee at time of submission, and multiplier is an arbitrary constant that can be set in wallets / dapps.

An example fee calculation can be as the following:
```
low = base_fee * 1.05
average = base_fee * 2
high = base_fee * 3
```

Note that setting a conservative, high multiplier can ensure getting user transactions even throughout high transaction volumes, whilst it can lead to users paying higher transaction fees than needed.

89 changes: 89 additions & 0 deletions docs/overview/features/fee-abstraction.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,89 @@
---
sidebar_position: 4
---

# Fee Abstraction

## Context

The concrete use cases which motivated this module include:

- The desire to use IBC token as transaction fees on any chain instead of having to use native token as fee.
- To fully take advantage of the newly represented Osmosis [``swap router``](https://github.com/osmosis-labs/osmosis/tree/main/cosmwasm/contracts) with the [``ibc-hooks``](https://github.com/osmosis-labs/osmosis/tree/main/x/ibc-hooks) module and the [``async-icq``](https://github.com/strangelove-ventures/async-icq) module.


## Description

Fee abstraction modules enable users on any Cosmos chain with IBC connections to pay fee using ibc token.

Fee-abs implementation:

- Fee-abs module imported to the customer chain.

The implememtation also uses Osmosis swap router and async-icq module which are already deployed on Osmosis testnet.

## Prototype

Fee-abs mechanism in a nutshell:

1. Pulling `twap data` and update exchange rate:

- Periodically pulling `twap data` from osmosis by ibc-ing to `async-icq` module on Osmosis, this `twap data` will update the exchange rate of osmosis to customer chain's native token.

2. Handling txs with ibc-token fee:

- The exchange rate is used to calculate the amount of ibc-token needed for tx fee allowing users to pay ibc-token for tx fee instead of chain's native token.

3. Swap accumulated ibc-token fee:

- The collected ibc-token users use for tx fee is periodically swaped back to customer chain's native token using osmosis.

We'll goes into all the details now:

#### Pulling `twap data` and update exchange rate

For this to work, we first has to set up an ibc channel from `feeabs` to `async-icq`. This channel set-up process can be done by anyone, just like setting up an ibc transfer channel. Once that ibc channel is there, we'll use that channel to ibc-query Twap data. Let's call this the querying channel.

The process of pulling Twap data and update exchange rate :

![Diagram of the process of pulling Twap data and updating exchange rate](https://i.imgur.com/HJ9a26H.png "Diagram of the process of pulling Twap data and updating exchange rate")

Description :
For every `update exchange rate period`, at fee-abs `BeginBlocker()` we submit a `InterchainQueryPacketData` which wrapped `QueryArithmeticTwapToNowRequest` to the querying channel on the customer chain's end. Then relayers will submit `MsgReceivePacket` so that our `QueryTwapPacket` which will be routed to `async-icq` module to be processed. `async-icq` module then unpack `InterchainQueryPacketData` and send query to TWAP module. The correspone response will be wrapped in the ibc acknowledgement. Relayers then submit `MsgAcknowledgement` to the customer chain so that the ibc acknowledgement is routed to fee-abs to be processed. Fee-abs then update exchange rate according to the Twap wrapped in the ibc acknowledgement.

#### Handling txs with ibc-token fee

We modified `MempoolFeeDecorator` so that it can handle ibc-token as fee. If the tx has ibc-token fee, the AnteHandler will first check if that token is allowed (which is setup by Gov) we basically replace the amount of ibc-token with the equivalent native-token amount which is calculated by `exchange rate` * `ibc-token amount`.

We have an account to manage the ibc-token user used to pay for tx fee. The collected ibc-token fee is sent to that account instead of community pool account.

#### Swap accumulated ibc-tokens fee

Fee-abstraction will use osmosis's Cross chain Swap (XCS) feature to do this. We basically ibc transfer to the osmosis crosschain swap contract with custom memo to swap the osmosis fee back to customer chain's native-token and ibc transfer back to the customer chain.

##### How XCS work

###### Reverse With Path-unwinding to get Ibc-token on Osmosis

- Create a ibc transfer message with a specific MEMO to work with ibc [``packet-forward-middleware``](https://github.com/strangelove-ventures/packet-forward-middleware) which is path-unwinding (an ibc feature that allow to automatic define the path and ibc transfer multiple hop follow the defined path)
- Ibc transfer the created packet to get the fee Ibc-token on Osmosis

Ex: When you sent STARS on Hub to Osmosis, you will get Osmosis(Hub(STARS)) which is different with STARS on Osmosis Osmosis(STARS). It will reverse back Osmosis(Hub(STARS)) to Osmosis(STARS):

![Diagram of the process of swapping accumulated ibc-tokens fee](https://i.imgur.com/D1wSrMm.png "Diagram of the process of swapping accumulated ibc-tokens fee")

###### Swap Ibc-token

###### Swap Ibc-token

After reverse the ibc-token, XCS will :

- Swap with the specific pool (which is defined in the transfer packet from Feeabs-chain) to get Feeabs-chain native-token
- Transfer back Feeabs-chain native-token to Feeabs module account (will use to pay fee for other transaction)

![Diagram of the process of swapping accumulated ibc-tokens fee](https://i.imgur.com/YKOK8mr.png "Diagram of the process of swapping accumulated ibc-tokens fee")

Current version of fee-abstraction working with XCSv2

## Repository
For more an in-depth docs and implementation, please visit: https://github.com/osmosis-labs/fee-abstraction
Loading

1 comment on commit 6e634f1

@vercel
Copy link

@vercel vercel bot commented on 6e634f1 Jan 18, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please sign in to comment.