AI3 is a comprehensive framework to build a sustainable tokenomics design with powerful simulations with fuzz testing, and autonomously evolve it into a permanently unbreakable protocol with LLMs.
yarn add ai3We will define simple configurations in token.js and create a test in test.js.
mkdir myai3 && cd myai3 && yarn init && yarn add ai3
touch token.js test.jsThis is the overview of how the simulation works.
Define various variables for the protocol and the market in token.js.
Let's simulate a dex pair with $AI and $USDC.
export const vars = {
iail: { name: "Initial $AI Liquidity", val: 100 },
iusdcl: { name: "Initial $USDC Liquidity", val: 50 },
iaip: { name: "Initial $AI Price", val: g => g("iusdcl") / g("iail") },
ail: { name: "$AI Liquidity", val: (g, r) => r.ai },
usdcl: { name: "$USDC Liquidity", val: (g, r) => r.usdc },
aip: { name: "$AI Price", val: (g, r) => r.usdc / r.ai },
buy: { name: "Total $AI Buy", val: (g, r) => r.total_buy },
sell: { name: "Total $AI Sell", val: (g, r) => r.total_sell },
}val can be either a number or a function to calculate a number from other variables and the simulation result.
g: getter function to get a variabler: result from the simulation
For example, the initial $AI price (iaip) is computed by g("iusdcl") / g("iail"), and the current $AI price (aip) is computed by r.usdc / r.ai from the simulation result r.
In before, define intermediate variables that should be tracked during the simulation and returned as the final result.
after can do final cleanups after the simulation is complete.
export const before = ({ v }) => {
return {
price: v.iusdcl / v.iail,
ai: v.iail,
usdc: v.iusdcl,
total_buy: 0,
total_sell: 0,
}
}
export const after = ({ i, v, r, s }) => {
r.diff = r.price - s[0].price // recording the $AI price difference
}v: computed vars (immutable)
The simulations will loop through a specified period of time and any logic to change the variables is injectable as players.
const buyer = {
key: "BUYER",
desc: "Buyer buys 10 $AI if the price is less than $1.",
fn: ({ i, v, r, s }) => {
if (r.price < 1) {
const ai = r.ai - 10
const usdc = (r.usdc * r.ai) / ai
r.ai = ai
r.usdc = usdc
r.price = usdc / ai
r.total_buy += 10
s[i].buy = 10
}
},
}
const seller = {
key: "SELLER",
desc: "Seller sells 7 $AI if the price is more than $1.",
fn: ({ i, v, r, s }) => {
if (r.price > 1) {
const ai = r.ai + 7
const usdc = (r.usdc * r.ai) / ai
r.ai = ai
r.usdc = usdc
r.price = usdc / ai
r.total_sell += 7
s[i].sell = 7
}
},
}
export const players = [buyer, seller]i: days from the begginingv: computed vars (immutable)r: simulation results: daily stats
r is the final simulation result to be returned. s is an array of daily stats. All the variables in r is automatically copied to s as daily records. Players should update r and s[i] to record their action.
In the example above, daily buy and sell are recorded in s[i] as well as all the daily state of r variables (price, ai, usdc, total_buy, total_sell).
Let's write a simulation test in test.js.
import assert from "assert"
import { describe, it } from "node:test"
import { AI3 } from "ai3"
import { vars, before, after, players } from "./token.js"
describe("AI3", () => {
it("should simulate", async () => {
const ai3 = new AI3({ vars })
const { nvars, res, stats } = ai3.simulate({
before,
after,
players,
years: 1,
})
assert.equal(nvars.ail, 71) // nvars = new computed variables
assert.equal(ai3.get("ail"), 71) // get a single variable
})
})nvars: new computed variables with the simulation resultres: simulation resultstats: daily stats
Add "type": "module" to package.json so we can test with ES6.
{
"type": "module",
"dependencies": {
"ai3": "^0.0.2"
}
}Run the simulation.
node test.js4 components can be customized in the dashboard app. Add each configuration in token.js.
export const cols = [
[
{
title: "Projections",
vals: "iail,iusdcl,iaip,aip,diff,ail,usdcl,buy,sell",
},
],
]The displayed data formats and descriptions can be added to the vars.
__title__: name of the simulation
export const vars = {
__title__: "$AI Token",
iail: { name: "Initial $AI Liquidity", val: 100, type: "AI" },
iusdcl: { name: "Initial $USDC Liquidity", val: 50, decimal: 0 },
iaip: {
name: "Initial $AI Price",
val: g => g("iusdcl") / g("iail"),
calc: "IUSDCL / IAIL",
},
ail: {
name: "$AI Liquidity",
val: (g, r) => r.ai,
type: "AI",
calc: "DEX()",
},
usdcl: {
name: "$USDC Liquidity",
val: (g, r) => r.usdc,
decimal: 0,
calc: "DEX()",
},
aip: {
name: "$AI Price",
val: (g, r) => r.usdc / r.ai,
color: "crimson",
calc: "USDCL / AIL",
},
buy: {
name: "Total $AI Buy",
val: (g, r) => r.total_buy,
type: "AI",
calc: "DEX()",
},
sell: {
name: "Total $AI Sell",
val: (g, r) => r.total_sell,
type: "AI",
calc: "DEX()",
},
diff: {
name: "$AI Price Diff",
val: (g, r) => r.diff,
calc: "DEX()",
},
}
export const stats = g => [
{
title: "$AI Price",
val: `$${(Math.floor(g("aip") * 100) / 100).toFixed(2)}`,
},
{
title: "Initial Price",
val: `$${(Math.floor(g("iaip") * 100) / 100).toFixed(2)}`,
},
{
title: "Price Diff",
val: `$${(Math.floor(g("diff") * 100) / 100).toFixed(2)}`,
},
]
export const graphs = [
{
key: "price",
name: "$AI Price",
span: 7,
lines: [{ label: "$AI Price", key: "price", floor: false }],
},
{
key: "dex",
name: "DEX Trades",
lines: [
{ label: "$AI Sell", key: "total_sell" },
{ label: "$AI Buy", key: "total_buy", color: "#DC143C" },
],
},
]
export const table = [
{
key: "dex",
name: "DEX",
cols: [
{ title: "Day", w: "40px", val: "i" },
{ title: "AI", val: "ai" },
{ title: "USDC", val: "usdc" },
{ title: "Buy", val: s => s.buy ?? 0 },
{ title: "Sell", val: s => s.sell ?? 0 },
{
title: "Total",
val: s => (s.sell ?? 0) - (s.buy ?? 0),
color: val => (val < 0 ? "crimson" : "royalblue"),
},
{ title: "Price", val: v => `$ ${v.price.toFixed(3)}` },
],
},
]Clone this repo and install dependencies.
git clone https://github.com/weavedb/ai3.git
cd ai3/dashboard && yarnReplace the lib/token/index.js file with the token.js created earlier, then run the app.
yarn devNow the dashboard is running at localhost:3000.
You can design the best tokenomics by fuzz testing your simulation logic.
Let's find out the best initial USDC liquidity within the range of $10 and $100 to maximize the $AI token price in a year.
import assert from "assert"
import { describe, it } from "node:test"
import { AI3 } from "ai3"
import { vars, before, after, players } from "./token.js"
import { clone } from "ramda"
describe("AI3", () => {
it("should find the best iusdcl", async () => {
let max = null
for (let i = 10; i <= 100; i++) {
let _vars = clone(vars)
_vars.iusdcl.val = i
const ai3 = new AI3({ vars: _vars })
const { nvars, res, stats } = ai3.simulate({
before,
after,
players,
years: 1,
})
if (!max || max.aip < nvars.aip) {
max = { iusdcl: _vars.iusdcl.val, aip: nvars.aip, res }
}
}
assert.equal(max.iusdcl, 25)
assert.equal(Math.floor(max.aip * 100) / 100, 1.13)
})
})Now we know $25 is the best initial USDC liquidity, which increases the $AI price to around $1.13.
AI3 has an extremely powerful feature to simplify fuzz testing.
import assert from "assert"
import { describe, it } from "node:test"
import { AI3 } from "ai3"
import {
vars,
before,
after,
players,
} from "../../dashboard/lib/token-ai/index.js"
describe("AI3", () => {
it("should find the best iusdcl and iail", async () => {
const ai3 = new AI3({ vars })
const res = ai3.fuzz({
cases: { iusdcl: { range: [10, 101] }, iail: { range: [50, 101] } },
find: { aip: "max", diff: "min" },
before,
after,
players,
years: 1,
})
assert.equal(res.aip.case.iusdcl, 10)
assert.equal(res.aip.case.iail, 57)
assert.equal(res.diff.case.iusdcl, 100)
assert.equal(res.diff.case.iail, 50)
})
})cases: specify variables with a range to generate test cases with all the possible combinations.find: specify variables to check with a function.
The example above will create 4500 test cases with all the possible combinations of iusdcl (10-100) and iail (50-100), then find a case that results in the biggest aip and a case that results in the smallest diff.
AI3 plugins help building complex variables and highly intelligent players.
Plugins can be defined with __plugins__ in the vars object. Specify type and options for each plugin.
type: plugin type
export const vars = {
__plugins__: {
ai: { type: "token", ticker: "AI", supply: 10000 },
dex: {
type: "dex",
tokenA: "AI",
tokenB: "USDC",
liquidityA: 100,
liquidityB: 50,
}
}
}Plugins will auto generate variables prefixed by the key in upper case. For example, AI_ITS, AI_P, AI_FDV will be auto-generated by the token plugin with the options above.
Plugins will also generate intermediate variables and functions to manipulate them during a simulation and they can be accessed via p object. For example, the dex plugin generates la, lb, pa, pb, and the aforementioned BUYER/SELLER could be rewritten like the following.
export const before = ({ v }) => ({ total_buy: 0, total_sell: 0 })
export const after = ({ i, v, r, s }) => {
r.diff = p.dex.v.pa - p.ai.v.price
p.ai.v.price = p.dex.v.pa
r.diff = r.price - s[0].price
}
const buyer = {
key: "BUYER",
desc: "Buyer buys 10 $AI if the price is less than or equal to $1.",
fn: ({ v, s, i, r, p }) => {
if (p.dex.v.pa <= 1) {
p.dex.buyA(10)
r.total_buy += 10
s[i].buy = 10
}
},
}
const seller = {
key: "SELLER",
desc: "Seller sells 7 $AI if the price is more than or equal to $1.",
fn: ({ v, s, r, i, p }) => {
if (p.dex.v.pa >= 1) {
p.dex.sellA(7)
r.total_sell += 7
s[i].sell = 7
}
},
}
export const players = [buyer, seller]token emulates a simple ERC20 style token.
ticker: token tickersupply: initial total supply
[KEY]_ITS: initial token supply[KEY]_P: token price in USD[KEY]_TS: token supply[KEY]_FDV: fully diluted value
price: token pricets: token supply
dex emulates a bonding curve-based dex.
tokenA: tokenA tickertokenB: tokenB tickerliquidityA: tokenA initial liquidityliquidityB: tokenB initial liquidity
[KEY]_[TOKEN_A]_IL: tokenA initial liquidity[KEY]_[TOKEN_B]_IL: tokenB initial liquidity[KEY]_[TOKEN_A]_IP: tokenA initial price[KEY]_[TOKEN_B]_IP: tokenB initial price[KEY]_K: bonding curve constant[KEY]_[TOKEN_A]_L: tokenA liquidity[KEY]_[TOKEN_B]_L: tokenB liquidity[KEY]_[TOKEN_A]_P: tokenA price[KEY]_[TOKEN_B]_P: tokenB price
la: tokenA liquiditylb: tokenB liquidityk: bonding curve constantpa: tokenA pricepb: tokenB price
sellA ( amount ): sell tokenAsellB ( amount ): sell tokenBbuyA ( amount ): buy tokenAbuyB ( amount ): buy tokenB
vc emulates a fundrasing round.
round: fundrasing round name (e.g. PreSeed)ticker: round ticker (e.g. PS)token: token to allocateper: percentage to allocateval: valuation in USDvesting: vesting period in monthcliff: vesting cliff in monthsell: target token price to cash out
[KEY]_P: percentage to allocate[KEY]_V: valuation in USD[KEY]_VP: vesting period in month[KEY]_C: vesting cliff in month[KEY]_SP: selling price[KEY]_S: fundrasing sales in USD[KEY]_TP: fundrasing token price
p: percentage to allocatevp: vesting period in monthc: cliff in monthsp: target price to sellgain: capital gainsold: sold tokenunlocked: unlocked tokenunsold: unlocked yet unsold tokenlocked: locked tokenrate: daily unlock rate
unlock ( i ): unlock vested tokensell ( dex ): sell unlocked token
Coming soon...
You can inject LLM-based players and let them autonomously evolve the strategies.
Currently AI3 supports GPT 4o, Claude 3.5, and Ollama to locally run opensouce LLMs.
import { AI3, GPT, Claude, Ollama } from "ai3"
import { vars, befor, after, players } from "./your_tokenomics.js"
import "dotenv/config"
const gpt_key = process.env.GPT_KEY
const claude_key = process.env.Claude_KEY
const comp = "ai_bag_usdc"
const goal = `You have 50 usdc in the "r.ai_bag_usdc".
Your goal is to maximize the profit in USDC.
"r.ai_bag_usdc", "r.ai_bag_ai", "r.ai", "r.usdc" cannot be ever negative.`
const params = { vars, before, after, players, comp, goal }
const gpt = new GPT({ apiKey: gpt_key, ...params })
const { code, res, stats, nvars } = await gpt.init() // initial attempt
const res2 = await gpt.improve() // attempt to improve the previous logic
const claude = new Claude({ apiKey: claude_key, ...params })
const res3 = await claude.init()
const res4 = await claude.improve()
// LLM should be locally running with ollama
const ollaama = new Ollama({ model: "llama3.2:1b", ...params })
const res5 = await ollaama.init()
const res6 = await ollaama.improve()code in the returned object contains the logic the LLM generated, which can be used as the player.fn function to result in res, nvars, and stats.
goal: an explanation of the goal the LLM should achievecomp: a name of the variable in the simulation result to maximize, or a function to compare if the new logic produces a better result
To define a custom logic with comp, return 0, 1, or 2 based on the comparison with the previous logic.
const comp = (old_res, new_res)=>{
if(old_res.ai_bag_usdc < new_res.ai_bag_usdc){
return 0 // the logic was successfully improved
}else if(old_res.ai_bag_usdc === new_res.ai_bag_usdc){
return 1 // the logic produced the same result
}else{
return 2 // the previous logic was better
}
}beat() will force the LLM to continue trying until it beats the target logic.
For example, the following will command Cloude to beat the logic previously generated by GPT.
const res3 = await claude.beat({ target: res2 })When you just use one LLM, it will soon hit the ceiling where it cannot improve the logic anymore by itself, but if you let multiple LLMs interact with each other and collectively evolve the logic, they will autonomously improve the logic in an infinite loop. Theoretically, LLMs could create permanently sustainable tokenomics designes with a proactively evolving protocol based on constant simulations with realtime data.
AI3 is the one and only framework to effectively automate it. We can bring them fully onchain with a hyper scalable decentralized blockchain and protocol such as AO. This is the beginning of the DeFAI singularity and Nature2.0 is becoming a reality.
In the same way, you can create AI agents that have superuser access to change protocol parameters and let them play against other players to design unbreakable tokenomics.
Coming soon...