@leofcoin/contracts 0.1.24 → 0.1.26

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@leofcoin/contracts",
-  "version": "0.1.24",
+  "version": "0.1.26",
   "description": "",
   "type": "module",
   "exports": {
@@ -8,7 +8,10 @@
     "./name-service": "./exports/name-service.js",
     "./name-token": "./exports/name-service.js",
     "./power-token": "./exports/power-token.js",
+    "./mock-token": "./exports/mock-token.js",
     "./native-token": "./exports/native-token.js",
+    "./liquidity-pool": "./exports/liquidity-pool.js",
+    "./liquidity-pool-factory": "./exports/liquidity-pool-factory.js",
     "./validators": "./exports/validators.js"
   },
   "scripts": {
@@ -18,15 +21,16 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/leofcoin/monorepo"
+    "url": "git+https://github.com/leofcoin/monorepo.git",
+    "directory": "packages/contracts"
   },
   "keywords": [],
   "author": "",
   "license": "MIT",
   "bugs": {
-    "url": "https://github.com/leofcoin/contracts/issues"
+    "url": "https://github.com/leofcoin/monorepo/issues"
   },
-  "homepage": "https://github.com/leofcoin/contracts#readme",
+  "homepage": "https://github.com/leofcoin/monorepo/tree/main/packages/contracts#readme",
   "dependencies": {
     "@leofcoin/standards": "^0.3.7"
   },

package/rollup.config.js

@@ -82,5 +82,53 @@ export default [
         mangle: false
       })
     ]
+  },
+  {
+    input: './src/liquidity-pool.ts',
+    output: {
+      dir: './exports',
+      format: 'es'
+    },
+    plugins: [
+      resolve({
+        mainFields: ['exports']
+      }),
+      typescript(),
+      terser({
+        mangle: false
+      })
+    ]
+  },
+  {
+    input: './src/mock-token.ts',
+    output: {
+      dir: './exports',
+      format: 'es'
+    },
+    plugins: [
+      resolve({
+        mainFields: ['exports']
+      }),
+      typescript(),
+      terser({
+        mangle: false
+      })
+    ]
+  },
+  {
+    input: './src/liquidity-pool-factory.ts',
+    output: {
+      dir: './exports',
+      format: 'es'
+    },
+    plugins: [
+      resolve({
+        mainFields: ['exports']
+      }),
+      typescript(),
+      terser({
+        mangle: false
+      })
+    ]
   }
 ]

package/src/factory.ts

@@ -55,7 +55,7 @@ export default class Factory extends TokenReceiver {
   }
 
   #isCreator(address: address) {
