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
// POST /api/knock/escrowed: the escrowed lane's refusal surface.
//
// The handler's whole job is to refuse anything the chain does not back, so the
// cases that matter are the refusals. Each one below is something a caller can
// really do, and getting any of them wrong means either delivering a message
// nobody paid for or telling somebody who did pay that they did not.
//
// Everything downstream of the seams is the real handler: the real zod schema,
// the real ordering of checks, the real escrow verifier decoding real
// program-layout bytes. Only the two boundaries are stubbed, the database and
// the Solana RPC, because this suite is about the handler's decisions rather
// than about Postgres or a live cluster. The PDA derivation those bytes are
// keyed by is pinned against the compiled program in tests/knock-escrow-pda.test.js.
import { describe, it, expect, vi, beforeEach } from 'vitest';
import { PublicKey } from '@solana/web3.js';
const OWNER_WALLET = '11111111111111111111111111111111';
const SENDER = 'TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA';
const USDC = 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v';
const HANDLE = 'nirholas';
const NONCE = 7;
const PRICE = '50000';
// From tests/knock-escrow-pda.test.js, which pins these against the program.
const KNOCK_PDA = '8WvZ64SL6JNss232BC78aapB2M6MjE95f9LtWfYYRn5t';
const DOOR_PDA = 'DMDKj3mSoM5rjsftGAhSbLbrAWMwmFxEkHDLsx997vk8';
const DISC_KNOCK = 'f9c621b06c558191';
const PROGRAM = 'uVX46U6sGUs6PD3339ZXbTpMyhZwkQhBLPxnvRX9ps7';
const state = {
door: null,
payout: null,
account: null,
accountOwner: PROGRAM,
existingByEscrow: null,
delivered: [],
checkDoorThrows: null,
};
vi.mock('../api/_lib/knock/store.js', () => ({
publicDoorByHandle: async () => state.door,
payoutFor: async () => state.payout,
findByEscrowKnock: async () => state.existingByEscrow,
}));
vi.mock('../api/_lib/knock/deliver.js', () => ({
checkDoor: async (userId, input) => {
if (state.checkDoorThrows) throw state.checkDoorThrows;
return { clean: { message: input.message, senderName: input.from, subject: input.subject ?? null } };
},
deliverKnock: async (args) => {
state.delivered.push(args);
return { knock: { id: 'knock-row-1' }, duplicate: false };
},
}));
vi.mock('../api/_lib/knock/receipt.js', () => ({ receiptUrl: (id) => `/knock/receipt/${id}` }));
vi.mock('../api/_lib/rate-limit.js', () => ({
clientIp: () => '203.0.113.9',
limits: { knockSendIp: async () => ({ success: true }) },
}));
vi.mock('../api/_lib/solana/rpc-fallback.js', () => ({
rpcFallbackFromEnv: () => ({
withFallback: (fn) =>
fn({
async getAccountInfo() {
if (!state.account) return null;
return { data: state.account, owner: { toBase58: () => state.accountOwner } };
},
}),
}),
}));
const { default: handler } = await import('../api/knock/escrowed.js');
const { sha256 } = await import('../api/_lib/knock/escrow.js');
/** A KnockRecord laid out exactly as the program writes one. */
function knockAccount({
messageHash,
amount = 50_000n,
state: knockState = 0,
expiresAt = Math.floor(Date.now() / 1000) + 3600,
} = {}) {
const buf = Buffer.alloc(205);
Buffer.from(DISC_KNOCK, 'hex').copy(buf, 0);
new PublicKey(DOOR_PDA).toBuffer().copy(buf, 8);
new PublicKey(SENDER).toBuffer().copy(buf, 40);
new PublicKey(USDC).toBuffer().copy(buf, 72);
buf.writeBigUInt64LE(amount, 104);
buf.writeUInt16LE(250, 112);
buf.writeBigUInt64LE(BigInt(NONCE), 114);
Buffer.from(messageHash).copy(buf, 122);
buf.writeBigInt64LE(BigInt(expiresAt - 3600), 186);
buf.writeBigInt64LE(BigInt(expiresAt), 194);
buf[202] = knockState;
return buf;
}
function call(body) {
const req = {
method: 'POST',
url: '/api/knock/escrowed',
headers: { 'content-type': 'application/json', origin: 'https://three.ws' },
body,
socket: { remoteAddress: '203.0.113.9' },
};
const res = {
statusCode: 0,
payload: null,
headers: {},
setHeader(k, v) {
this.headers[String(k).toLowerCase()] = v;
},
getHeader(k) {
return this.headers[String(k).toLowerCase()];
},
removeHeader(k) {
delete this.headers[String(k).toLowerCase()];
},
writeHead(code) {
this.statusCode = code;
return this;
},
get headersSent() {
return false;
},
get writableEnded() {
return false;
},
end(chunk) {
if (chunk) {
try {
this.payload = JSON.parse(String(chunk));
} catch {
this.payload = String(chunk);
}
}
return this;
},
};
return handler(req, res).then(() => ({ status: res.statusCode, body: res.payload }));
}
const MESSAGE = 'two questions about the facilitator, happy to pay for the time';
const goodBody = {
to: HANDLE,
from: 'Ada (research agent)',
message: MESSAGE,
sender_wallet: SENDER,
nonce: NONCE,
};
beforeEach(() => {
state.door = {
user_id: 'user-1',
username: HANDLE,
display_name: 'nirholas',
price_atomics: PRICE,
escrow_enabled: true,
escrow_window_hours: 24,
};
state.payout = { pay_to_solana: OWNER_WALLET };
state.account = knockAccount({ messageHash: sha256(MESSAGE) });
state.accountOwner = PROGRAM;
state.existingByEscrow = null;
state.delivered = [];
state.checkDoorThrows = null;
});
describe('POST /api/knock/escrowed', () => {
it('delivers a message backed by a live escrow, and says when it expires', async () => {
const out = await call(goodBody);
expect(out.status).toBe(201);
expect(out.body.ok).toBe(true);
expect(out.body.escrow.knock).toBe(KNOCK_PDA);
expect(out.body.escrow.program).toBe(PROGRAM);
expect(out.body.escrow.amount_atomics).toBe('50000');
expect(out.body.escrow.state).toBe('pending');
expect(out.body.escrow.expires_in_seconds).toBeGreaterThan(0);
expect(out.body.receipt).toBe('/knock/receipt/knock-row-1');
// The delivery carries the escrow through, so the inbox can show a
// countdown and the row can be reconciled against the chain later.
expect(state.delivered).toHaveLength(1);
expect(state.delivered[0].payment).toMatchObject({
escrowKnock: KNOCK_PDA,
escrowState: 'pending',
network: 'solana',
asset: USDC,
});
});
it('answers 402, not 500, when no escrow exists', async () => {
state.account = null;
const out = await call(goodBody);
expect(out.status).toBe(402);
expect(out.body.error).toBe('knock_not_found');
// The caller is told which account to go and fund.
expect(out.body.knock).toBe(KNOCK_PDA);
expect(state.delivered).toHaveLength(0);
});
it('refuses a message the sender did not escrow, so a payment cannot be reused', async () => {
state.account = knockAccount({ messageHash: sha256('a much smaller favour') });
const out = await call(goodBody);
expect(out.status).toBe(409);
expect(out.body.error).toBe('message_mismatch');
expect(state.delivered).toHaveLength(0);
});
it('refuses an escrow that already settled', async () => {
state.account = knockAccount({ messageHash: sha256(MESSAGE), state: 1 });
const out = await call(goodBody);
expect(out.status).toBe(409);
expect(out.body.error).toBe('already_settled');
});
it('refuses an expired escrow, because that money is owed back', async () => {
state.account = knockAccount({
messageHash: sha256(MESSAGE),
expiresAt: Math.floor(Date.now() / 1000) - 5,
});
const out = await call(goodBody);
expect(out.status).toBe(409);
expect(out.body.error).toBe('window_closed');
});
it('refuses an escrow below the door price', async () => {
state.account = knockAccount({ messageHash: sha256(MESSAGE), amount: 10_000n });
const out = await call(goodBody);
expect(out.status).toBe(409);
expect(out.body.error).toBe('underpaid');
});
it('refuses an account owned by another program', async () => {
state.accountOwner = '11111111111111111111111111111111';
const out = await call(goodBody);
expect(out.status).toBe(409);
expect(out.body.error).toBe('wrong_program');
});
it('checks the door BEFORE the chain, so a doomed message never reports a good escrow', async () => {
const refusal = Object.assign(new Error('this door is full for today'), {
code: 'door_full',
status: 429,
});
state.checkDoorThrows = refusal;
state.account = null; // would be a 402 if the chain were consulted first
const out = await call(goodBody);
// The door's own refusal wins, and it is the door's status the caller
// sees, not a payment error about an escrow that was never the problem.
expect(out.status).toBe(429);
expect(out.body.error).toBe('door_full');
expect(state.delivered).toHaveLength(0);
});
it('points a caller at the right lane when the door does not take escrow', async () => {
state.door.escrow_enabled = false;
const out = await call(goodBody);
expect(out.status).toBe(409);
expect(out.body.error).toBe('escrow_not_enabled');
expect(out.body.endpoint).toContain('/api/x402/knock');
});
it('refuses a door with no Solana address, which has no on-chain door at all', async () => {
state.payout = { pay_to_solana: null };
const out = await call(goodBody);
expect(out.status).toBe(409);
expect(out.body.error).toBe('no_payout_wallet');
});
it('404s an unknown handle', async () => {
state.door = null;
const out = await call(goodBody);
expect(out.status).toBe(404);
expect(out.body.error).toBe('no_door');
});
it('returns the original delivery when one escrow is replayed', async () => {
state.existingByEscrow = { id: 'knock-row-1' };
const out = await call(goodBody);
expect(out.status).toBe(200);
expect(out.body.duplicate).toBe(true);
expect(out.body.knock_id).toBe('knock-row-1');
// One escrow buys one message: no second delivery is staged.
expect(state.delivered).toHaveLength(0);
});
it('accepts a nonce sent as a string, which is how a JSON client avoids u64 loss', async () => {
const out = await call({ ...goodBody, nonce: String(NONCE) });
expect(out.status).toBe(201);
expect(out.body.escrow.knock).toBe(KNOCK_PDA);
});
});