Bonding Curve
This Bonding Curve page on CoinMaker enables you to set up and generate a custom bonding curve for a token on the AO network.
Last updated
This Bonding Curve page on CoinMaker enables you to set up and generate a custom bonding curve for a token on the AO network.
Last updated
It provides a visual interface for adjusting parameters like market cap, supply, and fees. The generated bonding curve is also capable of automated liquidity migration to the Botega DEX once a certain market cap target is reached. This document outlines how the page works, how to configure your curve, and how the generated Lua code can be used.
A bonding curve is a mathematical pricing tool where the token’s price is defined as a function of supply. In this particular implementation, we use a power function:
where:
s
is the current circulating supply of your token,
m
and n
are constants derived from your chosen Reserve Ratio (RR) and the target supply/market cap configuration.
This page helps you create a bonding curve process on AO which acts as a distribution mechanism for your token of choice, once it is initialized by receiving that token's supply.
Users will be able to buy and sell the issued token by using the bonding curve as a counterparty. The default quote token for these trades should be a base high liquidity asset like wrapped AR, AO or a Stablecoin. In our example we are using qAR. TokenId:
qAR: NG-0lVX882MG5nhARrSzyprEK6ejonHpdUmaaMPsHE8 wAR: xU9zFkq3X2ZQ6olwNVvr1vUWIjc3kXTWr7xKQD6dh10
The bonding curve is configured with a target, meaning that once a certain market cap / supply is reached, it stops acting as a trading counterparty. Instead, it migrates liquidity to Botega, while pairing the accumulated wAR
reserve with an equivalent amount of the curve token that was not yet issued.
In order for this page to generate lua code for your bonding curve, you can:
Configure the bonding curve parameters (target supply, target market cap, reserve ratio, etc.).
Preview how the price changes as the token supply grows.
Once the code is generated you are free to extend or change it according to your needs before loading it into a new AO process.
You can customize the following inputs through the interface:
Target Market Cap: The total market cap (in qAR
) at which the bonding curve will migrate to Botega.
Target Supply: The total number of tokens (xCOIN
, representing your custom token) that you want distributed by the time you reach the target.
Reserve Ratio (RR): A few options in the interval [0.15
.. 0.5
].
Lower RR: Steeper price increases after initial supply. More volatility and higher potential upside for early buyers.
Higher RR: Smoother, more gradual price curve. Less volatility but potentially lower upside.
Transaction Fee (in %): A percentage fee imposed on each buy or sell, collected in qAR
.
Developer Account: The AO account to which all fees are transferred, as well as unburned LP tokens after the Botega migration.
Token to be Distributed (Process ID): The token you want to distribute via this bonding curve (referred to as xCOIN
in the UI, but you can provide any AO process ID and matching custom ticker).
Token Ticker and Denomination: Your custom token ticker and the denomination. The default of 18
is recommended
LP Tokens Burn Ratio: Upon migrating liquidity to Botega, the AMM returns LP tokens. A certain percentage can be burned, with the remainder transferred to your developer account.
From these inputs, the UI calculates:
Target Liquidity (qAR): The total qAR
to be accumulated by the curve once the target is reached.
Target Price (in qAR): The spot price of one unit of your token at the target supply and market cap.
These values are automatically updated and displayed in the form.
Curve exponent (n): The exponent of the power function that the curve is based on.
The curve exponent n
is not displayed in the UI, but set in the bonding curve code behind the scenes, based on RR
Scaling constant (m): The scaling constant of the power function that the curve is based on.
The scaling constant m
is also not displayed in the UI, but set in the bonding curve code behind the scenes, based on the relationship between target price and target supply.
RR
is defined as the ratio between curve reserve balance (accumulated liquidity) and market cap (distributed value, expressed in the currency of the accumulated liquidity). It represents an invariant of the bonding curve.
With the bonding curve being based on the power function
We chose to make RR
adjustable in the UI, and derive n
from there, due to the expressive nature of RR
: it defines the curve shape and moves within the interval [0,1]
. In our particular set of limitations, we restrict it even more, so that RR
is in the interval [0.15, 0.5]
.
By tweaking RR
instead of n
, a curve builder can better grasp the impact of the configuration on the curve mechanism.
Deriving n
from RR
The handy relationship that expresses n
based on RR
can be obtained starting with the definition for RR
and by expressing everything (accumulated liquidity and market cap) in terms of the supply at any particular moment.
The accumulated liquidity is in direct relation to the distributed supply, due to the curve formula. If we integrate the curve formula over the interval from 0
to a given supply s
, we obtain the required liquidity in order to get to s
.
The Preview section plots a graph of the token price against the supply according to the chosen power function. Two notable points are annotated:
First Buy: Illustrates an example of purchasing 1 qAR
worth of tokens (minus fees) from the curve at the earliest supply.
Target: The configured supply (and corresponding price) at which the curve will migrate to Botega.
In addition, the Bonding Curve Life Cycle is broken down into three stages:
Configure & Deploy
Active Buy & Sell Phase
Liquidity Migration to Botega DEX
Once the target is reached, all accumulated reserve (qAR
) is paired with any remaining undistributed tokens to form liquidity on Botega.
Each form field in the Create Bonding Curve Form corresponds to your bonding curve’s configuration.
Target Market Cap (qAR)
Target Supply (xCOIN)
Reserve Ratio (RR)
Transaction Fees (%)
Curve Token Process (the AO process ID of your custom token)
Curve Token Ticker (a short uppercase identifier, e.g. MYT
)
Curve Token Denomination (default and recommended: 18)
Developer Account (your AO account ID)
LP Tokens Burn Ratio (%)
Many fields have tooltips that appear as question-mark icons, providing deeper explanations and hints for best practices.
After finalizing your settings, click Generate Code to produce a Lua script that can be deployed on the AO platform. The code:
Exposes a minimal set of message handlers for buying and selling tokens, as well as Info
for querying the configuration and state of your bonding curve.
Manages an internal state of how many tokens have been issued, how many remain for distribution, and how much wAR has been accumulated.
Automatically triggers liquidity migration to Botega DEX when the target is reached.
You can copy the generated Lua code and load it into a new AO process. In the UI, the code is shown in a syntax-highlighted window with a Copy button.
You can of course extend and refine the bonding curve functionality. The code is commented on multiple levels, giving you guidance in understanding how it works and why it is built like this.
⚠️ The code is tested to work with all configurations allowed by the UI. If you want to use other values, e.g. a reserve ratio RR > 0.5
or a target supply > 1 Million
, make sure that you understand the implications regarding the integer arithmetic required for these
Create or Identify Your Token
Before using this bonding curve, you must have a token process (with sufficient total supply) on AO.
The token should generally use 18 decimal places to ensure reliable calculations.
📝 Recommended workflow:
create a new token process and mint 1 Billion tokens (1,000,000,000 * 10^18)
transfer all tokens to the bonding curve in the initialization step (see handlers)
This will ensure the required supply for the complete bonding curve life cycle, regardless of your curve configuration, as long as you stay in the ranges available in the configuration UI. All excess (unissued) tokens after the Botega migration will be burned by the curve
Deploy the Lua Code on AO
Use the generated boilerplate script.
Load it into a new process via the aos
CLI or another deployment method of your choice.
Confirm the successful deployment with a dry-run on the Info
handler
Send Your Token to the Bonding Curve
The bonding curve expects to be initialized by receiving all the tokens it will ever distribute. Remember to set the ["X-Action"] = "Initialize"
tag when you make the transfer
Confirm the successful initialization with a dry-run on the Info
handler: check that ["Is-Initialized"] == "true"
Buying: Users send AR
(the reserve token) to the bonding curve process with the X-Action
= "Curve-Buy"
.
The bonding curve deducts fees, calculates how many tokens to issue based on its power function, and transfers tokens back to the buyer.
Selling: Users send your distributed token back to the bonding curve with X-Action
= "Curve-Sell"
.
The curve calculates how much AR
to return to the seller, deducts fees, and finalizes the transaction.
Once the Target Market Cap is reached (i.e., the curve has accumulated the target amount of AR
), the code sets IsMigrating = true
and triggers migration.
The bonding curve automatically creates a Botega AMM and provides liquidity:
All AR
in the curve’s reserve is paired with an appropriate amount of undistributed tokens.
LP tokens are returned to the curve, and a portion (per your configuration) is burned (LP_Tokens_Burn_Ratio
).
The remainder of the LP tokens is sent to your developer account.
⚠️ Please verify that you are using the latest Botega AMM factory process which can be found here (❗️ select "Production" from the radio button)
Consistent Pricing on Migration
The procedure for liquidity migration ensures that the initial marginal price of the AMM is the same as the price of the curve at the moment of migration (Target-Curve-Price
in the Info
response).
In this context, the marginal price of the AMM is agnostic of denominations. It simply divides the AMM reserve of qAR
by the reserve of xCOIN
.
The curve price (Curve-Price
, Target-Curve-Price
in the Info
response) is also denomination agnostic, and it includes a scaling of 10 ^ 18
for precision.
Example
A Curve-Price
of 1,000,000
indicates that:
One unit of xCOIN
has a marginal value of 1,000,000 × 10^{-18}
units of qAR
.
Equivalently, one unit of xCOIN
has a marginal value of 10^{-12}
units of qAR
.
This implies that a minimum of 10^{12}
units of xCOIN
is required to obtain one unit of qAR
.
In the context of an exchange, it is essential to account for token denominations:
For xCOIN
with a denomination of 18
, one xCOIN
corresponds to 10^{18}
units.
For qAR
with a denomination of 12
, one qAR
corresponds to 10^{12}
units.
Given these denominations, 10^{12}
units of xCOIN
equates to one unit of qAR
.
This equivalence can be further expressed as:
10^{-6} xCOIN
corresponds to 10^{-18} qAR
.
Therefore, 1 xCOIN
is equivalent to 10^{-12} qAR
.
Alternatively, 1 xCOIN
is equal to 0.000000000001 qAR
.
Because AO’s Lua environment handles large integers via .bint
, this bonding curve uses integer-only math to maintain precision for operations such as:
where:
cost
is how much qAR
needs to be paid in order to have a supply of s
distributed
price
is the continuous price after a supply of s
has been distributed
Floating-point errors are minimized by converting values into “bints” with a suitably large exponent before exponentiation or division.
To invert the power function (e.g., finding supply from a given cost), we need to compute the n-th root on large integers. We implement an integer-based Newton’s method to converge on the correct root:
In the curve calculations there is a need to perform power calculations where the base is an integer and the exponent is a fractional number.
In these cases we can perform the power operation as a combination of regular integer exponentiation and nth root based on Newton's method.
In order to use this, we convert the fractional exponent into a (numerator, denominator) tuple. These fractional exponents are all derived from RR
. Due to our UI-imposed limitations on RR
([0.15, 0.2, 0.25, … , 0.5]), we can use heuristics to choose the smallest possible values for numerator and denominator, such as to limit the computational load.
e.g.
The boilerplate contains:
Handlers for Info
, Buy
, Sell
, Get-Buy-Output
, Get-Sell-Output
, and the final Botega migration.
Integer-based calculations to maintain consistency when computing cost, price, and supply.
Configuration placeholders (like ###TARGET_MARKET_CAP###
, ###TARGET_SUPPLY###
, etc.) that are replaced by the form inputs.
Denomination: For safest results, use the default 18 decimals for your distributed token (like standard ERC-20).
Initialization: The curve only works after it is initialized with a transfer of tokens to be distributed. Ideally, send enough tokens to cover its entire life cycle.
Event Tracking: The sample code does not store or emit advanced event logs for each buy/sell. If detailed tracking is needed, you can extend the script.
Timing: Once the target is reached, no further buys or sells are processed; the code immediately proceeds with the migration.
While the UI references xCOIN
as a sample ticker, you can freely change it to the ticker (and process ID) of your actual AO token.
If you modify the quote token (default is qAR
), ensure the script’s placeholders are adapted accordingly.
The provided life cycle is an optional explanation for end users or integrators but reflects the recommended best practices for a full “Configure, Trade, Migrate” approach.