Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
import { describe, it, expect } from 'vitest';
import {
sharePriceE6, sharesForDeposit, payoutForShares, settleRedemption,
sharesRedeemableNow, drawdownBps, isDrawdownBreached, depositExceedsCap,
tradeExceedsPerTrade, tradeExceedsDailyBudget, nextPeak, roiBps,
usdcToAtomics, atomicsToUsdc, SHARE_PRICE_SCALE,
parseAmountInput, clampTermBps, TERM_BOUNDS,
} from '../api/_lib/vault-accounting.js';
const USDC = 1_000_000n; // 1 USDC in atomics
describe('share price', () => {
it('is exactly par (1.0) for an empty vault', () => {
expect(sharePriceE6(0n, 0n)).toBe(SHARE_PRICE_SCALE);
expect(sharePriceE6(5_000n * USDC, 0n)).toBe(SHARE_PRICE_SCALE);
});
it('reflects NAV per share once shares exist', () => {
// 100 USDC NAV across 50 shares-worth of atomics → 2.0 USDC/share.
expect(sharePriceE6(100n * USDC, 50n * USDC)).toBe(2_000_000n);
});
});
describe('sharesForDeposit', () => {
it('mints 1:1 at par on the first deposit', () => {
expect(sharesForDeposit(100n * USDC, 0n, 0n)).toBe(100n * USDC);
});
it('mints 1:1 when a wiped-out vault has no recoverable NAV', () => {
expect(sharesForDeposit(100n * USDC, 0n, 500n * USDC)).toBe(100n * USDC);
});
it('mints fewer shares as the price rises above par', () => {
// NAV doubled to 2.0/share → a 100 USDC deposit buys 50 shares-worth.
const total = 100n * USDC;
const navBefore = 200n * USDC; // price 2.0
expect(sharesForDeposit(100n * USDC, navBefore, total)).toBe(50n * USDC);
});
it('does not dilute existing holders: price after deposit is unchanged', () => {
const total = 100n * USDC;
const navBefore = 150n * USDC; // price 1.5
const minted = sharesForDeposit(60n * USDC, navBefore, total);
const navAfter = navBefore + 60n * USDC;
const totalAfter = total + minted;
// New price must not exceed the old price (floored mint can only help holders).
expect(sharePriceE6(navAfter, totalAfter)).toBeGreaterThanOrEqual(sharePriceE6(navBefore, total) - 1n);
expect(sharePriceE6(navAfter, totalAfter)).toBeLessThanOrEqual(sharePriceE6(navBefore, total) + 1n);
});
});
describe('payoutForShares', () => {
it('pays the pro-rata claim', () => {
// 25 of 100 shares against 200 USDC NAV → 50 USDC.
expect(payoutForShares(25n * USDC, 200n * USDC, 100n * USDC)).toBe(50n * USDC);
});
it('the last holder out takes the entire remaining NAV (no dust stranded)', () => {
const nav = 999_999n; // an awkward, indivisible amount
const total = 7n;
expect(payoutForShares(total, nav, total)).toBe(nav);
});
it('never overdraws: the sum of all backers redeeming at once is ≤ NAV', () => {
const nav = 1_000_000_001n; // not cleanly divisible
const shareSplit = [333_333n, 333_333n, 333_334n];
const total = shareSplit.reduce((a, b) => a + b, 0n);
const sum = shareSplit.reduce((acc, s) => acc + payoutForShares(s, nav, total), 0n);
expect(sum).toBeLessThanOrEqual(nav);
});
});
describe('settleRedemption — performance fee', () => {
it('charges fee only on realized gain above cost basis', () => {
// Backer holds 100 shares, basis 100 USDC; NAV doubled (200 USDC, 100 shares).
const r = settleRedemption({
shares: 100n * USDC, backerShares: 100n * USDC, costBasisAtomics: 100n * USDC,
navAtomics: 200n * USDC, totalShares: 100n * USDC, feeBps: 1000, // 10%
});
expect(r.grossPayout).toBe(200n * USDC);
expect(r.gain).toBe(100n * USDC);
expect(r.fee).toBe(10n * USDC); // 10% of the 100 USDC gain
expect(r.netPayout).toBe(190n * USDC);
});
it('charges ZERO fee on a loss — never touches principal', () => {
const r = settleRedemption({
shares: 100n * USDC, backerShares: 100n * USDC, costBasisAtomics: 100n * USDC,
navAtomics: 60n * USDC, totalShares: 100n * USDC, feeBps: 2000,
});
expect(r.gain).toBe(-40n * USDC);
expect(r.fee).toBe(0n);
expect(r.netPayout).toBe(60n * USDC);
});
it('charges fee only on the realized slice for a partial redemption', () => {
// Redeem half the position; basis attributed to the half is half the basis.
const r = settleRedemption({
shares: 50n * USDC, backerShares: 100n * USDC, costBasisAtomics: 100n * USDC,
navAtomics: 200n * USDC, totalShares: 100n * USDC, feeBps: 1000,
});
expect(r.costPortion).toBe(50n * USDC);
expect(r.grossPayout).toBe(100n * USDC);
expect(r.gain).toBe(50n * USDC);
expect(r.fee).toBe(5n * USDC);
expect(r.netPayout).toBe(95n * USDC);
expect(r.remainingBasis).toBe(50n * USDC);
});
it('net payout + fee always reconciles to the gross payout', () => {
for (const [navMul, feeBps] of [[3n, 1500], [1n, 1000], [7n, 500]]) {
const r = settleRedemption({
shares: 40n * USDC, backerShares: 100n * USDC, costBasisAtomics: 100n * USDC,
navAtomics: navMul * 100n * USDC, totalShares: 100n * USDC, feeBps,
});
expect(r.netPayout + r.fee).toBe(r.grossPayout);
}
});
});
describe('sharesRedeemableNow — honest partial liquidity', () => {
it('caps redeemable shares at what free USDC can actually pay', () => {
// NAV 200 USDC across 100 shares (price 2.0), only 50 USDC liquid.
// 50 USDC pays for 25 shares-worth.
const n = sharesRedeemableNow({
requestedShares: 100n * USDC, navAtomics: 200n * USDC,
totalShares: 100n * USDC, freeAtomics: 50n * USDC,
});
expect(n).toBe(25n * USDC);
// And that slice's payout never exceeds the free balance.
expect(payoutForShares(n, 200n * USDC, 100n * USDC)).toBeLessThanOrEqual(50n * USDC);
});
it('returns the full request when liquidity is ample', () => {
const n = sharesRedeemableNow({
requestedShares: 10n * USDC, navAtomics: 100n * USDC,
totalShares: 100n * USDC, freeAtomics: 100n * USDC,
});
expect(n).toBe(10n * USDC);
});
it('returns 0 with no free liquidity', () => {
expect(sharesRedeemableNow({ requestedShares: 10n * USDC, navAtomics: 100n * USDC, totalShares: 100n * USDC, freeAtomics: 0n })).toBe(0n);
});
});
describe('drawdown circuit breaker', () => {
it('is 0 at or above the peak', () => {
expect(drawdownBps(100n * USDC, 100n * USDC)).toBe(0);
expect(drawdownBps(100n * USDC, 120n * USDC)).toBe(0);
});
it('measures the drop from peak in bps', () => {
expect(drawdownBps(100n * USDC, 75n * USDC)).toBe(2500); // 25% down
expect(drawdownBps(100n * USDC, 90n * USDC)).toBe(1000); // 10% down
});
it('trips exactly at the threshold and beyond', () => {
expect(isDrawdownBreached(100n * USDC, 75n * USDC, 2500)).toBe(true);
expect(isDrawdownBreached(100n * USDC, 76n * USDC, 2500)).toBe(false);
expect(isDrawdownBreached(100n * USDC, 50n * USDC, 2500)).toBe(true);
});
it('a halted over-limit loss: a trade that drops NAV past the cap is caught', () => {
const peak = 1_000n * USDC;
const maxBps = 2000; // 20% max drawdown
const navAfterBadTrade = 700n * USDC; // 30% down
expect(isDrawdownBreached(peak, navAfterBadTrade, maxBps)).toBe(true);
});
it('never trips when disabled (max 0)', () => {
expect(isDrawdownBreached(100n * USDC, 1n, 0)).toBe(false);
});
});
describe('caps and budgets', () => {
it('per-backer cap blocks an over-cap deposit, allows within', () => {
expect(depositExceedsCap(800n * USDC, 300n * USDC, 1000n * USDC)).toBe(true);
expect(depositExceedsCap(800n * USDC, 200n * USDC, 1000n * USDC)).toBe(false);
expect(depositExceedsCap(800n * USDC, 300n * USDC, null)).toBe(false); // no cap
});
it('per-trade ceiling', () => {
expect(tradeExceedsPerTrade(60n * USDC, 50n * USDC)).toBe(true);
expect(tradeExceedsPerTrade(50n * USDC, 50n * USDC)).toBe(false);
});
it('rolling daily budget', () => {
expect(tradeExceedsDailyBudget(400n * USDC, 200n * USDC, 500n * USDC)).toBe(true);
expect(tradeExceedsDailyBudget(300n * USDC, 200n * USDC, 500n * USDC)).toBe(false);
});
});
describe('peak roll + roi + conversions', () => {
it('peak only ratchets up', () => {
expect(nextPeak(100n * USDC, 120n * USDC)).toBe(120n * USDC);
expect(nextPeak(100n * USDC, 80n * USDC)).toBe(100n * USDC);
});
it('roi bps tracks share price vs par', () => {
expect(roiBps(150n * USDC, 100n * USDC)).toBe(5000); // +50%
expect(roiBps(80n * USDC, 100n * USDC)).toBe(-2000); // -20%
expect(roiBps(0n, 0n)).toBe(0);
});
it('usdc <-> atomics round-trips for clean values', () => {
expect(usdcToAtomics(12.5)).toBe(12_500_000n);
expect(atomicsToUsdc(12_500_000n)).toBe(12.5);
expect(usdcToAtomics(-5)).toBe(0n);
});
});
describe('drawdown breaker tracks SHARE PRICE, not raw NAV', () => {
// The breaker must measure NAV-per-share so capital flows (deposits/redemptions)
// never falsely trip it — only real trading losses do.
it('a deposit moves NAV but not share price → no false drawdown', () => {
let total = sharesForDeposit(100n * USDC, 0n, 0n); // 100 shares @ par
const priceBefore = sharePriceE6(100n * USDC, total);
// Second backer deposits 100 at the same price.
const minted = sharesForDeposit(100n * USDC, 100n * USDC, total);
total += minted;
const priceAfter = sharePriceE6(200n * USDC, total);
expect(priceAfter).toBe(priceBefore); // price unchanged by the deposit
const peak = nextPeak(priceBefore, priceAfter);
expect(isDrawdownBreached(peak, priceAfter, 2500)).toBe(false);
});
it('a redemption moves NAV but not share price → no false drawdown', () => {
const total = sharesForDeposit(200n * USDC, 0n, 0n); // 200 shares @ par
const peak = sharePriceE6(200n * USDC, total);
// A backer redeems half: 100 shares burned, 100 USDC leaves → NAV 100, shares 100.
const priceAfter = sharePriceE6(100n * USDC, total - 100n * USDC);
expect(priceAfter).toBe(peak); // still par — no loss
expect(isDrawdownBreached(peak, priceAfter, 2500)).toBe(false);
});
it('a losing trade DOES drop share price and trips the breaker', () => {
const total = 100n * USDC;
const peak = sharePriceE6(100n * USDC, total); // par
const priceAfterLoss = sharePriceE6(70n * USDC, total); // 30% trading loss
expect(isDrawdownBreached(peak, priceAfterLoss, 2500)).toBe(true);
});
});
describe('end-to-end lifecycle conservation', () => {
it('deposit → gain → two redemptions never overpays the vault', () => {
let totalShares = 0n;
// Alice deposits 100 at par.
const aliceShares = sharesForDeposit(100n * USDC, 0n, totalShares);
totalShares += aliceShares;
let aliceBasis = 100n * USDC;
// Bob deposits 100 at par (NAV is 100 before his deposit).
const bobShares = sharesForDeposit(100n * USDC, 100n * USDC, totalShares);
totalShares += bobShares;
let bobBasis = 100n * USDC;
// The agent trades the 200 USDC up to 300 USDC NAV (+50%).
let nav = 300n * USDC;
// Track real custody: only the NET payout leaves the wallet; the fee stays
// in the vault as owner-accruable, and is excluded from backer NAV.
let vaultBalance = nav;
let accruedFee = 0n;
// Alice redeems everything.
const aliceOut = settleRedemption({
shares: aliceShares, backerShares: aliceShares, costBasisAtomics: aliceBasis,
navAtomics: vaultBalance - accruedFee, totalShares, feeBps: 1000,
});
vaultBalance -= aliceOut.netPayout; // only the net leaves the wallet
accruedFee += aliceOut.fee; // fee retained, owner-claimable
totalShares -= aliceShares;
// Bob redeems everything against backer-NAV (vault balance minus owner fee).
const bobOut = settleRedemption({
shares: bobShares, backerShares: bobShares, costBasisAtomics: bobBasis,
navAtomics: vaultBalance - accruedFee, totalShares, feeBps: 1000,
});
vaultBalance -= bobOut.netPayout;
accruedFee += bobOut.fee;
// Both backers gained symmetrically: 150 gross, 145 net (10% fee on 50 gain).
expect(aliceOut.netPayout).toBe(145n * USDC);
expect(bobOut.netPayout).toBe(145n * USDC);
// The vault never pays more than it holds, and ends with exactly the owner fees.
expect(vaultBalance).toBe(accruedFee);
expect(accruedFee).toBe(10n * USDC);
expect(vaultBalance).toBeGreaterThanOrEqual(0n);
});
});
describe('parseAmountInput (the HTTP boundary guard)', () => {
it('accepts the shapes a real caller sends', () => {
expect(parseAmountInput('2500000')).toBe(2_500_000n);
expect(parseAmountInput(2_500_000)).toBe(2_500_000n);
expect(parseAmountInput(2_500_000n)).toBe(2_500_000n);
expect(parseAmountInput(' 2500000 ')).toBe(2_500_000n);
expect(parseAmountInput('0')).toBe(0n);
// A decimal tail truncates down, never up into funds that aren't there.
expect(parseAmountInput('2500000.99')).toBe(2_500_000n);
});
it('returns null for anything BigInt() would throw on, so the handler can answer 400', () => {
for (const bad of ['abc', '', ' ', '1e6', '0x10', '1,000', '-5', -5, NaN, Infinity, null, undefined, {}, [], true]) {
expect(parseAmountInput(bad)).toBeNull();
}
});
});
describe('clampTermBps', () => {
it('clamps into the term bound and rounds to a whole bps', () => {
expect(clampTermBps(9999, TERM_BOUNDS.performanceFeeBps)).toBe(5000);
expect(clampTermBps(-1, TERM_BOUNDS.performanceFeeBps)).toBe(0);
expect(clampTermBps(1234.6, TERM_BOUNDS.performanceFeeBps)).toBe(1235);
expect(clampTermBps(0, TERM_BOUNDS.maxDrawdownBps)).toBe(100);
expect(clampTermBps(99_999, TERM_BOUNDS.maxDrawdownBps)).toBe(9000);
});
it('returns null (never NaN) for a value that is not a number', () => {
expect(clampTermBps('abc', TERM_BOUNDS.performanceFeeBps)).toBeNull();
expect(clampTermBps(NaN, TERM_BOUNDS.maxDrawdownBps)).toBeNull();
expect(clampTermBps(Infinity, TERM_BOUNDS.maxDrawdownBps)).toBeNull();
});
});