-    return msg.staticCall(address, 'creator', [msg.sender]) as unknown as boolean
+    return msg.staticCall(address, 'creator') as unknown as boolean
   }
 
   /**

package/src/liquidity-pool-factory.ts

@@ -0,0 +1,72 @@
+import Meta, { MetaState } from '@leofcoin/standards/meta.js'
+
+export interface LiquidityPoolFactoryState extends MetaState {
+  pools: address[]
+  poolsByToken: { [token0: address]: { [token1: address]: address } }
+}
+
+const canonicalPair = (tokenA: address, tokenB: address): [address, address] => {
+  if (!tokenA || !tokenB) throw new Error('token address undefined')
+  if (tokenA === tokenB) throw new Error('pool tokens must differ')
+  return [tokenA, tokenB].sort((left, right) => left.localeCompare(right)) as [address, address]
+}
+
+export default class LiquidityPoolFactory extends Meta {
+  #pools: address[] = []
+  #poolsByToken: { [token0: address]: { [token1: address]: address } } = {}
+
+  constructor(state?: LiquidityPoolFactoryState) {
+    super(state)
+    if (state) {
+      this.#pools = [...state.pools]
+      this.#poolsByToken = Object.fromEntries(
+        Object.entries(state.poolsByToken).map(([token0, pools]) => [token0, { ...pools }])
+      )
+    }
+  }
+
+  get state(): LiquidityPoolFactoryState {
+    return {
+      ...(super.state as MetaState),
+      pools: [...this.#pools],
+      poolsByToken: Object.fromEntries(
+        Object.entries(this.#poolsByToken).map(([token0, pools]) => [token0, { ...pools }])
+      )
+    }
+  }
+
+  get pools() {
+    return [...this.#pools]
+  }
+
+  get totalPools() {
+    return BigInt(this.#pools.length)
+  }
+
+  poolFor(tokenA: address, tokenB: address): address | undefined {
+    const [token0, token1] = canonicalPair(tokenA, tokenB)
+    return this.#poolsByToken[token0]?.[token1]
+  }
+
+  async registerPool(pool: address): Promise<address> {
+    if (!pool) throw new Error('pool address undefined')
+    if (this.#pools.includes(pool)) throw new Error('pool already registered')
+    if (msg.sender !== this.creator) throw new Error('only the factory owner may register pools')
+
+    const creator = (await msg.staticCall(pool, 'creator')) as address
+    if (creator !== msg.sender) throw new Error('factory owner must deploy the pool')
+
+    const poolToken0 = (await msg.staticCall(pool, 'token0')) as address
+    const poolToken1 = (await msg.staticCall(pool, 'token1')) as address
+    const [token0, token1] = canonicalPair(poolToken0, poolToken1)
+
+    const fee = BigInt(await msg.staticCall(pool, 'feeBasisPoints'))
+    if (fee < 0n || fee >= 10_000n) throw new Error('invalid pool fee')
+    if (this.#poolsByToken[token0]?.[token1]) throw new Error('pair already registered')
+
+    if (!this.#poolsByToken[token0]) this.#poolsByToken[token0] = {}
+    this.#poolsByToken[token0][token1] = pool
+    this.#pools.push(pool)
+    return pool
+  }
+}

package/src/liquidity-pool.ts

@@ -0,0 +1,259 @@
+import Meta, { MetaState } from '@leofcoin/standards/meta.js'
+
+export interface LiquidityPoolState extends MetaState {
+  token0: address
+  token1: address
+  feeBasisPoints: bigint
+  reserve0: bigint
+  reserve1: bigint
+  totalLiquidity: bigint
+  liquidity: { [provider: address]: bigint }
+}
+
+const BASIS_POINTS = 10_000n
+
+const squareRoot = (value: bigint): bigint => {
+  if (value < 0n) throw new Error('cannot calculate square root of a negative value')
+  if (value < 2n) return value
+
+  let current = value
+  let next = (current + value / current) / 2n
+  while (next < current) {
+    current = next
+    next = (current + value / current) / 2n
+  }
+  return current
+}
+
+export default class LiquidityPool extends Meta {
+  #token0: address
+  #token1: address
+  #feeBasisPoints: bigint
+  #reserve0 = 0n
+  #reserve1 = 0n
+  #totalLiquidity = 0n
+  #liquidity: { [provider: address]: bigint } = {}
+  #locked = false
+
+  constructor(
+    token0: address,
+    token1: address,
+    feeBasisPoints: bigint = 30n,
+    state?: LiquidityPoolState
+  ) {
+    if (!token0 || !token1) throw new Error('token address undefined')
+    if (token0 === token1) throw new Error('pool tokens must differ')
+    super(state)
+    this.#token0 = token0
+    this.#token1 = token1
+    this.#feeBasisPoints = BigInt(state?.feeBasisPoints ?? feeBasisPoints)
+    if (this.#feeBasisPoints < 0n || this.#feeBasisPoints >= BASIS_POINTS)
+      throw new Error('invalid fee')
+
+    if (state) {
+      if (state.token0 !== token0 || state.token1 !== token1)
+        throw new Error('pool state token mismatch')
+      this.#reserve0 = BigInt(state.reserve0)
+      this.#reserve1 = BigInt(state.reserve1)
+      this.#totalLiquidity = BigInt(state.totalLiquidity)
+      this.#liquidity = Object.fromEntries(
+        Object.entries(state.liquidity).map(([provider, amount]) => [provider, BigInt(amount)])
+      )
+    }
+  }
+
+  get token0() {
+    return this.#token0
+  }
+
+  get token1() {
+    return this.#token1
+  }
+
+  get feeBasisPoints() {
+    return this.#feeBasisPoints
+  }
+
+  get reserve0() {
+    return this.#reserve0
+  }
+
+  get reserve1() {
+    return this.#reserve1
+  }
+
+  get reserves() {
+    return [this.#reserve0, this.#reserve1]
+  }
+
+  get totalLiquidity() {
+    return this.#totalLiquidity
+  }
+
+  get state(): LiquidityPoolState {
+    return {
+      ...(super.state as MetaState),
+      token0: this.#token0,
+      token1: this.#token1,
+      feeBasisPoints: this.#feeBasisPoints,
+      reserve0: this.#reserve0,
+      reserve1: this.#reserve1,
+      totalLiquidity: this.#totalLiquidity,
+      liquidity: { ...this.#liquidity }
+    }
+  }
+
+  liquidityOf(provider: address): bigint {
+    return this.#liquidity[provider] ?? 0n
+  }
+
+  getAmountOut(tokenIn: address, amountIn: bigint): bigint {
+    amountIn = BigInt(amountIn)
+    if (amountIn <= 0n) throw new Error('input amount must be positive')
+
+    let reserveIn: bigint
+    let reserveOut: bigint
+    if (tokenIn === this.#token0) {
+      reserveIn = this.#reserve0
+      reserveOut = this.#reserve1
+    } else if (tokenIn === this.#token1) {
+      reserveIn = this.#reserve1
+      reserveOut = this.#reserve0
+    } else {
+      throw new Error('token not in pool')
+    }
+    if (reserveIn <= 0n || reserveOut <= 0n) throw new Error('insufficient liquidity')
+
+    const amountInWithFee = amountIn * (BASIS_POINTS - this.#feeBasisPoints)
+    return (amountInWithFee * reserveOut) / (reserveIn * BASIS_POINTS + amountInWithFee)
+  }
+
+  async addLiquidity(
+    amount0Desired: bigint,
+    amount1Desired: bigint,
+    minimumLiquidity: bigint = 0n
+  ) {
+    return this.#withLock(async () => {
+      amount0Desired = BigInt(amount0Desired)
+      amount1Desired = BigInt(amount1Desired)
+      minimumLiquidity = BigInt(minimumLiquidity)
+      if (amount0Desired <= 0n || amount1Desired <= 0n)
+        throw new Error('liquidity amounts must be positive')
+      if (minimumLiquidity < 0n) throw new Error('minimum liquidity cannot be negative')
+
+      let amount0 = amount0Desired
+      let amount1 = amount1Desired
+      let minted: bigint
+      if (this.#totalLiquidity === 0n) {
+        minted = squareRoot(amount0 * amount1)
+      } else {
+        const amount1ForAmount0 = (amount0Desired * this.#reserve1) / this.#reserve0
+        if (amount1ForAmount0 <= amount1Desired) {
+          amount1 = amount1ForAmount0
+        } else {
+          amount0 = (amount1Desired * this.#reserve0) / this.#reserve1
+        }
+        minted = (amount0 * this.#totalLiquidity) / this.#reserve0
+      }
+
+      if (amount0 <= 0n || amount1 <= 0n || minted <= 0n)
+        throw new Error('liquidity amount rounds to zero')
+      if (minted < minimumLiquidity) throw new Error('minimum liquidity not met')
+
+      const provider = msg.sender
+      this.#reserve0 += amount0
+      this.#reserve1 += amount1
+      this.#totalLiquidity += minted
+      this.#liquidity[provider] = this.liquidityOf(provider) + minted
+
+      await this.#pull(this.#token0, provider, amount0)
+      await this.#pull(this.#token1, provider, amount1)
+      return { amount0, amount1, liquidity: minted }
+    })
+  }
+
+  async removeLiquidity(
+    liquidity: bigint,
+    minimumAmount0: bigint = 0n,
+    minimumAmount1: bigint = 0n,
+    receiver: address = msg.sender
+  ) {
+    return this.#withLock(async () => {
+      liquidity = BigInt(liquidity)
+      minimumAmount0 = BigInt(minimumAmount0)
+      minimumAmount1 = BigInt(minimumAmount1)
+      if (!receiver) throw new Error('receiver undefined')
+      if (liquidity <= 0n) throw new Error('liquidity must be positive')
+      if (this.liquidityOf(msg.sender) < liquidity)
+        throw new Error('insufficient liquidity balance')
+
+      const amount0 = (liquidity * this.#reserve0) / this.#totalLiquidity
+      const amount1 = (liquidity * this.#reserve1) / this.#totalLiquidity
+      if (amount0 <= 0n || amount1 <= 0n) throw new Error('withdrawal amount rounds to zero')
+      if (amount0 < minimumAmount0 || amount1 < minimumAmount1)
+        throw new Error('minimum withdrawal amount not met')
+
+      this.#liquidity[msg.sender] -= liquidity
+      this.#totalLiquidity -= liquidity
+      this.#reserve0 -= amount0
+      this.#reserve1 -= amount1
+
+      await this.#push(this.#token0, receiver, amount0)
+      await this.#push(this.#token1, receiver, amount1)
+      return { amount0, amount1, liquidity }
+    })
+  }
+
+  async swapExactTokensForTokens(
+    tokenIn: address,
+    amountIn: bigint,
+    minimumAmountOut: bigint,
+    receiver: address = msg.sender,
+    deadline: number = Number.MAX_SAFE_INTEGER
+  ) {
+    return this.#withLock(async () => {
+      amountIn = BigInt(amountIn)
+      minimumAmountOut = BigInt(minimumAmountOut)
+      if (!receiver) throw new Error('receiver undefined')
+      if (!Number.isSafeInteger(deadline) || deadline < Date.now()) throw new Error('swap expired')
+
+      const amountOut = this.getAmountOut(tokenIn, amountIn)
+      if (amountOut <= 0n) throw new Error('output amount rounds to zero')
+      if (amountOut < minimumAmountOut) throw new Error('minimum output amount not met')
+
+      const sender = msg.sender
+      if (tokenIn === this.#token0) {
+        this.#reserve0 += amountIn
+        this.#reserve1 -= amountOut
+        await this.#pull(this.#token0, sender, amountIn)
+        await this.#push(this.#token1, receiver, amountOut)
+      } else if (tokenIn === this.#token1) {
+        this.#reserve1 += amountIn
+        this.#reserve0 -= amountOut
+        await this.#pull(this.#token1, sender, amountIn)
+        await this.#push(this.#token0, receiver, amountOut)
+      } else {
+        throw new Error('token not in pool')
+      }
+      return amountOut
+    })
+  }
+
+  async #pull(token: address, owner: address, amount: bigint) {
+    return msg.call(token, 'transferFrom', [owner, msg.contract, amount])
+  }
+
+  async #push(token: address, receiver: address, amount: bigint) {
+    return msg.call(token, 'transfer', [receiver, amount])
+  }
+
+  async #withLock<T>(operation: () => Promise<T>): Promise<T> {
+    if (this.#locked) throw new Error('reentrant call')
+    this.#locked = true
+    try {
+      return await operation()
+    } finally {
+      this.#locked = false
+    }
+  }
+}

package/src/mock-token.ts

@@ -0,0 +1,114 @@
+import Token, { TokenState } from '@leofcoin/standards/token.js'
+
+export interface MockTokenAllocation {
+  address: address
+  amount: bigint | string
+}
+
+export interface MockTokenState extends TokenState {
+  name: string
+  symbol: string
+  decimals: number
+}
+
+const validateMetadata = (name: string, symbol: string, decimals: number) => {
+  if (!name?.trim()) throw new Error('token name is required')
+  if (!symbol?.trim()) throw new Error('token symbol is required')
+  if (!Number.isSafeInteger(decimals) || decimals < 0 || decimals > 18)
+    throw new Error('token decimals must be an integer between 0 and 18')
+}
+
+const initialState = (
+  name: string,
+  symbol: string,
+  decimals: number,
+  initialSupply: bigint,
+  allocations: MockTokenAllocation[]
+): MockTokenState => {
+  initialSupply = BigInt(initialSupply)
+  if (initialSupply <= 0n) throw new Error('initial supply must be positive')
+
+  const effectiveAllocations = allocations.length > 0 ? allocations : [{ address: msg.sender, amount: initialSupply }]
+  const balances: Record<address, bigint> = {}
+  let allocated = 0n
+
+  for (const allocation of [...effectiveAllocations].sort((left, right) => left.address.localeCompare(right.address))) {
+    if (!allocation.address || balances[allocation.address] !== undefined)
+      throw new Error('invalid or duplicate allocation address')
+    const amount = BigInt(allocation.amount)
+    if (amount <= 0n) throw new Error('allocation amount must be positive')
+    balances[allocation.address] = amount
+    allocated += amount
+  }
+
+  if (allocated !== initialSupply) {
+    throw new Error(`allocations must equal initial supply: expected ${initialSupply}, got ${allocated}`)
+  }
+
+  return {
+    name,
+    symbol,
+    decimals,
+    creator: msg.sender,
+    createdAt: BigInt(Date.now()),
+    roles: {
+      OWNER: [msg.sender],
+      MINT: [msg.sender],
+      BURN: [msg.sender]
+    },
+    holders: BigInt(Object.keys(balances).length),
+    balances,
+    approvals: {},
+    totalSupply: initialSupply
+  }
+}
+
+/**
+ * Development-only fungible asset used to test generic token and DEX behavior.
+ * A deployment of this contract never represents or escrows the external asset
+ * whose name or symbol it mimics.
+ */
+export default class MockToken extends Token {
+  #tokenName: string
+  #tokenSymbol: string
+  #tokenDecimals: number
+
+  constructor(
+    name: string,
+    symbol: string,
+    decimals: number,
+    initialSupply: bigint,
+    allocations: MockTokenAllocation[] = [],
+    restoredState?: MockTokenState
+  ) {
+    validateMetadata(name, symbol, decimals)
+    const state = restoredState || initialState(name, symbol, decimals, initialSupply, allocations)
+    if (state.name !== name || state.symbol !== symbol || state.decimals !== decimals)
+      throw new Error('restored token metadata mismatch')
+    super(name, symbol, decimals, state)
+    this.#tokenName = name
+    this.#tokenSymbol = symbol
+    this.#tokenDecimals = decimals
+  }
+
+  get name() {
+    return this.#tokenName
+  }
+
+  get symbol() {
+    return this.#tokenSymbol
+  }
+
+  get decimals() {
+    return this.#tokenDecimals
+  }
+
+  get state(): MockTokenState {
+    return {
+      ...super.state,
+      name: this.#tokenName,
+      symbol: this.#tokenSymbol,
+      decimals: this.#tokenDecimals
+    } as MockTokenState
+  }
+}

