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
// Robinhood Portfolios: the shared data layer behind /api/v1/hood-portfolios/*.
//
// Robinhood Portfolios turns a sentence into a portfolio: a person describes what they want
// exposure to, a screen ranks Robinhood Chain's whole token universe against
// it, and the result is a basket with target weights that a vault holds in kind
// and rebalances on a published schedule.
//
// This module owns the parts of that which are not the chain:
//
// • the universe = data/hood-portfolios-universe.json, refreshed by
// `npm run hood:universe`, re-priced live
// here from DexScreener + Chainlink on every read
// • the screen = a real LLM call through api/_lib/llm.js's
// free-first provider chain, constrained to the
// universe and validated against it afterwards
// • the manifest = canonical JSON + keccak256, so the document a
// user is shown hashes to the value that gets
// committed on-chain by PortfolioRegistry
// • valuation = NAV from live prices, refusing to answer rather
// than under-reporting when a leg is unpriceable
//
// Price history and backtesting live next door in hood-portfolios-history.js and
// hood-portfolios-backtest.js, because both are about time rather than about now.
//
// Nothing here invents a number. Where a price genuinely does not exist (a
// memecoin with no live pool, an equity feed that stopped updating when the US
// market closed) the field is null and the caller is told why, because the
// whole product depends on being able to tell the difference between "this is
// worth zero" and "nobody knows what this is worth right now".
import { readFileSync } from 'node:fs';
import path from 'node:path';
import { keccak256, toHex } from 'viem';
import { cacheWrap } from './cache.js';
import { llmComplete } from './llm.js';
import {
chainlinkSnapshot,
dexSnapshot,
publicClient,
stockRegistry,
} from './robinhood.js';
export const CHAIN_ID = 4663;
export const POOL_MANAGER = '0x8366a39CC670B4001A1121B8F6A443A643e40951';
export const USDG = '0x5fc5360d0400a0fd4f2af552add042d716f1d168';
/** The three classes a manifest tags each constituent with. */
export const ASSET_CLASSES = ['rwa-equity', 'crypto-major', 'crypto-native', 'stablecoin'];
/** A constituent must have at least this much on-chain liquidity to be selectable. */
export const MIN_CONSTITUENT_LIQUIDITY_USD = 25_000;
/** Bounds on a generated basket. Wide enough to be useful, narrow enough to be a portfolio. */
export const MIN_CONSTITUENTS = 3;
export const MAX_CONSTITUENTS = 12;
/** No single constituent may exceed this share of a generated portfolio. */
export const MAX_WEIGHT_BPS = 3_500;
// ── The universe ────────────────────────────────────────────────────────────
let _universe = null;
/** The committed universe snapshot: every token that has ever had a v4 pool, plus every Stock Token. */
export function universeSnapshot() {
if (_universe) return _universe;
const file = path.join(process.cwd(), 'data', 'hood-portfolios-universe.json');
_universe = JSON.parse(readFileSync(file, 'utf8'));
return _universe;
}
/**
* The universe re-priced from live sources.
*
* The committed snapshot fixes WHICH tokens exist (that needs ~120 archival log
* queries and cannot be done per request); the prices, liquidity and volume on
* top of it are read live so nothing a user sees is a stale number from
* whenever the file was last built.
*/
export async function liveUniverse({ minLiquidityUsd = 0, classes = null, limit = 0 } = {}) {
return cacheWrap(`hp:universe:${minLiquidityUsd}:${classes?.join(',') || 'all'}:${limit}`, 30, async () => {
const snap = universeSnapshot();
const addresses = snap.tokens.map((t) => t.address);
const [dex, nav] = await Promise.all([dexSnapshot(addresses), chainlinkSnapshot().catch(() => ({}))]);
// `chainlinkSnapshot()` keys by lower-case token address and returns
// { symbol, priceUsd, updatedAt, uiMultiplier, totalSupply }. Its answers are
// ALREADY multiplier-adjusted, so `uiMultiplier` must never be applied on top
// of `priceUsd`; it is returned only for raw-balance arithmetic.
const navByAddress = {};
for (const [addr, row] of Object.entries(nav || {})) navByAddress[addr.toLowerCase()] = row;
let rows = snap.tokens.map((t) => {
const pair = dex[t.address] || null;
const feed = navByAddress[t.address] || null;
const dexUsd = pair?.priceUsd ? Number(pair.priceUsd) : null;
const navUsd = feed?.priceUsd != null ? Number(feed.priceUsd) : null;
return {
address: t.address,
symbol: t.symbol,
name: t.name,
decimals: t.decimals,
assetClass: t.assetClass,
feed: t.feed,
// Ticker squatting is rife on this chain (12 contracts call
// themselves USDG). `canonical` is resolved once at build time by
// contract address, never by symbol, and only canonical tokens are
// ever offered to the screen.
canonical: t.canonical !== false,
symbolPeers: t.symbolPeers ?? 0,
// The DEX mid is the price a portfolio can actually transact at on this
// chain, so it leads. The equity feed is the reference it is compared to.
priceUsd: dexUsd ?? navUsd,
dexPriceUsd: dexUsd,
navPriceUsd: navUsd,
navUpdatedAt: feed?.updatedAt != null ? Number(feed.updatedAt) : null,
premiumPct: dexUsd != null && navUsd ? ((dexUsd - navUsd) / navUsd) * 100 : null,
liquidityUsd: pair?.liquidity?.usd ?? 0,
volume24hUsd: pair?.volume?.h24 ?? 0,
change24hPct: pair?.priceChange?.h24 ?? null,
dexId: pair?.dexId ?? null,
pairAddress: pair?.pairAddress ?? null,
};
});
if (classes?.length) rows = rows.filter((r) => classes.includes(r.assetClass));
if (minLiquidityUsd > 0) rows = rows.filter((r) => r.liquidityUsd >= minLiquidityUsd);
rows.sort((a, b) => b.liquidityUsd - a.liquidityUsd);
if (limit > 0) rows = rows.slice(0, limit);
return {
chainId: CHAIN_ID,
generatedAtBlock: snap.generatedAtBlock,
universeBuiltAt: snap.generatedAt,
pricedAt: new Date().toISOString(),
count: rows.length,
tokens: rows,
};
});
}
/**
* Everything a portfolio is allowed to hold.
*
* Three conditions, and the third is the one that is easy to forget: real
* liquidity, a price we can actually read, and a symbol that belongs to this
* contract rather than one it is impersonating. Without the last, a screen shown
* only symbols and liquidity would pick the deepest "USDG" on the chain, which
* is not the real one.
*/
export async function selectableUniverse() {
const u = await liveUniverse({ minLiquidityUsd: MIN_CONSTITUENT_LIQUIDITY_USD });
const tokens = u.tokens.filter((t) => t.canonical && t.priceUsd != null && t.priceUsd > 0);
return { ...u, count: tokens.length, tokens };
}
// ── The manifest ────────────────────────────────────────────────────────────
/**
* Canonical JSON: object keys sorted at every depth, no insignificant whitespace.
*
* The manifest's hash is committed on-chain, so two parties who serialise the
* same document must produce the same bytes. JSON.stringify's key order follows
* insertion order, which differs between the generator and a client that
* round-tripped the document, so ordering is imposed rather than assumed.
*/
export function canonicalise(value) {
if (value === null || typeof value !== 'object') return JSON.stringify(value);
if (Array.isArray(value)) return `[${value.map(canonicalise).join(',')}]`;
const keys = Object.keys(value).sort();
return `{${keys.map((k) => `${JSON.stringify(k)}:${canonicalise(value[k])}`).join(',')}}`;
}
/** keccak256 of the canonical serialisation: the exact value `PortfolioRegistry.publish` commits. */
export function manifestHash(manifest) {
return keccak256(toHex(canonicalise(manifest)));
}
/** The schema version every manifest this build produces declares. */
export const MANIFEST_VERSION = '1.0.0';
/**
* Assemble the manifest document from a screen result.
*
* Everything needed to re-run the screen and check it goes in: the prompt, the
* universe snapshot it ran against, the filters, and every constituent's price
* and liquidity at selection time. That is what makes the screen auditable
* without anybody having to be trusted. The claim "this basket follows from
* this prompt" is not enforceable on-chain, but "this basket follows from this
* recorded input" is checkable by anyone who re-runs it.
*/
export function buildManifest({ prompt, screen, universe, createdAt = new Date().toISOString() }) {
return {
version: MANIFEST_VERSION,
chainId: CHAIN_ID,
createdAt,
prompt,
name: screen.name,
symbol: screen.symbol,
thesis: screen.thesis,
rebalance: {
intervalDays: screen.rebalanceDays,
// The vault's own timelock and auction window, restated here so the manifest
// fully describes the product a holder is buying.
proposalDelayHours: 24,
auctionHours: 6,
},
eligibility: {
minLiquidityUsd: MIN_CONSTITUENT_LIQUIDITY_USD,
maxWeightBps: MAX_WEIGHT_BPS,
minConstituents: MIN_CONSTITUENTS,
maxConstituents: MAX_CONSTITUENTS,
},
universe: {
builtAt: universe.universeBuiltAt,
atBlock: universe.generatedAtBlock,
consideredCount: universe.count,
source: 'Uniswap v4 Initialize events on chain 4663, unioned with the Stock Token registry',
},
constituents: screen.constituents.map((c) => ({
address: c.address,
symbol: c.symbol,
assetClass: c.assetClass,
weightBps: c.weightBps,
rationale: c.rationale,
priceUsdAtSelection: c.priceUsd,
liquidityUsdAtSelection: c.liquidityUsd,
oracle: c.feed ? { kind: 'chainlink', feed: c.feed } : { kind: 'dex-mid', pair: c.pairAddress },
})),
};
}
// ── The screen ──────────────────────────────────────────────────────────────
const SCREEN_SYSTEM = `You build investment portfolios from a token universe on Robinhood Chain (chain 4663).
The universe spans three asset classes and you may mix them freely in one portfolio:
rwa-equity tokenized equities and ETFs (NVDA, SPY, AAPL, GLD...). These track real
companies and only trade against a real-world price when US markets are open.
crypto-major large liquid crypto (WETH).
crypto-native tokens native to this chain, including memecoins. High risk, high variance.
stablecoin USD stablecoins. Use only as ballast, never as the thesis.
Rules you must follow exactly:
- Choose ONLY tokens from the supplied universe. Never invent an address or a symbol.
- Choose between 3 and 12 constituents.
- weightBps are integers that sum to EXACTLY 10000.
- No single constituent may exceed 3500 bps.
- Prefer deeper liquidity when two candidates serve the thesis equally well.
- rebalanceDays is one of 7, 14, 30, 90.
- Every constituent needs a one-sentence rationale tying it to the user's prompt specifically.
Never write filler like "provides diversification" or "strong fundamentals".
- thesis is two sentences: what this portfolio is a bet on, and what would make it wrong.
- name is a short human title. symbol is 3-6 uppercase letters, no spaces.
Reply with ONE JSON object and nothing else:
{"name":"...","symbol":"...","thesis":"...","rebalanceDays":30,
"constituents":[{"address":"0x...","weightBps":2500,"rationale":"..."}]}`;
function universeDigest(tokens, cap = 120) {
return tokens
.slice(0, cap)
.map(
(t) =>
`${t.address} ${t.symbol || '?'} class=${t.assetClass} price=${
t.priceUsd != null ? `$${Number(t.priceUsd).toPrecision(6)}` : 'n/a'
} liq=$${Math.round(t.liquidityUsd).toLocaleString('en-US')} vol24=$${Math.round(
t.volume24hUsd,
).toLocaleString('en-US')} chg24=${t.change24hPct != null ? `${t.change24hPct}%` : 'n/a'}`,
)
.join('\n');
}
function extractJson(text) {
const trimmed = String(text || '').trim();
// Models wrap JSON in prose or fences often enough that finding the object is
// part of parsing it, not a workaround.
const fenced = trimmed.match(/```(?:json)?\s*([\s\S]*?)```/);
const candidate = fenced ? fenced[1] : trimmed;
const start = candidate.indexOf('{');
const end = candidate.lastIndexOf('}');
if (start === -1 || end <= start) throw new Error('the screen did not return a JSON object');
return JSON.parse(candidate.slice(start, end + 1));
}
export class ScreenError extends Error {
constructor(message, detail) {
super(message);
this.name = 'ScreenError';
this.detail = detail;
}
}
/**
* Scale arbitrary positive weights onto integers that sum to exactly `total`,
* with no entry above `max` or below 1.
*
* Two passes, because doing it in one is where this went wrong the first time.
*
* The **water-filling** pass handles the cap. Naively scaling and then clamping
* loses whatever the clamp removed, so a set like 9999/1/1 collapses to
* 3500/1/1 and sums to 3502 rather than 10000. Instead, any entry that would
* exceed `max` is pinned there and its excess is redistributed proportionally
* across the entries that are still under the cap, repeating until nothing new
* pins. That converges because each round pins at least one more entry.
*
* The **largest-remainder** pass handles the rounding. Rounding each share
* independently leaves a remainder of up to n-1 basis points, so the entries are
* floored and the leftover is handed out one at a time, largest fractional part
* first, skipping anything already at the cap. The result sums to `total`
* exactly, which is what `feeSplit`-style arithmetic downstream depends on.
*
* Feasibility is the caller's: `total` must be reachable, i.e. entries.length *
* max >= total. With at least 3 constituents and a 3500bps cap, 10500 >= 10000.
*/
export function normaliseWeights(raw, max, total = 10_000) {
const n = raw.length;
if (n === 0) return [];
if (n * max < total) {
throw new ScreenError('the weight cap cannot be satisfied by this many constituents', {
constituents: n,
maxWeightBps: max,
total,
});
}
let values = raw.map((w) => (Number.isFinite(w) && w > 0 ? Number(w) : 1));
const pinned = new Array(n).fill(false);
for (;;) {
const pinnedTotal = pinned.reduce((s, p, i) => (p ? s + values[i] : s), 0);
const budget = total - pinnedTotal;
const freeSum = values.reduce((s, v, i) => (pinned[i] ? s : s + v), 0);
// Every free entry being zero can only happen if the caller passed no
// usable weights at all; spread the budget evenly rather than dividing by 0.
const scale = freeSum > 0 ? budget / freeSum : 0;
let newlyPinned = false;
for (let i = 0; i < n; ++i) {
if (pinned[i]) continue;
const scaled = freeSum > 0 ? values[i] * scale : budget / values.filter((_, j) => !pinned[j]).length;
if (scaled > max) {
values[i] = max;
pinned[i] = true;
newlyPinned = true;
}
}
if (newlyPinned) continue;
for (let i = 0; i < n; ++i) {
if (!pinned[i]) values[i] = freeSum > 0 ? values[i] * scale : budget / n;
}
break;
}
const floors = values.map((v) => Math.max(1, Math.min(max, Math.floor(v))));
let remainder = total - floors.reduce((a, b) => a + b, 0);
if (remainder > 0) {
const order = values
.map((v, i) => ({ i, frac: v - Math.floor(v) }))
.sort((a, b) => b.frac - a.frac);
for (let pass = 0; remainder > 0 && pass < n + 2; ++pass) {
for (const { i } of order) {
if (remainder === 0) break;
if (floors[i] < max) {
floors[i] += 1;
remainder -= 1;
}
}
}
} else if (remainder < 0) {
// Only reachable when flooring to a minimum of 1 pushed the total above
// `total`, which needs a very large n; take back from the largest first.
const order = floors.map((v, i) => ({ i, v })).sort((a, b) => b.v - a.v);
for (let pass = 0; remainder < 0 && pass < n + 2; ++pass) {
for (const { i } of order) {
if (remainder === 0) break;
if (floors[i] > 1) {
floors[i] -= 1;
remainder += 1;
}
}
}
}
return floors;
}
/**
* Normalise and validate a raw screen result against the universe.
*
* A language model is a ranking engine here, never an authority: everything it
* returns is checked against the universe it was given, and anything it made up
* is dropped rather than repaired into something plausible. Weights are the one
* thing that IS repaired, because "sum to exactly 10000" is an arithmetic
* property of a set the model chose correctly, not a judgement call.
*/
export function validateScreen(raw, tokens) {
const byAddress = new Map(tokens.map((t) => [t.address.toLowerCase(), t]));
const seen = new Set();
const picked = [];
for (const c of Array.isArray(raw?.constituents) ? raw.constituents : []) {
const addr = String(c?.address || '').toLowerCase();
const token = byAddress.get(addr);
if (!token || seen.has(addr)) continue;
const weight = Number(c?.weightBps);
if (!Number.isFinite(weight) || weight <= 0) continue;
seen.add(addr);
picked.push({
...token,
weightBps: Math.round(weight),
rationale: String(c?.rationale || '').trim() || `Selected for ${String(raw?.name || 'the thesis')}.`,
});
if (picked.length >= MAX_CONSTITUENTS) break;
}
if (picked.length < MIN_CONSTITUENTS) {
throw new ScreenError('the screen did not return enough usable constituents', {
returned: raw?.constituents?.length ?? 0,
usable: picked.length,
minimum: MIN_CONSTITUENTS,
});
}
const weights = normaliseWeights(picked.map((c) => c.weightBps), MAX_WEIGHT_BPS);
for (let i = 0; i < picked.length; ++i) picked[i].weightBps = weights[i];
picked.sort((a, b) => b.weightBps - a.weightBps);
const allowedIntervals = [7, 14, 30, 90];
const days = Number(raw?.rebalanceDays);
const symbol = String(raw?.symbol || '')
.toUpperCase()
.replace(/[^A-Z]/g, '')
.slice(0, 6);
return {
name: String(raw?.name || '').trim().slice(0, 64) || 'Generated Portfolio',
symbol: symbol.length >= 3 ? symbol : 'FLTCHR',
thesis: String(raw?.thesis || '').trim().slice(0, 600),
rebalanceDays: allowedIntervals.includes(days) ? days : 30,
constituents: picked,
};
}
/**
* Run the screen: a prompt in, a validated basket out.
*
* The model never sees the whole universe. It sees the tokens that are actually
* holdable (real liquidity, a readable price) ordered by depth, which is both
* what fits in a prompt and what a portfolio could survive rebalancing into.
*/
export async function generatePortfolio({ prompt, universe = null, track = null }) {
const u = universe || (await selectableUniverse());
if (!u.tokens.length) {
throw new ScreenError('no token in the universe currently has enough liquidity to be held', {
minLiquidityUsd: MIN_CONSTITUENT_LIQUIDITY_USD,
});
}
const user = `User's prompt: ${prompt}
Universe (${Math.min(u.tokens.length, 120)} most liquid of ${u.tokens.length} holdable tokens on Robinhood Chain):
${universeDigest(u.tokens)}`;
const completion = await llmComplete({
system: SCREEN_SYSTEM,
user,
maxTokens: 1800,
timeoutMs: 45_000,
track,
});
let raw;
try {
raw = extractJson(completion.text);
} catch (err) {
throw new ScreenError('the screen returned a response that was not valid JSON', {
provider: completion.provider,
model: completion.model,
reason: String(err.message || err),
});
}
const screen = validateScreen(raw, u.tokens);
const manifest = buildManifest({ prompt, screen, universe: u });
return {
screen,
manifest,
manifestHash: manifestHash(manifest),
provider: completion.provider,
model: completion.model,
universeConsidered: u.tokens.length,
};
}
// ── Valuation ───────────────────────────────────────────────────────────────
/**
* Value a basket at current prices.
*
* `unpriceable` is the field that matters. A portfolio whose equity leg's feed
* went stale over a weekend, or whose memecoin leg lost its only pool, has a
* NAV that is not merely uncertain but unknowable, and saying so is the whole
* difference between an index product and a number generator.
*/
export function valueBasket(constituents, priceByAddress) {
let total = 0;
const legs = [];
const unpriceable = [];
for (const c of constituents) {
const price = priceByAddress.get(String(c.address).toLowerCase());
const weight = c.weightBps / 10_000;
if (price == null || !(price > 0)) {
unpriceable.push({ address: c.address, symbol: c.symbol, reason: 'no live price on this chain' });
legs.push({ ...c, priceUsd: null, valueUsd: null });
continue;
}
const valueUsd = weight * price;
total += valueUsd;
legs.push({ ...c, priceUsd: price, valueUsd });
}
return {
legs,
unpriceable,
// A NAV computed while a leg is unpriceable would be a smaller number
// presented as a complete one, so it is withheld rather than approximated.
navUsdPerUnit: unpriceable.length === 0 ? total : null,
pricedLegs: legs.length - unpriceable.length,
totalLegs: legs.length,
};
}
/** Cheap health line for the status surfaces: is the chain answering, and how fresh is the universe. */
export async function portfoliosHealth() {
return cacheWrap('hp:health', 20, async () => {
const snap = universeSnapshot();
let head = null;
let chainOk = false;
try {
head = Number(await publicClient(false).getBlockNumber());
chainOk = true;
} catch {
chainOk = false;
}
const stocks = stockRegistry();
return {
chainId: CHAIN_ID,
chainOk,
head,
universeBuiltAt: snap.generatedAt,
universeAtBlock: snap.generatedAtBlock,
universeTokens: snap.tokenCount,
equityRegistrySize: stocks.tokenCount,
equitiesWithFeeds: stocks.feedCount,
};
});
}