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
/**
* Tokenized 3D — mint a generated/owned GLB as a Metaplex Core NFT whose media
* is a live, interactive 3D viewer, with baked provenance and enforced royalties.
* ---------------------------------------------------------------------------
* The payoff of infrastructure that already coexists in this repo: text→3D→rig
* generation, R2 avatar storage, and Solana signing rails. This module ties them
* together so a generated avatar becomes ownable, transferable, composable
* on-chain property.
*
* Flow (mintTokenized3dAsset):
* 1. Resolve the source GLB (an owned avatar or a supplied GLB URL) and the
* recipient wallet (OAuth-linked or supplied).
* 2. CLAIM an idempotency row *before* any on-chain call — the double-mint
* guard. A second call with the same key reads back the winner's mint.
* 3. Promote media to durable storage: copy the GLB + a fresh thumbnail into a
* tokenize-namespaced R2 key (so the NFT media never moves even if the
* source avatar is later deleted), and pin to IPFS when configured.
* 4. Build + upload Metaplex-compliant metadata (GLB under animation_url).
* 5. Mint a Core asset with an enforced Royalties plugin (capped), owned by the
* recipient, signed + paid by the three.ws collection authority.
* 6. Persist the launch record (mint, tx, provenance) and return the mint +
* explorer + viewer links.
*
* Heavy Solana/Umi + render deps are imported here (not in the pure metadata
* module) so callers that only need metadata shape stay dependency-light.
*
* $THREE-policy clean: $THREE is the only coin named. SOL is the Core rent +
* royalty rail (a settlement mechanic); no other mint is ever referenced.
*/
import { createUmi } from '@metaplex-foundation/umi-bundle-defaults';
import { mplCore, create, fetchAsset, ruleSet } from '@metaplex-foundation/mpl-core';
import {
generateSigner,
publicKey as umiPublicKey,
signerIdentity,
} from '@metaplex-foundation/umi';
import bs58 from 'bs58';
import { sql } from './db.js';
import { env } from './env.js';
import { collectionAuthoritySigner, collectionAuthorityAddress } from './solana-collection.js';
import { solanaConnection } from './solana/connection.js';
import { explorerTxUrl } from './avatar-wallet.js';
import { putObject, publicUrl } from './r2.js';
import { pinToIPFS, ipfsPinningConfigured } from './ipfs-pin.js';
import { fetchSafePublicUrl } from './ssrf-guard.js';
import { getAvatar, resolveAvatarUrl } from './avatars.js';
import { getUserSolanaWallets } from './nft-gate.js';
import { resolveRenderParams, renderAvatarScene } from './avatar-render.js';
import {
buildTokenized3dMetadata,
viewerLinkFor,
clampSellerFeeBps,
deriveIdempotencyKey,
TOKENIZE_3D_ROYALTY_CAP_BPS,
} from './tokenize-3d-metadata.js';
import { agentIdForAvatar, writeAssetProvenance } from './asset-provenance.js';
import { computeRemixSplit } from './remix-royalty.js';
import { resolvePayoutKeyBase58 } from './remix-settlement.js';
import { transferSolanaUSDC } from './solana-transfer.js';
import { SOLANA_USDC_MINT } from '../payments/_config.js';
import { priceFor } from './pump-pricing.js';
export { TOKENIZE_3D_ROYALTY_CAP_BPS };
/** The x402 price of one mint call, in USDC atomics — single source of truth
* (api/_lib/pump-pricing.js), reused so the remix-royalty split on a mint
* never drifts from what the caller was actually charged. */
function mintPriceAtomics() {
const usd = priceFor('mint_3d_asset')?.amount_usdc;
return usd > 0 ? BigInt(Math.round(usd * 1_000_000)) : 0n;
}
/** Networks we mint on. Devnet is the default; mainnet is explicit. */
export const TOKENIZE_3D_NETWORKS = /** @type {const} */ (['mainnet', 'devnet']);
/**
* Resolve the minting network. Devnet-default is deliberate: real value only
* moves when a caller explicitly asks for mainnet.
* @param {string|null|undefined} preferred
* @returns {'mainnet'|'devnet'}
*/
export function resolveNetwork(preferred) {
return preferred === 'mainnet' ? 'mainnet' : 'devnet';
}
function rpcForNetwork(network) {
return network === 'devnet' ? env.SOLANA_RPC_URL_DEVNET : env.SOLANA_RPC_URL;
}
function isValidBase58Pubkey(addr) {
try {
umiPublicKey(addr);
return true;
} catch {
return false;
}
}
function encodeSignature(sig) {
return typeof sig === 'string' ? sig : bs58.encode(sig);
}
function assetExplorerUrl(mint, network) {
const cluster = network === 'devnet' ? '?cluster=devnet' : '';
return `https://solscan.io/token/${mint}${cluster}`;
}
// ── Source + owner resolution ────────────────────────────────────────────────
/**
* Resolve the GLB source into { glbUrl, name, sourceAvatarId, provenance } and
* the durable-storage bytes fetcher. Accepts either an owned avatar id or a raw
* GLB URL.
*
* @param {object} p
* @param {string} [p.avatarId]
* @param {string} [p.glbUrl]
* @param {string|null} p.requesterId OAuth userId (visibility gate for avatars)
* @param {string} [p.name]
*/
async function resolveSource({ avatarId, glbUrl, requesterId, name }) {
if (avatarId) {
const avatar = await getAvatar({ id: avatarId, requesterId });
if (!avatar) {
throw Object.assign(new Error('avatar not found'), { status: 404, code: 'not_found' });
}
const urlInfo = await resolveAvatarUrl(avatar);
if (!urlInfo?.url) {
throw Object.assign(new Error('this avatar has no model to tokenize yet'), {
status: 409,
code: 'no_model',
});
}
const meta = avatar.source_meta || {};
return {
sourceUrl: urlInfo.url,
sourceAvatarId: avatar.id,
name: name || avatar.name || 'three.ws 3D asset',
description: avatar.description || '',
parentAvatarId: avatar.parent_avatar_id || null,
provenance: {
prompt: meta.source_prompt || null,
generationModel: meta.generator || meta.model || null,
generationProvider: meta.provider || (meta.generator ? 'three.ws' : null),
},
};
}
if (glbUrl) {
if (!/^https?:\/\//i.test(glbUrl)) {
throw Object.assign(new Error('glb_url must be an absolute http(s) URL'), {
status: 400,
code: 'validation_error',
});
}
return {
sourceUrl: glbUrl,
sourceAvatarId: null,
name: name || 'three.ws 3D asset',
description: '',
parentAvatarId: null,
provenance: { prompt: null, generationModel: null, generationProvider: null },
};
}
throw Object.assign(new Error('provide either avatar_id or glb_url'), {
status: 400,
code: 'validation_error',
});
}
/**
* Resolve the NFT recipient wallet: an explicitly supplied base58 address, else
* the OAuth user's linked Solana wallet.
*/
async function resolveOwnerWallet({ ownerWallet, requesterId }) {
if (ownerWallet) {
if (!isValidBase58Pubkey(ownerWallet)) {
throw Object.assign(new Error('owner_wallet is not a valid Solana address'), {
status: 400,
code: 'validation_error',
});
}
return ownerWallet;
}
if (requesterId) {
const wallets = await getUserSolanaWallets(requesterId);
if (wallets.length) return wallets[0];
}
throw Object.assign(
new Error('no recipient wallet — connect a Solana wallet (sign in) or pass owner_wallet'),
{ status: 400, code: 'no_wallet' },
);
}
// ── Durable storage promotion ────────────────────────────────────────────────
/**
* Copy the source GLB and a freshly-rendered thumbnail into a tokenize-namespaced
* R2 key so the NFT media is permanent + first-party, and pin both to IPFS when
* a provider is configured. Returns the durable URLs.
*
* @returns {Promise<{ glbUrl: string, imageUrl: string, glbIpfs: string|null, imageIpfs: string|null }>}
*/
async function promoteToDurableStorage({ idempotencyKey, sourceUrl, name }) {
const base = `tokenized/${idempotencyKey}`;
// 1. GLB bytes → durable R2 key.
const glbResp = await fetchSafePublicUrl(sourceUrl, {}, { allowHttp: false });
if (!glbResp.ok) {
throw Object.assign(new Error(`could not fetch source GLB (${glbResp.status})`), {
status: 502,
code: 'source_unreachable',
});
}
const glbBuf = Buffer.from(await glbResp.arrayBuffer());
const glbKey = `${base}/model.glb`;
await putObject({ key: glbKey, body: glbBuf, contentType: 'model/gltf-binary' });
const glbUrl = publicUrl(glbKey);
// 2. Thumbnail — render the model once, store it durably. A 3D NFT needs a
// real image for wallets/marketplaces that don't render glTF.
const { params, error } = resolveRenderParams({
scene: 'full-body',
size: 1024,
bg: '#0b0b0f',
format: 'png',
});
if (error) {
throw Object.assign(new Error(`thumbnail params invalid: ${error.message}`), {
status: 400,
code: 'render_params',
});
}
let png;
try {
({ png } = await renderAvatarScene({
glbUrl,
width: params.width,
height: params.height,
background: params.bg,
posePresetId: params.posePresetId,
cameraOrbit: { theta: params.scenePreset.theta, phi: params.scenePreset.phi, radius: null },
expression: null,
scenePreset: params.scenePreset,
}));
} catch (err) {
throw Object.assign(
new Error(`could not render a thumbnail for the asset: ${err?.message || 'render failed'}`),
{ status: 502, code: 'thumbnail_failed' },
);
}
const imageKey = `${base}/thumb.png`;
await putObject({ key: imageKey, body: png, contentType: 'image/png' });
const imageUrl = publicUrl(imageKey);
// 3. Optional IPFS permanence copies (best-effort; R2 https is the primary).
let glbIpfs = null;
let imageIpfs = null;
if (ipfsPinningConfigured()) {
try {
const safeName = (name || 'asset').replace(/[^a-z0-9._-]/gi, '_').slice(0, 40);
const [g, i] = await Promise.all([
pinToIPFS(glbBuf, `${safeName}.glb`),
pinToIPFS(png, `${safeName}.png`),
]);
glbIpfs = g?.uri || null;
imageIpfs = i?.uri || null;
} catch (err) {
// Permanence is a bonus; a pin failure must not fail the mint.
console.warn('[tokenize-3d] IPFS pin failed (continuing on R2):', err?.message);
}
}
return { glbUrl, imageUrl, glbIpfs, imageIpfs };
}
async function uploadMetadataJson({ idempotencyKey, metadata }) {
const key = `tokenized/${idempotencyKey}/metadata.json`;
await putObject({
key,
body: Buffer.from(JSON.stringify(metadata)),
contentType: 'application/json',
});
let ipfs = null;
if (ipfsPinningConfigured()) {
try {
ipfs = (await pinToIPFS(Buffer.from(JSON.stringify(metadata)), 'metadata.json'))?.uri || null;
} catch (err) {
console.warn('[tokenize-3d] metadata IPFS pin failed:', err?.message);
}
}
return { uri: publicUrl(key), ipfs };
}
// ── On-chain mint ────────────────────────────────────────────────────────────
/**
* Mint the Core asset with an enforced Royalties plugin. The three.ws collection
* authority is the fee payer + update authority (authority-managed model: the
* holder owns/transfers the asset, three.ws can curate its on-chain metadata);
* the recipient wallet is the owner.
*/
async function mintCoreAsset({ network, ownerWallet, name, metadataUri, royaltyBps, royaltyRecipient }) {
const umi = createUmi(solanaConnection({ url: rpcForNetwork(network), network })).use(mplCore());
const authority = collectionAuthoritySigner(umi);
umi.use(signerIdentity(authority));
const assetSigner = generateSigner(umi);
const { signature } = await create(umi, {
asset: assetSigner,
owner: umiPublicKey(ownerWallet),
name: String(name).slice(0, 32) || '3D Asset',
uri: metadataUri,
plugins: [
{
type: 'Royalties',
basisPoints: royaltyBps,
creators: [{ address: umiPublicKey(royaltyRecipient), percentage: 100 }],
ruleSet: ruleSet('None'),
},
],
}).sendAndConfirm(umi, { confirm: { commitment: 'confirmed' } });
return { mint: assetSigner.publicKey.toString(), signature: encodeSignature(signature) };
}
// ── Public API: mint ─────────────────────────────────────────────────────────
/**
* Default dependency set — real DB + real chain/storage. Tests inject fakes to
* exercise the idempotency guard without touching Solana or R2.
*/
function defaultDeps() {
return {
sql,
resolveSource,
resolveOwnerWallet,
promoteToDurableStorage,
uploadMetadataJson,
mintCoreAsset,
now: () => new Date().toISOString(),
};
}
/**
* Mint a generated/owned GLB as a Metaplex Core 3D NFT.
*
* @param {object} input
* @param {string} [input.avatarId] owned avatar to tokenize
* @param {string} [input.glbUrl] or a GLB URL to tokenize
* @param {string} [input.ownerWallet] recipient (base58); defaults to OAuth wallet
* @param {string|null} [input.requesterId] OAuth userId
* @param {string} [input.name]
* @param {string} [input.description]
* @param {number} [input.sellerFeeBasisPoints] requested royalty (clamped to cap)
* @param {string} [input.royaltyRecipient] wallet royalty routes to (default: owner)
* @param {string} [input.network] 'devnet' (default) | 'mainnet'
* @param {string} [input.parentMint] lineage parent (remix source)
* @param {string} [input.prompt] provenance override
* @param {string} [input.generationModel]
* @param {string} [input.generationProvider]
* @param {string} [input.idempotencyKey] override the derived key
* @param {bigint|number} [input.mintFeeAtomicsCollected] the mint fee ACTUALLY
* collected for this call (USDC atomics) — used only to split a remix
* royalty when parentMint is set. Omit/0 for an OAuth-bypassed call (no fee
* was collected, so nothing is split) — never assume the advertised price
* was paid.
* @param {object} [deps] injected dependencies (testing)
* @returns {Promise<object>} mint result
*/
export async function mintTokenized3dAsset(input, deps = defaultDeps()) {
const network = resolveNetwork(input.network);
const src = await deps.resolveSource({
avatarId: input.avatarId,
glbUrl: input.glbUrl,
requesterId: input.requesterId ?? null,
name: input.name,
});
const ownerWallet = await deps.resolveOwnerWallet({
ownerWallet: input.ownerWallet,
requesterId: input.requesterId ?? null,
});
const royaltyRecipient =
input.royaltyRecipient && isValidBase58Pubkey(input.royaltyRecipient)
? input.royaltyRecipient
: ownerWallet;
const { bps: royaltyBps, capped, requestedBps } = clampSellerFeeBps(input.sellerFeeBasisPoints);
const idempotencyKey =
input.idempotencyKey ||
deriveIdempotencyKey({
ownerWallet,
glbSource: src.sourceAvatarId ? `avatar:${src.sourceAvatarId}` : `url:${src.sourceUrl}`,
network,
creatorUserId: input.requesterId ?? null,
});
const provenance = {
prompt: input.prompt ?? src.provenance.prompt,
generationModel: input.generationModel ?? src.provenance.generationModel,
generationProvider: input.generationProvider ?? src.provenance.generationProvider,
parentMint: input.parentMint ?? null,
};
// ── Claim-first idempotency guard: insert a pending row; a conflict means a
// prior call already owns this key. ──
const [claimed] = await deps.sql`
insert into tokenized_3d_assets
(idempotency_key, network, status, owner_wallet, creator_user_id, source_avatar_id,
parent_mint, name, glb_url, viewer_url, royalty_bps, royalty_recipient, provenance)
values
(${idempotencyKey}, ${network}, 'pending', ${ownerWallet}, ${input.requesterId ?? null},
${src.sourceAvatarId}, ${provenance.parentMint}, ${src.name}, ${src.sourceUrl},
${viewerLinkFor(env.APP_ORIGIN, src.sourceUrl)}, ${royaltyBps}, ${royaltyRecipient},
${JSON.stringify(provenance)}::jsonb)
on conflict (idempotency_key, network) do nothing
returning id, status
`;
let rowId = claimed?.id;
if (!claimed) {
const [existing] = await deps.sql`
select id, status, mint, network, name, glb_url, image_url, viewer_url,
metadata_uri, royalty_bps, royalty_recipient, tx_signature,
provenance_ledger, remix_royalty
from tokenized_3d_assets
where idempotency_key = ${idempotencyKey} and network = ${network}
`;
if (existing?.status === 'minted') {
// Idempotent hit — return the already-minted asset, do NOT mint again.
return formatMintResult(existing, { idempotent: true, capped, requestedBps, royaltyBps });
}
if (existing?.status === 'pending') {
return {
status: 'pending',
idempotent: true,
message: 'A mint for this asset is already in progress. Read it back once it confirms.',
id: existing.id,
network,
};
}
// status === 'failed' → reclaim for a retry (only one winner flips it back).
const [reclaimed] = await deps.sql`
update tokenized_3d_assets
set status = 'pending', mint_error = null, updated_at = now()
where idempotency_key = ${idempotencyKey} and network = ${network} and status = 'failed'
returning id
`;
if (!reclaimed) {
return {
status: 'pending',
idempotent: true,
message: 'A retry for this asset is already in progress.',
id: existing?.id,
network,
};
}
rowId = reclaimed.id;
}
try {
// 1. Durable media.
const media = await deps.promoteToDurableStorage({
idempotencyKey,
sourceUrl: src.sourceUrl,
name: src.name,
});
const viewerUrl = viewerLinkFor(env.APP_ORIGIN, media.glbUrl);
const createdAt = deps.now();
// 2. Metaplex metadata.
const metadata = buildTokenized3dMetadata({
name: src.name,
description: input.description || src.description,
glbUrl: media.glbUrl,
imageUrl: media.imageUrl,
viewerUrl,
glbIpfs: media.glbIpfs,
imageIpfs: media.imageIpfs,
creatorWallet: ownerWallet,
creatorUserId: input.requesterId ?? null,
prompt: provenance.prompt,
generationModel: provenance.generationModel,
generationProvider: provenance.generationProvider,
parentMint: provenance.parentMint,
royaltyBps,
royaltyRecipient,
network,
createdAt,
});
const { uri: metadataUri, ipfs: metadataIpfs } = await deps.uploadMetadataJson({
idempotencyKey,
metadata,
});
// 3. Mint.
const { mint, signature } = await deps.mintCoreAsset({
network,
ownerWallet,
name: src.name,
metadataUri,
royaltyBps,
royaltyRecipient,
});
// 4. Persist the launch record.
const [row] = await deps.sql`
update tokenized_3d_assets
set status = 'minted', mint = ${mint}, tx_signature = ${signature},
glb_url = ${media.glbUrl}, image_url = ${media.imageUrl}, viewer_url = ${viewerUrl},
metadata_uri = ${metadataUri},
provenance = ${JSON.stringify({ ...metadata.properties.provenance, metadata_ipfs: metadataIpfs })}::jsonb,
updated_at = now()
where id = ${rowId}
returning id, status, mint, network, name, glb_url, image_url, viewer_url,
metadata_uri, royalty_bps, royalty_recipient, tx_signature
`;
// 5. Signed provenance on the agent_actions ledger (Prompt 08, task 1) —
// independently verifiable via query_action/list_agent_actions, alongside
// the provenance already baked into the NFT metadata itself. Best-effort:
// only fires when the source avatar has a provisioned agent, and never
// blocks or fails the mint that already succeeded on-chain.
let provenanceLedger = null;
const provenanceAgentId = await agentIdForAvatar(src.sourceAvatarId).catch(() => null);
if (provenanceAgentId) {
const ledgerResult = await writeAssetProvenance({
agentId: provenanceAgentId,
type: 'tokenize_3d.mint',
payload: {
mint,
network,
name: src.name,
prompt: provenance.prompt,
generation_model: provenance.generationModel,
generation_provider: provenance.generationProvider,
parent_mint: provenance.parentMint,
glb_url: media.glbUrl,
viewer_url: viewerUrl,
royalty_bps: royaltyBps,
creator_wallet: ownerWallet,
minted_at: createdAt,
},
sourceSkill: 'tokenize-3d',
}).catch(() => null);
if (ledgerResult?.recorded) {
provenanceLedger = {
action_id: ledgerResult.action_id,
signed: ledgerResult.signed,
signer_address: ledgerResult.signer_address,
digest: ledgerResult.digest,
};
}
}
// 6. Remix royalty on the mint fee (Prompt 08, task 4) — when this mint
// names a parent (a remix/derivative), route the parent creator's
// royalty slice out of the fee actually collected for THIS mint call, a
// real second USDC transfer, same rails as api/_lib/remix-settlement.js.
// Mainnet only (the payout wallet is a real mainnet treasury); a devnet
// remix mint still records durable parent→child lineage but settles
// nothing. An OAuth-bypassed mint (feeAtomicsCollected=0) has nothing to
// split — honestly reported, never a fabricated payout.
let remixRoyalty = null;
if (provenance.parentMint) {
remixRoyalty = await settleOrDeferRemixRoyalty({
sql: deps.sql,
rowId,
parentMint: provenance.parentMint,
network,
feeAtomics: input.mintFeeAtomicsCollected ?? 0n,
defer: input.deferRoyalty,
});
}
if (provenanceLedger || remixRoyalty) {
await deps
.sql`update tokenized_3d_assets set provenance_ledger = ${provenanceLedger ? JSON.stringify(provenanceLedger) : null}::jsonb, remix_royalty = ${remixRoyalty ? JSON.stringify(remixRoyalty) : null}::jsonb, updated_at = now() where id = ${rowId}`
.catch((err) => console.warn('[tokenize-3d] provenance/royalty persist failed:', err?.message));
}
return formatMintResult(row, {
idempotent: false,
capped,
requestedBps,
royaltyBps,
metadataIpfs,
provenanceLedger,
remixRoyalty,
});
} catch (err) {
// Clean failure at the boundary: mark the row failed so the key can retry,
// then surface a sanitized error. Never leak a key/secret.
await deps
.sql`update tokenized_3d_assets set status='failed', mint_error=${String(err?.message || 'mint failed').slice(0, 500)}, updated_at=now() where id=${rowId}`
.catch(() => {});
throw err;
}
}
// ── Remix royalty on a mint ─────────────────────────────────────────────────
/**
* When a mint names a `parent_mint` (it's a derivative of another creator's
* tokenized 3D asset), route that creator's royalty slice out of THIS mint's
* x402 fee — a real second USDC transfer, same split math + payout wallet as
* the forge_creations remix bazaar (api/_lib/remix-royalty.js +
* api/_lib/remix-settlement.js). Every non-paying outcome is reported with an
* honest reason (never a fake "pending"): no such parent, the parent has no
* royalty wallet, the split falls below the dust floor, the platform payout
* wallet isn't configured, the remix crosses networks, or this specific mint
* call collected no fee to split (an OAuth-bypassed call, or devnet — the
* payout wallet only holds real mainnet funds).
*
* @param {object} p
* @param {Function} p.sql tagged-template SQL client (injectable for tests)
* @param {string} p.parentMint the asset this mint derives from
* @param {string} p.network this mint's network — must match the parent's
* @param {bigint} p.feeAtomics the mint fee actually collected for THIS call
* @returns {Promise<object>} settlement summary — always defined, `paid` tells the story
*/
export async function settleTokenizeRemixRoyalty({ sql: sqlClient, parentMint, network, feeAtomics }) {
const fee = typeof feeAtomics === 'bigint' ? feeAtomics : BigInt(feeAtomics || 0);
if (network !== 'mainnet') {
return { paid: false, reason: 'devnet_not_settled', parent_mint: parentMint };
}
if (fee <= 0n) {
return { paid: false, reason: 'no_fee_collected', parent_mint: parentMint };
}
const [parent] = await sqlClient`
select mint, royalty_bps, royalty_recipient, owner_wallet
from tokenized_3d_assets
where mint = ${parentMint} and network = ${network} and status = 'minted'
limit 1
`;
if (!parent) {
return { paid: false, reason: 'parent_not_found', parent_mint: parentMint };
}
const creatorWallet = parent.royalty_recipient || parent.owner_wallet;
const split = computeRemixSplit({ priceAtomics: fee, royaltyBps: parent.royalty_bps });
const summary = {
parent_mint: parentMint,
royalty_bps: split.royaltyBps,
requested_bps: split.requestedBps,
capped: split.capped,
dust: split.dust,
creator_usd: split.creatorUsd,
platform_usd: split.platformUsd,
creator_atomics: split.creatorAtomics.toString(),
platform_atomics: split.platformAtomics.toString(),
};
if (!creatorWallet) {
return { ...summary, paid: false, reason: 'no_creator_wallet' };
}
if (split.creatorAtomics <= 0n) {
return { ...summary, paid: false, reason: split.dust ? 'below_dust_floor' : 'zero_royalty' };
}
const fromWallet = resolvePayoutKeyBase58();
if (!fromWallet) {
return { ...summary, paid: false, reason: 'payout_unconfigured' };
}
try {
const sig = await transferSolanaUSDC({
fromWallet,
toAddress: creatorWallet,
amount: split.creatorAtomics,
mint: SOLANA_USDC_MINT,
});
return {
...summary,
paid: true,
creator_wallet: creatorWallet,
creator_tx: sig,
explorer_tx_url: explorerTxUrl(sig, network),
settled_at: new Date().toISOString(),
};
} catch (err) {
return { ...summary, paid: false, reason: 'royalty_transfer_failed', error: err?.message || 'transfer failed' };
}
}
/**
* Pay the parent creator's remix royalty, or hold it until the caller's x402
* payment has settled. The royalty comes out of the platform treasury, so it must
* not leave before the fee it is carved from has actually landed: a payer whose
* settlement fails would otherwise cost the platform the royalty.
*
* @param {object} p
* @param {(run: () => Promise<void>) => void} [p.defer] registers work to run
* after settlement; omitted means pay now (no per-call fee to wait for).
*/
export async function settleOrDeferRemixRoyalty({ sql: sqlClient, rowId, parentMint, network, feeAtomics, defer }) {
const settle = () => settleTokenizeRemixRoyalty({ sql: sqlClient, parentMint, network, feeAtomics });
if (typeof defer !== 'function') return settle();
defer(async () => {
const settled = await settle();
await sqlClient`update tokenized_3d_assets set remix_royalty = ${JSON.stringify(settled)}::jsonb, updated_at = now() where id = ${rowId}`;
});
return { paid: false, reason: 'pending_payment_settlement', parent_mint: parentMint };
}
function formatMintResult(
row,
{ idempotent, capped, requestedBps, royaltyBps, metadataIpfs = null, provenanceLedger, remixRoyalty },
) {
return {
status: 'minted',
idempotent: Boolean(idempotent),
mint: row.mint,
network: row.network,
name: row.name,
owner: row.royalty_recipient, // recipient == owner unless royaltyRecipient overridden
glb_url: row.glb_url,
image_url: row.image_url,
viewer_url: row.viewer_url,
metadata_uri: row.metadata_uri,
metadata_ipfs: metadataIpfs,
// Signed agent_actions-ledger provenance for this mint (Prompt 08, task 1)
// — null when the source avatar has no provisioned agent to sign as.
provenance_ledger: provenanceLedger ?? row.provenance_ledger ?? null,
// Real remix-royalty settlement out of this mint's fee (Prompt 08, task 4)
// — null when this mint has no parent_mint (not a remix).
remix_royalty: remixRoyalty ?? row.remix_royalty ?? null,
royalty: {
basis_points: row.royalty_bps ?? royaltyBps,
percent: (row.royalty_bps ?? royaltyBps) / 100,
recipient: row.royalty_recipient,
cap_basis_points: TOKENIZE_3D_ROYALTY_CAP_BPS,
capped: Boolean(capped),
...(capped ? { requested_basis_points: requestedBps } : {}),
},
tx_signature: row.tx_signature,
explorer_tx_url: row.tx_signature ? explorerTxUrl(row.tx_signature, row.network) : null,
explorer_asset_url: assetExplorerUrl(row.mint, row.network),
};
}
// ── Public API: read-back ────────────────────────────────────────────────────
/**
* Resolve a mint to its live 3D asset + holder + provenance + royalty terms.
* Reads the on-chain Core asset, fetches its off-chain metadata, joins our
* launch record, and confirms it resolves to a live viewer.
*
* @param {object} p
* @param {string} p.mint
* @param {string} [p.network] 'devnet' (default) | 'mainnet'
* @returns {Promise<object>}
*/
export async function readTokenized3dAsset({ mint, network: preferredNetwork }) {
if (!isValidBase58Pubkey(mint)) {
throw Object.assign(new Error('mint is not a valid Solana address'), {
status: 400,
code: 'validation_error',
});
}
// Our launch record (if this was minted through three.ws) — the source of
// truth for provenance, and it tells us which network to read.
const [record] = await sql`
select mint, network, owner_wallet, name, glb_url, image_url, viewer_url,
metadata_uri, royalty_bps, royalty_recipient, provenance, tx_signature, created_at,
provenance_ledger, remix_royalty
from tokenized_3d_assets
where mint = ${mint} and status = 'minted'
limit 1
`;
const network = resolveNetwork(record?.network || preferredNetwork);
// On-chain read: holder + enforced royalty live here, authoritative over the DB.
const umi = createUmi(solanaConnection({ url: rpcForNetwork(network), network })).use(mplCore());
let asset;
try {
asset = await fetchAsset(umi, umiPublicKey(mint));
} catch (err) {
throw Object.assign(new Error(`asset not found on ${network}: ${err?.message || 'read failed'}`), {
status: 404,
code: 'asset_not_found',
});
}
const holder = asset.owner?.toString?.() || null;
const onchainRoyalty = asset.royalties
? {
basis_points: asset.royalties.basisPoints,
percent: asset.royalties.basisPoints / 100,
creators: (asset.royalties.creators || []).map((c) => ({
address: c.address?.toString?.() || String(c.address),
percent: c.percentage,
})),
}
: null;
// Off-chain metadata (media + provenance). Prefer the on-chain URI so an
// asset not in our DB still resolves.
const metadataUri = asset.uri || record?.metadata_uri || null;
let metadata = null;
if (metadataUri) {
try {
const resp = await fetchSafePublicUrl(metadataUri, {}, { allowHttp: false });
if (resp.ok) metadata = await resp.json();
} catch (err) {
console.warn('[tokenize-3d] metadata fetch failed:', err?.message);
}
}
const glbUrl = metadata?.animation_url || record?.glb_url || null;
const viewerUrl =
metadata?.external_url ||
record?.viewer_url ||
(glbUrl ? viewerLinkFor(env.APP_ORIGIN, glbUrl) : null);
// Confirm the media resolves to a live viewer (HEAD the GLB).
let viewerLive = false;
if (glbUrl) {
try {
const head = await fetchSafePublicUrl(glbUrl, { method: 'HEAD' }, { allowHttp: false });
viewerLive = head.ok;
} catch {
viewerLive = false;
}
}
const provenance = metadata?.properties?.provenance || record?.provenance || null;
return {
mint,
network,
holder,
name: asset.name || metadata?.name || record?.name || null,
media: {
glb_url: glbUrl,
image_url: metadata?.image || record?.image_url || null,
viewer_url: viewerUrl,
viewer_live: viewerLive,
media_kind: '3d/gltf-binary',
},
provenance,
// The signed agent_actions-ledger record for this mint (if the source
// avatar had a provisioned agent to sign as) — independently verifiable
// via query_action/list_agent_actions, alongside the metadata provenance.
provenance_ledger: record?.provenance_ledger || null,
royalty: {
// The enforced on-chain terms are authoritative; fall back to the record.
basis_points: onchainRoyalty?.basis_points ?? record?.royalty_bps ?? null,
percent:
onchainRoyalty?.percent ??
(record?.royalty_bps != null ? record.royalty_bps / 100 : null),
recipient:
onchainRoyalty?.creators?.[0]?.address || record?.royalty_recipient || null,
cap_basis_points: TOKENIZE_3D_ROYALTY_CAP_BPS,
enforced_onchain: Boolean(onchainRoyalty),
creators: onchainRoyalty?.creators || null,
},
// The real remix-royalty settlement this mint routed to its parent's
// creator (only present when this mint named a parent_mint).
remix_royalty: record?.remix_royalty || null,
metadata_uri: metadataUri,
minted_through_threews: Boolean(record),
tx_signature: record?.tx_signature || null,
explorer_tx_url: record?.tx_signature ? explorerTxUrl(record.tx_signature, network) : null,
explorer_asset_url: assetExplorerUrl(mint, network),
};
}
/** The three.ws authority that pays rent + holds update authority for these mints. */
export function tokenizeAuthorityAddress() {
return collectionAuthorityAddress();
}