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.

8.8 KB
Raw Blame
// A paid endpoint's job is RECEIVING crypto. It must not stop doing that
// because the wallet we use to sponsor buyers' gas ran dry.
//
// Sponsoring is a convenience: three.ws pays the Solana fee so a buyer holding
// only USDC can pay without owning SOL. It is not a precondition for taking
// money. The x402 rail already supports self-pay end to end (settleRingPayment
// broadcasts a fully-signed buyer-paid transaction without touching a sponsor
// key), but buildRequirements used to DROP the Solana accept entirely when the
// sponsor was under its SOL floor, so /club answered 503 on both the cover
// charge and every dance tip for four days while the payTo wallet sat there
// perfectly able to receive.
//
// The contract these tests pin: no sponsor means the accept is advertised
// WITHOUT `extra.feePayer`, which is the wire signal that the buyer signs as
// their own fee payer.

import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';

const SPONSOR = 'WwwuGbqHrwF5RG89KhUbmRWEvjnRH9k5kVM5p7T3WwW';
const PAY_TO = 'wwwwwDxFWRn7grgr3Esrsg5C6NvDoDHSA4gaCffccrU';
const USDC = 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v';
const THREE = 'FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump';

const ENV = {
	X402_PAY_TO_SOLANA: PAY_TO,
	X402_ASSET_MINT_SOLANA: USDC,
	X402_FEE_PAYER_SOLANA: SPONSOR,
	THREE_TOKEN_MINT: THREE,
	X402_ACCEPT_THREE_SOLANA: 'true',
	X402_SELF_FACILITATOR_ENABLED: 'true',
	// Non-empty means the sponsor co-signing key is loaded, so solanaSettleable()
	// reports sponsor mode available. Never parsed by buildRequirements.
	X402_FEE_PAYER_SECRET_BASE58: 'test-cosigning-key-present',
};

// Cleared per test so facilitator routing is decided by X402_SELF_FACILITATOR_ENABLED
// rather than by whatever the ambient environment happens to point at.
const CLEARED = ['X402_FACILITATOR_URL_SOLANA', 'X402_RING_SELF_PAY'];

let saved;
beforeEach(() => {
	saved = {};
	for (const [k, v] of Object.entries(ENV)) {
		saved[k] = process.env[k];
		process.env[k] = v;
	}
	for (const k of CLEARED) {
		saved[k] = process.env[k];
		delete process.env[k];
	}
	vi.resetModules();
});
afterEach(() => {
	for (const [k, v] of Object.entries(saved)) {
		if (v === undefined) delete process.env[k];
		else process.env[k] = v;
	}
	vi.restoreAllMocks();
	vi.resetModules();
});

/** Load buildRequirements with the sponsor's floor state stubbed. */
async function requirementsWith({ belowFloor }) {
	vi.doMock('../api/_lib/x402/self-facilitator.js', () => ({
		sponsorKnownBelowFloor: () => belowFloor,
		refreshSponsorFloorState: () => {},
	}));
	const { buildRequirements } = await import('../api/_lib/x402-paid-endpoint.js');
	return buildRequirements({
		priceAtomics: '1000',
		networks: ['solana'],
		resourceUrl: 'https://three.ws/api/x402/dance-tip',
	});
}

const solanaAccepts = (list) => list.filter((a) => String(a.network).startsWith('solana'));

describe('a dry sponsor keeps the endpoint payable via self-pay', () => {
	it('still advertises Solana when the sponsor is below its floor', async () => {
		const accepts = await requirementsWith({ belowFloor: true });
		// The regression: this list used to come back empty and the endpoint 503'd.
		expect(solanaAccepts(accepts).length).toBeGreaterThan(0);
	});

	it('omits feePayer on every Solana accept when the sponsor is dry', async () => {
		const accepts = solanaAccepts(await requirementsWith({ belowFloor: true }));
		for (const accept of accepts) {
			expect(accept.extra).toBeDefined();
			expect(accept.extra.feePayer).toBeUndefined();
		}
		// Both tokens stay on the menu, so $THREE does not quietly disappear the
		// moment the sponsor runs out.
		expect(accepts.map((a) => a.asset)).toEqual([USDC, THREE]);
	});

	it('keeps sponsoring gas while the sponsor is healthy', async () => {
		const accepts = solanaAccepts(await requirementsWith({ belowFloor: false }));
		expect(accepts.length).toBeGreaterThan(0);
		for (const accept of accepts) {
			expect(accept.extra.feePayer).toBe(SPONSOR);
		}
	});

	it('falls back to self-pay when no sponsor is configured at all', async () => {
		delete process.env.X402_FEE_PAYER_SOLANA;
		const accepts = solanaAccepts(await requirementsWith({ belowFloor: false }));
		// Previously this dropped Solana too, so a deployment that never set a
		// sponsor could not take Solana payments at all.
		expect(accepts.length).toBeGreaterThan(0);
		for (const accept of accepts) {
			expect(accept.extra.feePayer).toBeUndefined();
		}
	});

	it('keeps the sponsor as fee payer when an EXTERNAL facilitator settles', async () => {
		// PayAI and friends pin the sponsor as fee payer and reject a challenge
		// without one at /verify, so the self-pay fallback must not apply there:
		// it would trade a retryable 503 for a hard verify failure.
		process.env.X402_FACILITATOR_URL_SOLANA = 'https://facilitator.payai.network';
		const accepts = solanaAccepts(await requirementsWith({ belowFloor: true }));
		for (const accept of accepts) {
			expect(accept.extra.feePayer).toBe(SPONSOR);
		}
	});

	it('still refuses to advertise Solana when the receiving address is missing', async () => {
		// Self-pay fixes who pays gas. It cannot conjure somewhere to send the
		// money, so a genuinely unconfigured lane must stay unadvertised, and with
		// Solana the only requested network that leaves nothing payable at all.
		delete process.env.X402_PAY_TO_SOLANA;
		await expect(requirementsWith({ belowFloor: false })).rejects.toMatchObject({
			code: 'no_payto_configured',
		});
	});
});

