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.

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.js
index 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, sharesD
return 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.js
index 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, idempotencyKey
const 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, idempotencyKey
status: '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, idempotencyKey
const { 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, idempotenc
const 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.js
new file mode 100644
index 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);
+ });
+});