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
fix(vaults): burn shares and reserve fees before paying so concurrent redeems cannot double-pay
nirholas42b07a654edd
diff --git a/api/_lib/vault-store.js b/api/_lib/vault-store.jsindex a14dcb4ba..dfc2a987f 100644--- a/api/_lib/vault-store.js+++ b/api/_lib/vault-store.js@@ -301,6 +301,44 @@ export async function applyBackerDelta({ vaultId, userId, backerAgentId, sharesDreturn row;}+/**+ * Burn `shares` from a backer's position atomically, only if the position still+ * holds them. Returns the updated row, or null when another redemption already+ * took them. Redemption burns BEFORE it pays: a read-then-pay let N concurrent+ * redeems each pay the full position out of other backers' USDC.+ */+export async function reserveBackerShares(vaultId, userId, shares) {+ const [row] = await sql`+ UPDATE vault_backers SET shares = shares - ${String(shares)}, updated_at = now()+ WHERE vault_id = ${vaultId} AND user_id = ${userId} AND shares >= ${String(shares)}+ RETURNING shares+ `;+ return row || null;+}++/** Give back shares a reservation burned when its payout did not happen. */+export async function releaseBackerShares(vaultId, userId, shares) {+ await sql`+ UPDATE vault_backers SET shares = shares + ${String(shares)}, updated_at = now()+ WHERE vault_id = ${vaultId} AND user_id = ${userId}+ `;+}++/**+ * Take `atomics` out of the vault's accrued fee atomically, only if that much is+ * still accrued. Returns the remaining accrual, or null when a concurrent claim+ * already took it. The fee claim reserves BEFORE it pays for the same reason+ * reserveBackerShares exists.+ */+export async function reserveAccruedFee(vaultId, atomics) {+ const [row] = await sql`+ UPDATE agent_vaults SET accrued_fee_atomics = accrued_fee_atomics - ${String(atomics)}, updated_at = now()+ WHERE id = ${vaultId} AND accrued_fee_atomics >= ${String(atomics)}+ RETURNING accrued_fee_atomics+ `;+ return row ? row.accrued_fee_atomics : null;+}+/** Move total_shares by a signed delta and ratchet the high-water share-price peak. */export async function applyVaultShareDelta(vaultId, sharesDelta, peakSharePriceE6 = null) {const [row] = await sql`diff --git a/api/_lib/vault-transfer.js b/api/_lib/vault-transfer.jsindex 8cfb802a8..9f1a9fa31 100644--- a/api/_lib/vault-transfer.js+++ b/api/_lib/vault-transfer.js@@ -28,6 +28,7 @@ import { explorerTxUrl } from './avatar-wallet.js';import {getVaultWithSecret, getBacker, getOpenPositions,recordVaultEvent, applyBackerDelta, applyVaultShareDelta, applyAccruedFee,+ reserveBackerShares, releaseBackerShares, reserveAccruedFee,} from './vault-store.js';import { recoverVaultKeypair, computeVaultNav, readVaultUsdcAtomics } from './vault-wallet.js';import { USDC_MINT_BY_NETWORK, USDC_DECIMALS } from './vault-jupiter.js';@@ -192,6 +193,12 @@ export async function redeemFromVault({ vaultId, userId, shares, idempotencyKeyconst toAddress = recipient?.addr;if (!toAddress) return { status: 'failed', code: 'no_recipient', message: 'the funding wallet for this position is no longer available' };+ // Burn the shares BEFORE paying. The position read above is a plain SELECT,+ // so without this N concurrent redeems (each with its own idempotency key)+ // all saw the same shares and each paid the full net out of the pool.+ const burned = await reserveBackerShares(vault.id, userId, redeemNow);+ if (!burned) return { status: 'failed', code: 'in_flight', message: 'another redemption already claimed these shares; check the ledger before retrying' };+// Claim a pending event keyed by the caller's idempotency key BEFORE paying —// a retry/double-submit with the same key collides here and never pays twice.const claimId = await recordVaultEvent({@@ -201,7 +208,10 @@ export async function redeemFromVault({ vaultId, userId, shares, idempotencyKeystatus: 'pending', reason: 'redeem', idempotencyKey: idempotencyKey || `redeem:${vault.id}:${userId}:${redeemNow}`,meta: { gross_atomics: String(settle.grossPayout), fee_atomics: String(settle.fee), net_atomics: String(settle.netPayout), gain_atomics: String(settle.gain), shares_burned: String(redeemNow) },});- if (claimId == null) return { status: 'failed', code: 'in_flight', message: 'a redemption with this id is already in progress — check the ledger before retrying' };+ if (claimId == null) {+ await releaseBackerShares(vault.id, userId, redeemNow);+ return { status: 'failed', code: 'in_flight', message: 'a redemption with this id is already in progress; check the ledger before retrying' };+ }let signature;try {@@ -209,6 +219,7 @@ export async function redeemFromVault({ vaultId, userId, shares, idempotencyKey} catch (e) {const { updateVaultEvent } = await import('./vault-store.js');await updateVaultEvent(claimId, { status: 'failed', meta: { error: e?.code || 'payout_failed' } });+ await releaseBackerShares(vault.id, userId, redeemNow);return { status: 'failed', code: e?.code || 'payout_failed', message: 'the redemption payout could not be confirmed — your shares were not burned' };}@@ -216,9 +227,10 @@ export async function redeemFromVault({ vaultId, userId, shares, idempotencyKeyconst { updateVaultEvent } = await import('./vault-store.js');await updateVaultEvent(claimId, { status: 'ok', signature });+ // The shares were already burned by reserveBackerShares; settle the rest.await applyBackerDelta({vaultId: vault.id, userId, backerAgentId: backer.backer_agent_id,- sharesDelta: -redeemNow, basisDelta: -settle.costPortion,+ sharesDelta: 0n, basisDelta: -settle.costPortion,redeemedDelta: settle.netPayout, realizedGainDelta: settle.gain, feesPaidDelta: settle.fee,});await applyVaultShareDelta(vault.id, -redeemNow);@@ -260,19 +272,32 @@ export async function claimVaultFees({ vaultId, ownerUserId, toAgent, idempotencconst claimable = accrued < free ? accrued : free;if (claimable <= 0n) return { status: 'queued', code: 'insufficient_liquidity', message: 'fees are accrued but the vault has no liquid USDC to pay them right now', detail: { accrued_atomics: String(accrued) } };+ // Take the fee out of the accrual BEFORE paying, then claim the ledger row.+ // Paying first let N concurrent claims each pay the full accrual out of the+ // pooled USDC, i.e. out of backers' principal.+ if ((await reserveAccruedFee(vault.id, claimable)) == null) {+ return { status: 'failed', code: 'in_flight', message: 'another fee claim already took these fees; check the ledger before retrying' };+ }+ const eventId = await recordVaultEvent({+ vaultId: vault.id, type: 'fee_claim', userId: ownerUserId, backerAgentId: toAgent.id,+ atomicsDelta: String(-claimable), status: 'pending', reason: 'fee_claim',+ idempotencyKey: idempotencyKey || null, meta: { to: toAddress, claimed_atomics: String(claimable) },+ });+ if (eventId == null) {+ await applyAccruedFee(vault.id, claimable);+ return { status: 'replayed', code: 'in_flight', message: 'a fee claim with this id was already recorded' };+ }++ const { updateVaultEvent } = await import('./vault-store.js');let signature;try {({ signature } = await payoutUsdc({ vault, toAddress, atomics: claimable, userId: ownerUserId, reason: 'vault_fee_claim' }));} catch (e) {+ await updateVaultEvent(eventId, { status: 'failed', meta: { error: e?.code || 'payout_failed' } });+ await applyAccruedFee(vault.id, claimable);return { status: 'failed', code: e?.code || 'payout_failed', message: 'the fee claim could not be confirmed' };}- const eventId = await recordVaultEvent({- vaultId: vault.id, type: 'fee_claim', userId: ownerUserId, backerAgentId: toAgent.id,- atomicsDelta: String(-claimable), signature, status: 'ok', reason: 'fee_claim',- idempotencyKey: idempotencyKey || `fee_claim:${signature}`, meta: { to: toAddress, claimed_atomics: String(claimable) },- });- if (eventId == null) return { status: 'replayed', signature };- await applyAccruedFee(vault.id, -claimable);+ await updateVaultEvent(eventId, { status: 'ok', signature });logAudit({ userId: ownerUserId, action: 'vault.fee_claim', resourceId: vault.id, meta: { claimed_atomics: String(claimable), signature } });return {diff --git a/tests/vault-redeem-reservation.test.js b/tests/vault-redeem-reservation.test.jsnew file mode 100644index 000000000..3aba02973--- /dev/null+++ b/tests/vault-redeem-reservation.test.js@@ -0,0 +1,101 @@+// Vault redemptions and fee claims reserve BEFORE they pay.+//+// Both paths used to read the position (or the accrued fee) with a plain SELECT,+// pay USDC, and only then debit the books. N concurrent requests, each with its+// own idempotency key, all saw the same balance and each paid it in full out of+// the pooled vault USDC, i.e. out of the other backers' principal. These tests+// pin the order: an atomic reservation first, the payout only when it succeeds,+// and the reservation handed back when the payout does not happen.++import { describe, it, expect, vi, beforeEach } from 'vitest';++const VAULT = { id: 'v1', network: 'mainnet', total_shares: '1000000', performance_fee_bps: 0, owner_user_id: 'owner', accrued_fee_atomics: '500000', vault_address: 'VaultAddr', encrypted_secret: 'enc' };+const order = [];+const store = {+ getVaultWithSecret: vi.fn(async () => ({ ...VAULT })),+ getBacker: vi.fn(async () => ({ shares: '1000000', cost_basis_atomics: '1000000', backer_agent_id: 'agent-b' })),+ getOpenPositions: vi.fn(async () => []),+ recordVaultEvent: vi.fn(async () => { order.push('event'); return 7; }),+ updateVaultEvent: vi.fn(async () => {}),+ applyBackerDelta: vi.fn(async () => ({})),+ applyVaultShareDelta: vi.fn(async () => ({})),+ applyAccruedFee: vi.fn(async () => '0'),+ reserveBackerShares: vi.fn(async () => { order.push('reserve'); return { shares: '0' }; }),+ releaseBackerShares: vi.fn(async () => { order.push('release'); }),+ reserveAccruedFee: vi.fn(async () => { order.push('reserveFee'); return '0'; }),+};+vi.mock('../api/_lib/vault-store.js', () => store);+vi.mock('../api/_lib/vault-wallet.js', () => ({+ recoverVaultKeypair: vi.fn(async () => {+ const { Keypair } = await import('@solana/web3.js');+ return Keypair.generate();+ }),+ computeVaultNav: vi.fn(async () => ({ navAtomics: 1_000_000n, freeAtomics: 1_000_000n, priced: true })),+ readVaultUsdcAtomics: vi.fn(async () => 1_000_000n),+}));+const submitProtected = vi.fn(async () => { order.push('pay'); return { signature: 'sig1' }; });+vi.mock('../api/_lib/execution-engine.js', () => ({ submitProtected: (...a) => submitProtected(...a) }));+vi.mock('../api/_lib/agent-pumpfun.js', () => ({ solanaConnection: vi.fn(() => ({})) }));+vi.mock('../api/_lib/agent-usdc-transfer.js', () => ({ transferUsdcGuarded: vi.fn() }));+vi.mock('../api/_lib/audit.js', () => ({ logAudit: vi.fn() }));+vi.mock('../api/_lib/db.js', () => ({+ sql: vi.fn(async () => [{ addr: '9xQeWvG816bUx9EPjHmaT23yvVM2ZWbrrpZb9PusVFin' }]),+}));++const { redeemFromVault, claimVaultFees } = await import('../api/_lib/vault-transfer.js');++beforeEach(() => {+ order.length = 0;+ vi.clearAllMocks();+ store.reserveBackerShares.mockImplementation(async () => { order.push('reserve'); return { shares: '0' }; });+ store.reserveAccruedFee.mockImplementation(async () => { order.push('reserveFee'); return '0'; });+ submitProtected.mockImplementation(async () => { order.push('pay'); return { signature: 'sig1' }; });+});++describe('redeemFromVault', () => {+ it('burns the shares before it pays and does not burn them again after', async () => {+ const r = await redeemFromVault({ vaultId: 'v1', userId: 'u1', shares: 'max', idempotencyKey: 'k1' });+ expect(r.status).toBe('ok');+ expect(order.indexOf('reserve')).toBeLessThan(order.indexOf('pay'));+ expect(store.applyBackerDelta).toHaveBeenCalledWith(expect.objectContaining({ sharesDelta: 0n }));+ });++ it('never pays when a concurrent redemption already took the shares', async () => {+ store.reserveBackerShares.mockImplementation(async () => null);+ const r = await redeemFromVault({ vaultId: 'v1', userId: 'u1', shares: 'max', idempotencyKey: 'k2' });+ expect(r).toMatchObject({ status: 'failed', code: 'in_flight' });+ expect(submitProtected).not.toHaveBeenCalled();+ });++ it('hands the shares back when the payout fails', async () => {+ submitProtected.mockImplementation(async () => { throw Object.assign(new Error('rpc'), { code: 'send_failed' }); });+ const r = await redeemFromVault({ vaultId: 'v1', userId: 'u1', shares: 'max', idempotencyKey: 'k3' });+ expect(r.status).toBe('failed');+ expect(store.releaseBackerShares).toHaveBeenCalledWith('v1', 'u1', 1_000_000n);+ });+});++describe('claimVaultFees', () => {+ const toAgent = { id: 'agent-o', meta: { solana_address: '9xQeWvG816bUx9EPjHmaT23yvVM2ZWbrrpZb9PusVFin' } };++ it('reserves the accrued fee before it pays', async () => {+ const r = await claimVaultFees({ vaultId: 'v1', ownerUserId: 'owner', toAgent, idempotencyKey: 'f1' });+ expect(r.status).toBe('ok');+ expect(order.indexOf('reserveFee')).toBeLessThan(order.indexOf('pay'));+ expect(store.applyAccruedFee).not.toHaveBeenCalled();+ });++ it('never pays when a concurrent claim already took the fee', async () => {+ store.reserveAccruedFee.mockImplementation(async () => null);+ const r = await claimVaultFees({ vaultId: 'v1', ownerUserId: 'owner', toAgent, idempotencyKey: 'f2' });+ expect(r).toMatchObject({ status: 'failed', code: 'in_flight' });+ expect(submitProtected).not.toHaveBeenCalled();+ });++ it('restores the accrual when the payout fails', async () => {+ submitProtected.mockImplementation(async () => { throw Object.assign(new Error('rpc'), { code: 'send_failed' }); });+ const r = await claimVaultFees({ vaultId: 'v1', ownerUserId: 'owner', toAgent, idempotencyKey: 'f3' });+ expect(r.status).toBe('failed');+ expect(store.applyAccruedFee).toHaveBeenCalledWith('v1', 500000n);+ });+});