// The same fallback on the OTHER accept builder. paymentRequirements() serves
// the 17 hand-rolled paid endpoints (asset-download, skill-call, print-order,
// cosmetic-purchase, knock and friends) that do not go through paidEndpoint,
// and it had the identical flaw: no sponsor meant no Solana accept at all.
describe('paymentRequirements shares the self-pay fallback', () => {
	async function requirements({ belowFloor }) {
		vi.doMock('../api/_lib/x402/self-facilitator.js', () => ({
			sponsorKnownBelowFloor: () => belowFloor,
			refreshSponsorFloorState: () => {},
		}));
		const { paymentRequirements } = await import('../api/_lib/x402-spec.js');
		return paymentRequirements('https://three.ws/api/x402/asset-download', { amount: '1000' });
	}

	it('keeps advertising Solana without a feePayer when the sponsor is dry', async () => {
		const accepts = solanaAccepts(await requirements({ belowFloor: true }));
		expect(accepts.length).toBeGreaterThan(0);
		for (const accept of accepts) {
			expect(accept.extra.feePayer).toBeUndefined();
		}
		// $THREE survives the sponsor going dry here too.
		expect(accepts.map((a) => a.asset)).toContain(THREE);
	});

	it('keeps sponsoring gas while the sponsor is healthy', async () => {
		const accepts = solanaAccepts(await requirements({ belowFloor: false }));
		expect(accepts.length).toBeGreaterThan(0);
		for (const accept of accepts) {
			expect(accept.extra.feePayer).toBe(SPONSOR);
		}
	});
});

// The four sibling builders that never got the guard: they advertised the
// sponsor as fee payer unconditionally, so a sponsor under its floor kept being
// offered and every payment buyers signed against it was refused at settle.
describe.each([
	[
		'buildExactRequirements',
		async () => (await import('../api/_lib/x402-spec.js')).buildExactRequirements,
	],
	[
		'pipeline.js buildRequirements',
		async () => (await import('../api/x402/pipeline.js')).buildRequirements,
	],
	[
		'forge.js buildRequirements',
		async () => (await import('../api/x402/forge.js')).buildRequirements,
	],
	[
		'drops.js buildRequirements',
		async () => (await import('../api/vanity/drops.js')).buildRequirements,
	],
])('%s shares the self-pay fallback', (_name, load) => {
	async function requirements({ belowFloor }) {
		vi.doMock('../api/_lib/x402/self-facilitator.js', () => ({
			sponsorKnownBelowFloor: () => belowFloor,
			refreshSponsorFloorState: () => {},
		}));
		const build = await load();
		return build('https://three.ws/api/x402/example', '1000');
	}

	it('keeps the Solana accept but drops feePayer when the sponsor is below its floor', async () => {
		const accepts = solanaAccepts(await requirements({ belowFloor: true }));
		expect(accepts.length).toBeGreaterThan(0);
		for (const accept of accepts) {
			expect(accept.extra.feePayer).toBeUndefined();
		}
	});

	it('keeps sponsoring gas while the sponsor is healthy', async () => {
		const accepts = solanaAccepts(await requirements({ belowFloor: false }));
		expect(accepts.length).toBeGreaterThan(0);
		for (const accept of accepts) {
			expect(accept.extra.feePayer).toBe(SPONSOR);
		}
	});

	it('advertises Solana via self-pay when no sponsor is configured', async () => {
		delete process.env.X402_FEE_PAYER_SOLANA;
		const accepts = solanaAccepts(await requirements({ belowFloor: false }));
		expect(accepts.length).toBeGreaterThan(0);
		for (const accept of accepts) {
			expect(accept.extra.feePayer).toBeUndefined();
		}
	});
});