diff --git a/docs/.vuepress/components/Tools.vue b/docs/.vuepress/components/Tools.vue index cdca0714..8bd4d369 100644 --- a/docs/.vuepress/components/Tools.vue +++ b/docs/.vuepress/components/Tools.vue @@ -82,13 +82,6 @@ const coreTools = [ ]; const calculatorsAndDApps = [ - { - title: 'Xeonus and Zen Dragon Tools', - icon: '/images/logo-light.svg', - details: - 'veBAL, Impermanent Loss and Price Impact Calculators - created by Xeonus and Zen Dragon', - link: 'https://balancer.tools/veBAL', - }, { title: 'veBAL Gauge Multivoter', icon: '/images/toolshub/zekraken.jpg', @@ -118,18 +111,18 @@ const calculatorsAndDApps = [ link: 'https://tools.balancer.blue/internalmanager', }, { - title: 'Custom Pool Metadata', + title: 'Stable Swap Simulator', icon: '/images/toolshub/balancer-symbol.svg', details: - 'Tool for owners to be able to add custom metadata to their pools - created by Bleu', - link: 'https://tools.balancer.blue/metadata/', + 'Dashboard to visualize the impact of changes in the Amplification Factor on Balancer Stable-Like Pools - created by Bleu', + link: 'https://tools.balancer.blue/stableswapsimulator', }, { - title: 'Stable Swap Simulator', + title: 'LBP simulator', icon: '/images/toolshub/balancer-symbol.svg', details: - 'Dashboard to visualize the impact of changes in the Amplification Factor on Balancer Stable-Like Pools - created by Bleu', - link: 'https://tools.balancer.blue/stableswapsimulator', + 'Tool created for LBP pool creators, with the goal of facilitating the projection of different scenarios that the pool may follow.', + link: 'https://lbp.balancer.fi/', }, // Add more calculators and dApps as needed ]; @@ -139,7 +132,7 @@ const analyticsSites = [ title: 'DeFilytica Analytics', icon: '/images/toolshub/defilytica_simple.png', details: - 'Protocol, pool and token metrics. Additionally, an in-depth financial dashboard and service-provider analytics board.', + 'Protocol, pool and token metrics. Additionally, an in-depth financial dashboard and service-provider analytics board. V2 only ', link: 'https://balancer.defilytica.com/', }, { diff --git a/docs/.vuepress/public/lbp_modeling_demand_curve.pdf b/docs/.vuepress/public/lbp_modeling_demand_curve.pdf new file mode 100644 index 00000000..2f9428c7 Binary files /dev/null and b/docs/.vuepress/public/lbp_modeling_demand_curve.pdf differ diff --git a/docs/concepts/explore-available-balancer-pools/liquidity-bootstrapping-pool.md b/docs/concepts/explore-available-balancer-pools/liquidity-bootstrapping-pool.md deleted file mode 100644 index 0e2d6c39..00000000 --- a/docs/concepts/explore-available-balancer-pools/liquidity-bootstrapping-pool.md +++ /dev/null @@ -1,81 +0,0 @@ ---- -order: 4 -title: Liquidity Bootstrapping Pool ---- - -# Liquidity Bootstrapping Pools (LBPs) - -## Overview - -Liquidity Bootstrapping Pools (LBPs) are pools that can dynamically change token weighting (e.g 1/99 to 99/1 for TokenA/TokenB). LBPs use [Weighted Math](./weighted-pool/weighted-math.md) with time-dependent weights. The starting and end weights and times are selected by the pool owner. The pool owner is the only address that can add liquidity to the pool, which must be done prior to the start of the sale. Furthermore, the proceeds can only be removed after the end time. - -::: info Create an LBP - -- [Create an LBP with the balancer SDK](https://github.com/balancer/b-sdk/blob/main/examples/createAndInitPool/createAndInitLBPoolV3.ts) -- [Create an LBP with a foundry script](https://github.com/balancer/balancer-v3-foundry-starter/pull/5/files) -- Once the LBP has concluded, the token can be easily migrated to a standard pool on Balancer with this [tool](). - - ::: - -### Mental Model - -You can think of the starting price of your LBP as the ceiling you would want to set for the token sale. This may seem counterintuitive, but since LBPs work differently than other token sales, your starting price should be set much higher than what you believe is the fair price. - -This does not mean you are trying to sell the token above what it is worth. Setting a high starting price allows the changing pool weights of your LBP to make their full impact, lowering the price progressively until market equilibrium is reached. Unlike older token sale models, such as bonding curves, users are disincentivized to buy early and instead benefit from waiting for the price to decrease until it reaches a level they believe is fair. - -## Advantages - -### Sell Pressure - -During a weight shift, the token price of one token experiences sell pressure while the other experiences buy pressure. When this is mixed with modest swap volume, the price approaches the generally agreed-upon market price. - -### Fair Market - -LBPs often start with intentionally high prices. This strongly disincentivizes whales and bots from snatching up much of the pool liquidity at the get-go. When LBPs are used for early-stage tokens, this can help increase how widespread the token distribution is. - -### Starting Capital Can Be Small - -Teams who use LBPs to kickstart the liquidity of a token that has not been well distributed yet can do so with minimal starting capital. For a team running an LBP with their TOKEN and DAI, starting with 10% or 20% DAI, as opposed to 50% DAI ** like they might need on another platform, significantly reduces their starting capital requirements. Shifting from 80/20 TOKEN/DAI ** to 20/80 would look like this: - -![Liquidity Bootstrapping pool weight shifts](/images/pool_LBP.webp) - -and would ultimately result in the team holding far more DAI at the end of their LBP while reducing the (sometimes extreme) price volatility that teams experience when just launching a 50/50 pool. - -### Immediate liquidity - -Once the LBP concludes, immediate access to the funds raised is available. The new token holders can immediately trade their token, providing instant liquidity without lengthy lock-up periods. - -## Pool Settings - -LBPs are highly configurable. Here are the key parameters and settings, as defined in the pool implementation: - -- **Tokens**: LBPs are always two-token pools: the project token (being launched) and the reserve token (e.g., a stablecoin or WETH). -- **Weights**: The pool owner specifies the starting and ending weights for both tokens. These weights change linearly over the sale period. -- **Sale Period**: The pool owner sets the `startTime` and `endTime` (timestamps) for the sale. Swaps are only enabled between these times. -- **Liquidity Provision**: Only the owner can add liquidity, and only before the sale starts. -- **Swaps**: Optionally, the pool can block selling the project token back into the pool (`blockProjectTokenSwapsIn`). -- **Trusted Router**: All pool interactions must go through a trusted router to ensure correct sender reporting and security. - -## Pool migration - -It is possible to either create a standalone LBP or create one that can easily be migrated to a weighted pool after the sale has commended. To use this feature the pool factory offers a `createWithMigration` function. For this additional parameters are required: - -- `bptLockDuration`: The time in seconds the BPT of the created weighted pool is locked before the liquidity can be removed from the created weighted pool. -- `bptPercentageToMigrate`: The percentage of the liquidity to be migrated from the LBP to the created weighted pool. -- `migrationWeightProjectToken`: Defines the weight of the project token in the created weighted pool. -- `migrationWeightReserveToken`: Defines the weight of the reserve token in the created weighted pool. - -The migration happens via the [`LBPMigrationRouter`](https://github.com/balancer/balancer-deployments/tree/master/v3/tasks/20251219-v3-liquidity-bootstrapping-pool-v3). - - -**Technical Parameters (from the implementation):** - -- `projectToken` / `reserveToken`: ERC20 addresses for the tokens. -- `projectTokenStartWeight` / `reserveTokenStartWeight`: Initial weights (scaled). -- `projectTokenEndWeight` / `reserveTokenEndWeight`: Final weights (scaled). -- `startTime` / `endTime`: UNIX timestamps for the sale window. -- `blockProjectTokenSwapsIn`: Boolean to restrict project token sales. -- `poolCreator`: The account accrueing [pool creator fees](../core-concepts/pool-creator-fee.md) -- Only two tokens are allowed per pool. - ---- diff --git a/docs/concepts/explore-available-balancer-pools/liquidity-bootstrapping-pool/.order b/docs/concepts/explore-available-balancer-pools/liquidity-bootstrapping-pool/.order new file mode 100644 index 00000000..56a6051c --- /dev/null +++ b/docs/concepts/explore-available-balancer-pools/liquidity-bootstrapping-pool/.order @@ -0,0 +1 @@ +1 \ No newline at end of file diff --git a/docs/concepts/explore-available-balancer-pools/liquidity-bootstrapping-pool/fixed-price-lbp.md b/docs/concepts/explore-available-balancer-pools/liquidity-bootstrapping-pool/fixed-price-lbp.md new file mode 100644 index 00000000..bfadfa46 --- /dev/null +++ b/docs/concepts/explore-available-balancer-pools/liquidity-bootstrapping-pool/fixed-price-lbp.md @@ -0,0 +1,28 @@ +--- +order: 4 +title: Fixed Price LBP +--- + +# Fixed Price LBP + +A **Fixed Price LBP** is a Liquidity Bootstrapping Pool that keeps a **constant exchange rate** between the project token and the reserve token for the whole sale. Unlike standard LBPs, there is no scheduled weights changes. + +## When to use it? + +Use a Fixed Price LBP when you want a **constant-rate token sale**: one project token always costs the same amount of reserve token (1 TOKEN = 10 USDC). Use a **weight-shifting LBP** when you want price discovery (check [Token Launches](./token-launches.md)). + +## How it works? + +- **Constant price:** The pool uses a fixed rate (e.g. `projectTokenRate`). Swaps are simple: reserve in → project out at that rate (or the reverse, depending on configuration). +- **Invariant:** The pool uses a constant-sum style invariant: `projectBalance * projectTokenRate + reserveBalance`, i.e. total value in terms of the reserve token. No weighted math or time-dependent weights. +- **Buy-only (one-way):** Fixed Price LBPs are configured so that only **buying** the project token with the reserve token is allowed. Selling the project token back into the pool is disabled. +- **Seedless:** Because the sale is one-way, the pool is initialized with **project tokens only**. No reserve tokens are required up front; buyers supply the reserve token when they swap. + +## Summary + +| Aspect | Weight-shifting LBP | Fixed Price LBP | +| :----------------------------- | :----------------------------------------------- | :---------------------------- | +| **Price** | Changes over time (weight schedule) | Constant (fixed rate) | +| **Use case** | Price discovery (launches, divestment, buybacks) | Constant-rate sales | +| **Initial liquidity** | Project + reserve (or seedless for some configs) | Project token only (seedless) | +| **Selling project token back** | Configurable | Disabled (buy-only) | diff --git a/docs/concepts/explore-available-balancer-pools/liquidity-bootstrapping-pool/liquidity-bootstrapping-pool.md b/docs/concepts/explore-available-balancer-pools/liquidity-bootstrapping-pool/liquidity-bootstrapping-pool.md new file mode 100644 index 00000000..5be25603 --- /dev/null +++ b/docs/concepts/explore-available-balancer-pools/liquidity-bootstrapping-pool/liquidity-bootstrapping-pool.md @@ -0,0 +1,81 @@ +--- +order: 0 +title: Liquidity Bootstrapping Pool +--- + +# Liquidity Bootstrapping Pools (LBPs) + +## Overview + +Balancer offers two LBP variants: + +- **Weight Shifting LBPs**: Pools that change token weighting over time (e.g. 90/10 → 10/80 project/reserve token). They use Weighted Math with time-dependent weights for price discovery. +- **[Fixed Price LBP](./fixed-price-lbp.md)**: Pools that keep a constant exchange rate for the whole sale (no weight schedule). Used for constant-rate token sales; buy-only and seedless by default. + +The pool owner is the only address that can add liquidity to the pool, which must be done prior to the start of the sale. Furthermore, the proceeds can only be removed after the end time. + +## Use Cases (weight-shifting LBPs) + +The following use cases rely on **weight-shifting** LBPs (scheduled weights changes). For constant-rate sales, see [Fixed Price LBP](./fixed-price-lbp.md). + +### 1. [Token Launches](./token-launches.md) + +**Objective:** Fair initial token distribution. + +The standard LBP configuration supports price discovery for new tokens via a continuous Dutch-auction-style mechanism. The pool starts with a high project-token weight (e.g., 90% project token / 10% reserve) and gradually shifts over time to a lower project-token weight (e.g., 20% / 80%). + +This scheduled reweighting creates controlled downward price pressure, helping distribute tokens more broadly while reducing incentives for bot sniping and whale concentration. Buyers can enter when the price reaches a level they consider fair, rather than rushing into a priority-fee bidding race at launch. + +### 2. [Treasury Diversification](./treasury-diversification.md) + +**Objective:** Position entry and exit with minimal market impact. + +For DAOs and treasuries managing significant capital, LBPs can be used to enter or exit positions over time via a scheduled weight shift. This allows treasuries to: + +- **Divest:** Sell large positions with reduced market impact. +- **Invest:** Accumulate positions in target tokens with reduced market impact. + +### 3. [Token Buybacks](./token-buybacks.md) + +**Objective:** Efficient protocol token accumulation. + +An LBP configured for accumulation inverts the weight logic to create upward price pressure. By starting with high reserve token weight (90% WETH / 10% project token) and shifting toward the project token (10% / 90%), the pool functions as an automated, rising limit order. + +## Pool Settings + +LBPs are highly configurable. Here are the key parameters and settings, as defined in the pool implementation: + +- **Tokens**: LBPs are always two-token pools: the project token (being launched) and the reserve token (e.g., a stablecoin or WETH). +- **Weights**: The pool owner specifies the starting and ending weights for both tokens. These weights change linearly over time. +- **Period**: The pool owner sets the `startTime` and `endTime` (timestamps) for the LBP. Swaps are only enabled between these times. +- **Swaps**: Optionally, the pool can block selling the project token back into the pool (`blockProjectTokenSwapsIn`). This is typically enabled for token launches to prevent manipulation, but disabled for token buybacks where sellers must deposit the project token into the pool. +- **Trusted Router**: All pool interactions must go through a trusted router to ensure correct sender reporting and security. + +## Pool Migration + +It is possible to either create a standalone LBP or create one that can easily be migrated to a weighted pool after the operation has concluded. To use this feature the pool factory offers a `createWithMigration` function. For this additional parameters are required: + +- `bptLockDuration`: The time in seconds the BPT of the created weighted pool is locked before the liquidity can be removed from the created weighted pool. +- `bptPercentageToMigrate`: The percentage of the liquidity to be migrated from the LBP to the created weighted pool. +- `migrationWeightProjectToken`: Defines the weight of the project token in the created weighted pool. +- `migrationWeightReserveToken`: Defines the weight of the reserve token in the created weighted pool. + +The migration happens via the [`LBPMigrationRouter`](https://github.com/balancer/balancer-deployments/tree/master/v3/tasks/20251219-v3-liquidity-bootstrapping-pool-v3). + +**Technical Parameters (from the implementation):** + +- `projectToken` / `reserveToken`: ERC20 addresses for the tokens. +- `projectTokenStartWeight` / `reserveTokenStartWeight`: Initial weights (scaled). +- `projectTokenEndWeight` / `reserveTokenEndWeight`: Final weights (scaled). +- `startTime` / `endTime`: UNIX timestamps for the sale window. +- `blockProjectTokenSwapsIn`: Boolean to restrict project token sales. +- `poolCreator`: The account accruing [pool creator fees](../core-concepts/pool-creator-fee.md) +- Only two tokens are allowed per pool. + +::: tip + +**Primary Use Case:** This feature is most commonly used for **Token Launches**, where the LBP concludes with a successful distribution and the project wishes to establish permanent liquidity. By migrating to a reCLAMM or Weighted pool, the project token becomes immediately tradable on Balancer. + +::: + +--- diff --git a/docs/concepts/explore-available-balancer-pools/liquidity-bootstrapping-pool/token-buybacks.md b/docs/concepts/explore-available-balancer-pools/liquidity-bootstrapping-pool/token-buybacks.md new file mode 100644 index 00000000..898c5f78 --- /dev/null +++ b/docs/concepts/explore-available-balancer-pools/liquidity-bootstrapping-pool/token-buybacks.md @@ -0,0 +1,32 @@ +--- +order: 3 +title: Token Buybacks +--- + +# Token Buybacks + +The same LBP mechanism can be used to support **accumulation** - buying the project token. + +## Mental Model + +For DAOs and treasuries, buying back a large amount of a token can be challenging - **market buys** can create abrupt price impact. An LBP buyback configuration approaches this differently: it uses a scheduled weight shift to create a rising bid, and lets arbitrage keep the pool price aligned with external markets. + +## Configuration + +### 1. Token Setup + +- **Reserve token:** The asset the Treasury wishes to spend (e.g., USDC, WETH). +- **Project token:** The asset the Treasury wishes to acquire. + +### 2. Weight Schedule + +The weight curve should start with the reserve token dominant. + +| Parameter | Example value | Reason | +| :---------------- | :------------------------------------ | :-------------------------------- | +| **Start weights** | 90% reserve token / 10% project token | Keeps the initial bid low. | +| **End weights** | 30% reserve token / 70% project token | Allows the bid to rise over time. | + +### 3. Swap Permissions + +Ensure that `blockProjectTokenSwapsIn` is set to `false`. The mechanism relies on external actors swapping the project token _in_ to the pool to extract the reserve token. diff --git a/docs/concepts/explore-available-balancer-pools/liquidity-bootstrapping-pool/token-launches.md b/docs/concepts/explore-available-balancer-pools/liquidity-bootstrapping-pool/token-launches.md new file mode 100644 index 00000000..34fa3de3 --- /dev/null +++ b/docs/concepts/explore-available-balancer-pools/liquidity-bootstrapping-pool/token-launches.md @@ -0,0 +1,54 @@ +--- +order: 1 +title: Token Launches +--- + +# Token Launches + +The Liquidity Bootstrapping Pool (LBP) is the standard primitive for initial token distribution. The LBP utilizes time-dependent weights to facilitate fair price discovery and capital efficiency. + +::: tip New on Balancer v3: Seedless LBPs +Token launch LBPs can be configured as **seedless**, meaning they require **no initial liquidity in the reserve token**. +::: + +### Mental Model + +You can think of the starting price of your LBP as the ceiling you would want to set for the token sale. This may seem counterintuitive, but since LBPs work differently than other token sales, your starting price should be set much higher than what you believe is the fair price. + +This does not mean you are trying to sell the token above what it is worth. Setting a high starting price allows the changing pool weights of your LBP to make their full impact, lowering the price progressively until market equilibrium is reached. Unlike older token sale models, such as bonding curves, users are disincentivized to buy early and instead benefit from waiting for the price to decrease until it reaches a level they believe is fair. + +## Advantages + +### Capital Efficiency + +LBPs can be configured as **seedless**, meaning they require **no initial liquidity in the reserve token**. + +### Fair Market Price + +LBPs often start with intentionally high prices. This strongly disincentivizes whales and bots from snatching up much of the pool liquidity at the get-go. When LBPs are used for early-stage tokens, this can help increase how widespread the token distribution is. + +### Immediate Liquidity + +Once the LBP concludes, immediate access to the funds raised is available. The new token holders can immediately trade their token, providing instant liquidity without lengthy lock-up periods. + +### Sell Pressure + +During a weight shift, the token price of one token experiences sell pressure while the other experiences buy pressure. When this is mixed with modest swap volume, the price approaches the generally agreed-upon market price. + +## Configuration + +Token launches using LBPs rely on a scheduled **weight shift**. + +### Duration + +Token launches are typically run over **days** (not weeks or months). A common choice is **48 to 72 hours** (2 to 3 days), which gives participants time to enter without concentrating all activity into a short window. + +### Weights + +To create the necessary "price ceiling," the **project token** should start with a dominant weight and decrease over time. In practice, avoid weight schedules that go all the way to the extremes (close to 100/0 or 0/100), as pricing becomes highly non-linear near the ends of the range. + +## Liquidity Migration + +A successful LBP concludes with the **project token** widely distributed and the **reserve token** accumulated in the pool. To transition to a permanent trading venue, use the `createWithMigration` function on the factory. + +This allows the migration of liquidity from the LBP to a **concentrated** or **weighted** pool upon conclusion. diff --git a/docs/concepts/explore-available-balancer-pools/liquidity-bootstrapping-pool/treasury-diversification.md b/docs/concepts/explore-available-balancer-pools/liquidity-bootstrapping-pool/treasury-diversification.md new file mode 100644 index 00000000..7f6c7b4f --- /dev/null +++ b/docs/concepts/explore-available-balancer-pools/liquidity-bootstrapping-pool/treasury-diversification.md @@ -0,0 +1,48 @@ +--- +order: 3 +title: Treasury Diversification +--- + +# Treasury Diversification + +LBPs can help treasuries and DAOs enter or exit large positions with reduced market impact. + +::: tip Balancer V3: Boosted Pools +In Balancer V3, one side of an LBP can be a boosted token (e.g., a yield-bearing stablecoin), so idle balances don’t have to sit unproductive during a long-running operation. +::: + +### Mental Model + +LBPs can be used by treasuries to enter (invest) or exit (divest) positions over time, using a scheduled weight shift rather than a single large swap. Arbitrage keeps the LBP internal price aligned with external markets as the sale progresses. + +## Strategic Divestment (Selling) + +Divestment involves selling a large quantity of an asset (e.g., a grant received in an illiquid token, or diversifying treasury holdings) into a more liquid asset like USDC or ETH. Unlike a **Token Launch** (which typically runs over days), a **Strategic Divestment** prioritizes stability and value retention over longer horizons. + +## Strategic Investment (Buying) + +While token buybacks focus on retiring supply, a **Strategic Investment** allows treasuries to acquire large stakes in _other_ protocols (e.g., a DAO rotating stablecoins into another governance token or ETH) without triggering a parabolic price response. These operations are often run over weeks or months, rather than days. + +## Case Study: The Gitcoin Akita Divestment + +The viability of using LBPs for institutional-scale divestment was demonstrated by the **Gitcoin DAO**. + +**Challenge:** + +In 2021, Vitalik Buterin donated approximately 49 trillion AKITA tokens (valued at ~$5 million) to Gitcoin. The on-chain market depth was insufficient to absorb this liquidity; a direct sale would have resulted in roughly 99% slippage and a collapse of the token's community value. + +**Solution:** + +Instead of an atomic sell-off, the DAO deployed a LBP with the following parameters: + +- **Duration:** 1 Year (slow decay). +- **Weight Shift:** 90% AKITA / 10% WETH $\to$ 10% AKITA / 90% WETH. + +**Results:** + +Over the 12-month period, the mechanism successfully converted the illiquid asset into WETH. + +| Metric | Result | +| :--------------------- | :------------ | +| **Total Funds Raised** | $4.48 Million | +| **Trading Volume** | $22.6 Million | diff --git a/docs/integration-guides/README.md b/docs/integration-guides/README.md index e84f710a..995a76fb 100644 --- a/docs/integration-guides/README.md +++ b/docs/integration-guides/README.md @@ -29,6 +29,11 @@ features: iconDark: /images/build-dark.svg details: How to integrate with Balancer v3 liquidity link: /integration-guides/aggregators/introduction.md + - title: LBP Simulator + icon: /images/build.svg + iconDark: /images/build-dark.svg + details: What is the LBP simulator and should you use it + link: /integration-guides/lbp-simulator/overview.md --- # Integration Guides diff --git a/docs/integration-guides/lbp-simulator/.order b/docs/integration-guides/lbp-simulator/.order new file mode 100644 index 00000000..62f94575 --- /dev/null +++ b/docs/integration-guides/lbp-simulator/.order @@ -0,0 +1 @@ +6 \ No newline at end of file diff --git a/docs/integration-guides/lbp-simulator/overview.md b/docs/integration-guides/lbp-simulator/overview.md new file mode 100644 index 00000000..33333a19 --- /dev/null +++ b/docs/integration-guides/lbp-simulator/overview.md @@ -0,0 +1,45 @@ +--- +order: 0 +title: Overview + +features: + - title: How to use the simulator + icon: /images/build.svg + iconDark: /images/build-dark.svg + details: Walkthrough a quick guide of the simulator usage. + link: /integration-guides/lbp-simulator/user-guide.md + +--- + +# LBP Simulator + +## What is the simulator? +The LBP Simulator is an interactive, client-side tool for modeling a Liquidity Bootstrapping Pool (LBP). It lets you configure a launch/divestment/buyback setup and watch how price, weights, and demand dynamics evolve over time. The goal is to make LBP mechanics more intuitive and to help teams explore tradeoffs before going on-chain. + +## What it can do +- Configure core LBP parameters (token name/symbol, supply, percentage for sale, start and end weights, duration, fees, initial balances). +- Model demand and sell pressure curves to see how different market behaviors affect the price path. +- Run the simulation with play/pause controls and adjustable speed. +- Visualize outcomes across multiple charts: + - Price over time + - Sales / swaps + - Demand curve + - Weight changes +- Execute simulated actions with a wallet-style flow: + - Instant swaps + - Limit orders + - TWAP (time‑weighted average price) orders + +## How it works (high-level) +- The simulator computes price and pool balances step‑by‑step using LBP math. +- A client-side store (Zustand) holds configuration, state, and user actions. +- Charts and stats are derived from the simulation state and update as inputs change. + + +## Intended use +- Explore LBP configuration strategies. +- Compare different demand/sell pressure assumptions. +- Communicate launch mechanics with a clear, visual narrative. + +## User guide +
\ No newline at end of file diff --git a/docs/integration-guides/lbp-simulator/user-guide.md b/docs/integration-guides/lbp-simulator/user-guide.md new file mode 100644 index 00000000..893e6429 --- /dev/null +++ b/docs/integration-guides/lbp-simulator/user-guide.md @@ -0,0 +1,103 @@ +--- +order: 1 +title: User guide +--- + +# LBP Simulator User Guide + +## Overview +The LBP Simulator lets you configure a Liquidity Bootstrapping Pool (LBP), model buy and sell pressure, and watch how prices, weights, and liquidity evolve over time. It also includes a simulated trading panel for swaps, limit orders, and TWAP. + +## Getting Started +1. Open the simulator page. +2. Click `Configure your LBP` or use the keyboard shortcut kbd `⌘ + b` to open the configuration panel. +3. Set your parameters, then press `Play` to run the simulation. +4. Use the chart tabs and stats cards to read results. + +## Core Configuration +All core settings live in the `Configure your LBP` panel. + +**Timeline** +- `Duration`: Total campaign length in days. This controls how long the LBP runs and how quickly weights shift. +- `Play/Pause`: Starts or stops the simulation clock. +- `Speed`: Changes how fast the simulation advances (`1x`, `5x`, `10x`). +- `Buy & sell` / `Buy only`: Toggles whether sell pressure is included. `Buy only` disables selling pressure by setting it to zero. + +**Tokenomics** +- `Total Supply`: Total token supply used to compute valuation metrics. +- `% for Sale`: Share of total supply sold through the LBP. This drives the `Tokens for sale` amount. +- `Initial Liquidity (Collateral token)`: Starting collateral balance in the pool (USDC/USDT/WETH). This anchors the starting price. + +**Weights** +- `Start (Token / Collateral)`: Initial pool weights. Higher token weight means a higher starting price. +- `End (Token / Collateral)`: Final pool weights at the end of the LBP. +- `Collateral Token`: Selects the collateral asset (`USDC`, `USDT`, `WETH`). +- `Swap Fee`: Fee charged on swaps (1%–5%). + +## Buy Pressure Model +Open `Model the buy pressure` to configure market demand assumptions. + +- `Preset`: `Bullish` (steadier/higher buying) or `Bearish` (lighter early, ramps later). +- `Magnitude`: Sets the base scale of cumulative buy volume. +- `Multiplier`: Scales the curve up or down (e.g. 0.5x, 2x). + +This model affects how much simulated buy volume is applied over time. + +To understand more about the curve modeling, read the article that discusses the study conducted to determine the purchase and sale curves modeled in the app. + + Modeling a demand pressure curve article + + + +## Sell Pressure Model +Open `Model the sell pressure` to configure sell behavior. This is only active when `Buy & sell` is selected. + +- `Loyal community` + - `Total sold share of community tokens (%)`: Approximate fraction of community tokens sold over the whole campaign. + - `Concentration at start & end (%)`: How much of the sell activity happens early and late vs. evenly distributed. +- `Greedy community` + - `Profit spread above cost basis (%)`: Sell trigger threshold above average entry price. + - `Portion of holdings sold on trigger (%)`: Portion sold each time the trigger is hit. + +## Trading Panel (Simulated) +The right-side panel lets you simulate actions using a wallet-style flow. + +**Swap** +- Buy or sell the token instantly at the current simulated price. +- Use `Max` to spend your full balance. + +**Limit** +- Set a target price and a maximum spend. +- When the simulated price reaches the target, the order executes. + +**TWAP** +- Split a total amount into multiple parts over a time period. +- The simulator executes the parts across the chosen duration. + +All trades are simulated and do not use real funds. + +## Results and Charts +Use the chart tabs to explore outcomes. + +- `Price over time`: Spot price evolution during the LBP. When paused, dotted paths show potential price scenarios. +- `Sales`: Displays simulated swap activity. +- `Demand curve`: Shows buy and sell pressure over time (net pressure included). +- `Weights`: Shows how token and collateral weights shift through the sale. + +## Key Metrics (Stats Cards) +The header and stat cards summarize current results. + +- `Tokens for sale`: Total tokens allocated to the LBP from `% for Sale`. +- `Implied Market Cap`: Current price × tokens for sale. +- `Starting price`: Initial spot price. +- `Current price`: Current spot price. +- `FDV`: Fully diluted valuation (current price × total supply). +- `TVL`: Total value locked in the pool. +- `Total Raised`: Net collateral accumulated in the pool. +- `Total fees`: Approximate fees collected based on swap fee. +- `Time remaining`: Remaining time in the simulation. + +## Tips +- Use a high start token weight and low end token weight to mimic a classic LBP price decay. +- Increase initial collateral or reduce `% for Sale` to raise the starting price. +- Compare `Bullish` vs `Bearish` buy pressure to see how sensitive pricing is to demand.