Skip to content

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.

9.7 KB
Raw Blame
// POST /api/x402/remix-asset — paid remix with automatic creator royalties.
//
// The composable, economic half of conversational 3D: an agent pays a fixed
// remix fee in USDC (x402) to generate a NEW model derived from another
// creator's PUBLISHED, remixable asset. The platform collects the fee, generates
// the remix (a real anchored regeneration off the source), links the durable
// parent → child provenance edge, and then routes the source creator's royalty
// slice on-chain from the platform payout wallet — a real second USDC transfer,
// capped at 20%, with the remixer always keeping the clear majority of value.
//
// Why this shape: the x402 rail settles to ONE recipient (the platform), so the
// split is composed — fee in via x402, royalty out via a guarded treasury
// transfer (api/_lib/remix-settlement.js). Split + caps are pure and unit-tested
// (api/_lib/remix-royalty.js). Provenance is stored on the existing
// forge_creations rows (parent_creation_id + remix_settlement_ref) — no parallel
// store. $THREE-policy clean: USDC is the settlement asset only.
//
// The pre-remix disclosure (a source's terms + royalty rate) is free on
// GET /api/remix-feed; this endpoint is the paid execution.

import { paidEndpoint } from '../_lib/x402-paid-endpoint.js';
import { buildBazaarSchema } from '../_lib/x402-spec.js';
import { readJson } from '../_lib/http.js';
import { withService } from '../_lib/x402/bazaar-helpers.js';
import { getRemixSource, linkRefinement } from '../_lib/forge-store.js';
import { settleRemixRoyalty } from '../_lib/remix-settlement.js';
import { atomicsToUsd } from '../_lib/remix-royalty.js';
import { composeRefinement } from '../../mcp-server/src/tools/_lineage.js';
import { generate, originFromReq, viewerUrl } from '../_mcp-studio/forge-client.js';
import remixAssetListing from '../_lib/service-catalog/services/remix-asset.js';
import { unlockBadge, BADGES } from '../_lib/streaks.js';
import { publishUserEvent } from '../_lib/feed.js';

// $0.25 — the cost of a generation. The creator royalty comes OUT of this fee
// (the platform's share), never as an extra charge to the remixer.
const PRICE_ATOMICS = '250000';

const INPUT_SCHEMA = {
	type: 'object',
	required: ['source_creation_id', 'instruction'],
	properties: {
		source_creation_id: { type: 'string', minLength: 1, maxLength: 64, description: 'The id of a remixable creation (from GET /api/remix-feed).' },
		instruction: { type: 'string', minLength: 1, maxLength: 500, description: 'The change to make, in plain language.' },
	},
};

const OUTPUT_SCHEMA = {
	type: 'object',
	properties: {
		ok: { type: 'boolean' },
		remix: { type: 'object' },
		source: { type: 'object' },
		royalty: { type: 'object' },
		fee: { type: 'object' },
	},
};

const BAZAAR = {
	discoverable: true,
	info: {
		input: {
			type: 'http',
			method: 'POST',
			bodyType: 'json',
			body: { source_creation_id: '00000000-0000-0000-0000-000000000000', instruction: 'make it metallic' },
		},
		output: {
			type: 'json',
			example: {
				ok: true,
				remix: { glbUrl: 'https://three.ws/cdn/creations/def456/mesh.glb', creationId: 'def456' },
				source: { id: '00000000-0000-0000-0000-000000000000', royaltyPercent: 10 },
				royalty: { paid: true, creatorUsd: 0.025, creatorTx: '5eyk…', capped: false },
				fee: { usd: 0.25, atomics: '250000' },
			},
		},
	},
	schema: buildBazaarSchema({ method: 'POST', bodySchema: INPUT_SCHEMA, outputSchema: OUTPUT_SCHEMA }),
};

class RemixError extends Error {
	constructor(status, code, message) {
		super(message);
		this.status = status;
		this.code = code;
	}
}