package/src/validators.ts

@@ -126,7 +126,7 @@ export default class Validators extends Roles {
     if (this.minimumBalance > balance)
       throw new Error(`balance to low! got: ${balance} need: ${this.#minimumBalance}`)
 
-    await msg.call(this.currency, 'transfer', [validator, msg.contract, this.#minimumBalance])
+    await msg.call(this.currency, 'transferFrom', [validator, msg.contract, this.#minimumBalance])
 
     this.#balances[validator] = this.#minimumBalance
     this.#validators.push(validator)
@@ -135,7 +135,7 @@ export default class Validators extends Roles {
   async removeValidator(validator) {
     this.#isAllowed(validator)
     if (!this.has(validator)) throw new Error('validator not found')
-    await msg.call(this.currency, 'transfer', [msg.contract, validator, this.#minimumBalance])
+    await msg.call(this.currency, 'transfer', [validator, this.#minimumBalance])
     delete this.#balances[validator]
     this.#validators.splice(this.#validators.indexOf(validator), 1)
   }

package/test/factory.js

@@ -40,10 +40,11 @@ describe('Factory', () => {
         return BigInt(100) // Balance too low
       } else if (method === 'creator') {
         return true
-      } else if (method === 'transfer') {
-        throw new Error('amount exceeds balance')
       }
     }
+    global.msg.call = async (currency, method) => {
+      if (method === 'transferFrom') throw new Error('amount exceeds balance')
+    }
     await assert.rejects(async () => await factory.registerContract('0xContractAddress'), {
       message: 'amount exceeds balance'
     })
@@ -57,9 +58,16 @@ describe('Factory', () => {
   })
 
   it('should successfully register a contract', async () => {
+    let creatorParameters
+    global.msg.staticCall = async (currency, method, args) => {
+      if (method === 'creator') creatorParameters = args
+      if (method === 'balanceOf') return BigInt(100000)
+      return true
+    }
     await factory.registerContract('0xContractAddress')
 
     assert.equal(factory.totalContracts, BigInt(1))
     assert.ok(factory.contracts.includes('0xContractAddress'))
+    assert.equal(creatorParameters, undefined)
   })
 })

package/test/liquidity-pool-factory.js

@@ -0,0 +1,71 @@
+import { beforeEach, describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+import LiquidityPoolFactory from '../exports/liquidity-pool-factory.js'
+
+describe('LiquidityPoolFactory', () => {
+  const creator = '0xCreator'
+  const token0 = '0xToken0'
+  const token1 = '0xToken1'
+  const poolAddress = '0xPool'
+  let factory
+  let pool
+
+  beforeEach(() => {
+    pool = { creator, token0, token1, feeBasisPoints: 30n }
+    global.msg = {
+      sender: creator,
+      contract: '0xFactory',
+      staticCall: async (target, method) => {
+        assert.equal(target, poolAddress)
+        return pool[method]
+      }
+    }
+    factory = new LiquidityPoolFactory()
+  })
+
+  it('registers one canonical pool per pair', async () => {
+    assert.equal(await factory.registerPool(poolAddress), poolAddress)
+    assert.equal(factory.poolFor(token0, token1), poolAddress)
+    assert.equal(factory.poolFor(token1, token0), poolAddress)
+    assert.deepEqual(factory.pools, [poolAddress])
+    assert.equal(factory.totalPools, 1n)
+
+    await assert.rejects(factory.registerPool(poolAddress), {
+      message: 'pool already registered'
+    })
+  })
+
+  it('requires the factory owner and accepts either pool token order', async () => {
+    global.msg.sender = '0xAttacker'
+    await assert.rejects(factory.registerPool(poolAddress), {
+      message: 'only the factory owner may register pools'
+    })
+
+    global.msg.sender = creator
+    pool = { ...pool, token0: token1, token1: token0 }
+    assert.equal(await factory.registerPool(poolAddress), poolAddress)
+    assert.equal(factory.poolFor(token0, token1), poolAddress)
+  })
+
+  it('requires pools to be deployed by the factory owner', async () => {
+    pool.creator = '0xDifferentCreator'
+    await assert.rejects(factory.registerPool(poolAddress), {
+      message: 'factory owner must deploy the pool'
+    })
+  })
+
+  it('rejects a second pool for the same pair and restores state', async () => {
+    await factory.registerPool(poolAddress)
+    const restored = new LiquidityPoolFactory(factory.state)
+    assert.equal(restored.poolFor(token1, token0), poolAddress)
+
+    const secondPool = '0xSecondPool'
+    global.msg.staticCall = async (target, method) => {
+      assert.equal(target, secondPool)
+      return pool[method]
+    }
+    await assert.rejects(restored.registerPool(secondPool), {
+      message: 'pair already registered'
+    })
+  })
+})

package/test/liquidity-pool.js

@@ -0,0 +1,175 @@
+import { beforeEach, describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+import LiquidityPool from '../exports/liquidity-pool.js'
+import MockToken from '../exports/mock-token.js'
+
+describe('LiquidityPool', () => {
+  const poolAddress = '0xPool'
+  const token0 = '0xToken0'
+  const token1 = '0xToken1'
+  const alice = '0xAlice'
+  const bob = '0xBob'
+  let pool
+  let balances
+  let allowances
+
+  const balanceOf = (token, account) => balances[token][account] ?? 0n
+  const allowanceOf = (token, owner, operator) => allowances[token][owner]?.[operator] ?? 0n
+
+  beforeEach(() => {
+    balances = {
+      [token0]: { [alice]: 100_000n, [bob]: 100_000n },
+      [token1]: { [alice]: 100_000n, [bob]: 100_000n }
+    }
+    allowances = {
+      [token0]: {
+        [alice]: { [poolAddress]: 100_000n },
+        [bob]: { [poolAddress]: 100_000n }
+      },
+      [token1]: {
+        [alice]: { [poolAddress]: 100_000n },
+        [bob]: { [poolAddress]: 100_000n }
+      }
+    }
+    global.msg = {
+      sender: alice,
+      contract: poolAddress,
+      call: async (contract, method, params) => {
+        if (method === 'transferFrom') {
+          const [owner, receiver, amount] = params
+          const approved = allowanceOf(contract, owner, poolAddress)
+          if (approved < amount) throw new Error('amount exceeds allowance')
+          if (balanceOf(contract, owner) < amount) throw new Error('amount exceeds balance')
+          allowances[contract][owner][poolAddress] = approved - amount
+          balances[contract][owner] -= amount
+          balances[contract][receiver] = balanceOf(contract, receiver) + amount
+          return
+        }
+        if (method === 'transfer') {
+          const [receiver, amount] = params
+          if (balanceOf(contract, poolAddress) < amount) throw new Error('amount exceeds balance')
+          balances[contract][poolAddress] -= amount
+          balances[contract][receiver] = balanceOf(contract, receiver) + amount
+          return
+        }
+        throw new Error(`unsupported token method: ${method}`)
+      }
+    }
+    pool = new LiquidityPool(token0, token1)
+  })
+
+  it('adds balanced initial liquidity using approvals', async () => {
+    const result = await pool.addLiquidity(10_000n, 10_000n, 10_000n)
+
+    assert.deepEqual(result, {
+      amount0: 10_000n,
+      amount1: 10_000n,
+      liquidity: 10_000n
+    })
+    assert.deepEqual(pool.reserves, [10_000n, 10_000n])
+    assert.equal(pool.liquidityOf(alice), 10_000n)
+    assert.equal(balanceOf(token0, poolAddress), 10_000n)
+    assert.equal(balanceOf(token1, poolAddress), 10_000n)
+  })
+
+  it('accepts only the proportional part of later liquidity', async () => {
+    await pool.addLiquidity(10_000n, 20_000n)
+    global.msg.sender = bob
+
+    const result = await pool.addLiquidity(10_000n, 30_000n)
+
+    assert.deepEqual(result, {
+      amount0: 10_000n,
+      amount1: 20_000n,
+      liquidity: 14_142n
+    })
+    assert.deepEqual(pool.reserves, [20_000n, 40_000n])
+    assert.equal(balanceOf(token1, bob), 80_000n)
+  })
+
+  it('swaps with a constant-product fee and enforces slippage', async () => {
+    await pool.addLiquidity(10_000n, 10_000n)
+    global.msg.sender = bob
+
+    const quoted = pool.getAmountOut(token0, 1_000n)
+    assert.equal(quoted, 906n)
+    const productBefore = pool.reserve0 * pool.reserve1
+    await assert.rejects(pool.swapExactTokensForTokens(token0, 1_000n, 907n, bob, Date.now()), {
+      message: 'minimum output amount not met'
+    })
+
+    const received = await pool.swapExactTokensForTokens(token0, 1_000n, 906n, bob, Date.now())
+    assert.equal(received, 906n)
+    assert.deepEqual(pool.reserves, [11_000n, 9_094n])
+    assert.ok(pool.reserve0 * pool.reserve1 > productBefore)
+    assert.equal(balanceOf(token1, bob), 100_906n)
+  })
+
+  it('rejects expired swaps', async () => {
+    await pool.addLiquidity(10_000n, 10_000n)
+    await assert.rejects(pool.swapExactTokensForTokens(token0, 1_000n, 1n, alice, Date.now() - 1), {
+      message: 'swap expired'
+    })
+  })
+
+  it('returns the provider share and can restore its state', async () => {
+    await pool.addLiquidity(10_000n, 20_000n)
+    const restored = new LiquidityPool(token0, token1, 30n, pool.state)
+
+    assert.deepEqual(restored.reserves, [10_000n, 20_000n])
+    assert.equal(restored.liquidityOf(alice), 14_142n)
+
+    const result = await pool.removeLiquidity(14_142n, 9_999n, 19_999n)
+    assert.deepEqual(result, {
+      amount0: 10_000n,
+      amount1: 20_000n,
+      liquidity: 14_142n
+    })
+    assert.deepEqual(pool.reserves, [0n, 0n])
+    assert.equal(pool.totalLiquidity, 0n)
+  })
+
+  it('rejects invalid pairs and missing allowance', async () => {
+    assert.throws(() => new LiquidityPool(token0, token0), {
+      message: 'pool tokens must differ'
+    })
+    allowances[token0][alice][poolAddress] = 0n
+    await assert.rejects(pool.addLiquidity(10_000n, 10_000n), {
+      message: 'amount exceeds allowance'
+    })
+  })
+
+  it('trades mock WETH and USDC through their real token contract interface', async () => {
+    const wethAddress = '0xMockWETH'
+    const usdcAddress = '0xMockUSDC'
+    global.msg = { sender: alice }
+    const weth = new MockToken('Mock Wrapped Ether', 'WETH', 18, 100_000n)
+    const usdc = new MockToken('Mock USD Coin', 'USDC', 6, 200_000n)
+    const tokens = { [wethAddress]: weth, [usdcAddress]: usdc }
+    const contractPool = new LiquidityPool(wethAddress, usdcAddress)
+
+    weth.approve(poolAddress, 100_000n)
+    usdc.approve(poolAddress, 200_000n)
+    global.msg = {
+      sender: alice,
+      contract: poolAddress,
+      call: async (contract, method, params) => {
+        const previousMessage = global.msg
+        global.msg = { sender: poolAddress, contract }
+        try {
+          return await tokens[contract][method](...params)
+        } finally {
+          global.msg = previousMessage
+        }
+      }
+    }
+
+    await contractPool.addLiquidity(10_000n, 20_000n)
+
+    assert.deepEqual(contractPool.reserves, [10_000n, 20_000n])
+    assert.equal(weth.balanceOf(poolAddress), 10_000n)
+    assert.equal(usdc.balanceOf(poolAddress), 20_000n)
+    assert.equal(weth.allowance(alice, poolAddress), 90_000n)
+    assert.equal(usdc.allowance(alice, poolAddress), 180_000n)
+  })
+})

package/test/mock-token.js

@@ -0,0 +1,48 @@
+import { beforeEach, describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+import MockToken from '../exports/mock-token.js'
+
+describe('MockToken', () => {
+  const owner = '0xOwner'
+  const alice = '0xAlice'
+
+  beforeEach(() => {
+    global.msg = { sender: owner }
+  })
+
+  it('creates mock WETH, WBNB and USDC with their conventional decimals', () => {
+    const assets = [
+      new MockToken('Mock Wrapped Ether', 'WETH', 18, 1_000_000n),
+      new MockToken('Mock Wrapped BNB', 'WBNB', 18, 2_000_000n),
+      new MockToken('Mock USD Coin', 'USDC', 6, 3_000_000n)
+    ]
+
+    assert.deepEqual(
+      assets.map((asset) => [asset.symbol, asset.decimals, asset.balanceOf(owner)]),
+      [
+        ['WETH', 18, 1_000_000n],
+        ['WBNB', 18, 2_000_000n],
+        ['USDC', 6, 3_000_000n]
+      ]
+    )
+  })
+
+  it('supports transfers, allowances and deterministic state restoration', () => {
+    const token = new MockToken('Mock USD Coin', 'USDC', 6, 1_000_000n)
+    token.transfer(alice, 100_000n)
+    token.approve(alice, 25_000n)
+
+    const restored = new MockToken('Mock USD Coin', 'USDC', 6, 1_000_000n, [], token.state)
+
+    assert.equal(restored.balanceOf(owner), 900_000n)
+    assert.equal(restored.balanceOf(alice), 100_000n)
+    assert.equal(restored.allowance(owner, alice), 25_000n)
+    assert.equal(restored.totalSupply, 1_000_000n)
+  })
+
+  it('rejects allocations that do not match the declared supply', () => {
+    assert.throws(() => new MockToken('Mock USD Coin', 'USDC', 6, 1_000_000n, [{ address: owner, amount: 1n }]), {
+      message: 'allocations must equal initial supply: expected 1000000, got 1'
+    })
+  })
+})

package/test/native-token.js

@@ -89,7 +89,7 @@ describe('Leofcoin', () => {
 
   it('allows allocated holders to transfer', () => {
     msg.sender = receiverAddress
-    token.transfer(receiverAddress, otherReceiverAddress, 10_000n)
+    token.transfer(otherReceiverAddress, 10_000n)
     assert.equal(token.balanceOf(receiverAddress), 390_000n)
     assert.equal(token.balanceOf(otherReceiverAddress), 10_000n)
   })