async function handleRemix({ req, requirement }) {
	const body = await readJson(req).catch(() => ({}));
	const sourceId = String(body?.source_creation_id || '').trim();
	const instruction = String(body?.instruction || '').trim();
	if (!sourceId) throw new RemixError(400, 'missing_source', 'source_creation_id is required');
	if (!instruction) throw new RemixError(400, 'missing_instruction', 'instruction is required (e.g. "make it metallic")');
	if (instruction.length > 500) throw new RemixError(400, 'instruction_too_long', 'instruction must be 500 characters or fewer');

	// Load the source and enforce that it is actually opted into the bazaar.
	const source = await getRemixSource({ creationId: sourceId });
	if (!source) throw new RemixError(404, 'source_not_found', 'no finished, stored creation with that id');
	if (!source.remixable) throw new RemixError(403, 'not_remixable', 'this creation is not published as remixable');

	// Real anchored regeneration: carry the source prompt forward + fold in the
	// change, and anchor on the source's reference image when one exists (image→3D).
	const composed = composeRefinement(source.prompt || '', instruction);
	const base = originFromReq(req);
	const anchorImage =
		typeof source.previewImageUrl === 'string' && /^https?:\/\//i.test(source.previewImageUrl)
			? source.previewImageUrl
			: null;

	let job;
	try {
		job = await generate(
			base,
			anchorImage ? { prompt: composed, imageUrls: [anchorImage], aspect: source.aspect || '1:1' } : { prompt: composed },
			{ timeoutEnv: 'REMIX_ASSET_TIMEOUT_MS' },
		);
	} catch (err) {
		throw new RemixError(502, err.code === 'timeout' ? 'generation_timeout' : 'generation_failed', `remix generation failed: ${err.message}`);
	}
	if (job._timedOut || !job.glb_url) {
		// Nothing was delivered, so we do NOT settle — the remixer keeps their
		// funds and can retry the same payment (payment-identifier makes it safe).
		throw new RemixError(504, 'generation_timeout', 'remix generation did not finish in time — no fee was charged; retry with the same payment');
	}

	// Durable provenance: link the derived creation to its source.
	const remixCreationId = job.creation_id ?? null;
	if (remixCreationId) {
		await linkRefinement({
			creationId: remixCreationId,
			clientKey: null, // platform-authoritative link; remixer is not the owner
			parentCreationId: source.id,
			refineInstruction: instruction,
			lineageIndex: (source.lineageIndex ?? 0) + 1,
		});
	}

	// Route the creator royalty out of the collected fee. settleRemixRoyalty is
	// honest about every outcome (paid / no wallet / sub-dust / unconfigured).
	const feeAtomics = requirement?.amount || PRICE_ATOMICS;
	let royalty;
	try {
		royalty = await settleRemixRoyalty({ source, priceAtomics: feeAtomics, remixCreationId });
	} catch (err) {
		// The remix WAS generated and the fee WILL settle; the royalty transfer
		// alone failed. Report it truthfully rather than pretending it paid.
		royalty = { paid: false, reason: 'royalty_transfer_failed', error: err.message };
	}

	// Notify the source creator (real signed-in creators only — anonymous
	// forge_creations rows have no user_id to notify). Fire-and-forget, never
	// blocks the response; folds the royalty outcome into the same notice so a
	// creator learns "you were remixed" and "you got paid" in one line.
	if (source.userId) {
		publishUserEvent(source.userId, {
			type: 'remix',
			actor: 'Someone',
			link: remixCreationId ? viewerUrl(base, job.glb_url) : '/profile',
			sourcePrompt: source.prompt,
			creationId: remixCreationId,
			royaltyPaid: royalty.paid,
			royaltyUsd: royalty.creatorUsd ?? 0,
		});
		// First-remix-received badge — a real earned record, awarded once.
		unlockBadge(source.userId, BADGES.FIRST_REMIX_RECEIVED).catch(() => {});
	}

	return {
		ok: true,
		remix: {
			glbUrl: job.glb_url,
			viewerUrl: viewerUrl(base, job.glb_url),
			creationId: remixCreationId,
			prompt: composed,
			instruction,
			anchored: Boolean(anchorImage),
		},
		source: {
			id: source.id,
			prompt: source.prompt,
			royaltyBps: source.royaltyBps,
			royaltyPercent: Math.round((source.royaltyBps / 100) * 10) / 10,
		},
		royalty: {
			paid: royalty.paid,
			...(royalty.reason ? { reason: royalty.reason } : {}),
			royaltyBps: royalty.royaltyBps ?? source.royaltyBps,
			capped: royalty.capped ?? false,
			creatorUsd: royalty.creatorUsd ?? 0,
			platformUsd: royalty.platformUsd ?? atomicsToUsd(feeAtomics),
			creatorAtomics: royalty.creatorAtomics ?? '0',
			...(royalty.creatorTx ? { creatorTx: royalty.creatorTx } : {}),
			...(royalty.settlement ? { settlement: royalty.settlement } : {}),
		},
		fee: { usd: atomicsToUsd(feeAtomics), atomics: String(feeAtomics) },
		note:
			'The remix fee settled to the platform via x402 (see X-PAYMENT-RESPONSE). ' +
			(royalty.paid
				? `The creator royalty of ${royalty.creatorUsd} USDC settled on-chain (creatorTx above).`
				: `No creator royalty was routed (${royalty.reason || 'no payout'}).`),
	};
}

// Single source of truth: api/_lib/service-catalog/services/remix-asset.js is
// the storefront listing copy — importing it here keeps the live 402 challenge
// from drifting from what /.well-known/x402.json and the OKX projection
// advertise (same pattern as forge.js → forge-listing.js).
export default paidEndpoint({
	route: '/api/x402/remix-asset',
	method: 'POST',
	priceAtomics: PRICE_ATOMICS,
	networks: ['solana', 'base'],
	description: remixAssetListing.description,
	mimeType: 'application/json',
	bazaar: BAZAAR,
	// A duplicate call is materially expensive (a GPU generation + an on-chain
	// royalty transfer), so require the payment-identifier idempotency extension.
	paymentIdentifier: { required: true },
	service: withService({
		serviceName: 'Remix a 3D asset + royalties',
		tags: ['3d', 'remix', 'royalties', 'generation'],
	}),
	// RemixError carries .status + .code, which is exactly what paidEndpoint's own
	// catch maps to a clean error response before settlement runs. Writing the
	// response here instead made paidEndpoint see a handler that flushed without
	// settling: it logged a payment_unsettled_flush leak, recorded a failed
	// payment metric and threw, so every ordinary 400 (bad source id, empty
	// instruction) read as a money leak in the x402 telemetry.
	handler: handleRemix,
});