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(solana): make drop payouts and circulation survive an unreadable chain, and stop calling an RPC outage a missing mint

nirholas85ff038c387e
diff --git a/api/_lib/circulation.js b/api/_lib/circulation.js
index 9b75ac57d..b6b7d622a 100644
--- a/api/_lib/circulation.js
+++ b/api/_lib/circulation.js
@@ -17,6 +17,7 @@
// neither set the engine is fully inert.
import { sql } from './db.js';
+import { blockhashKey, getRecentBlockhashInfo, mintDecimals } from './solana/read-guards.js';
import { env } from './env.js';
import { confirmOrThrow } from './solana/confirm.js';
import { randomUUID } from 'node:crypto';
@@ -325,7 +326,15 @@ async function transferSol(conn, fromKp, toAddress, lamports) {
const MAX_ATTEMPTS = 2;
let lastErr;
for (let attempt = 0; attempt < MAX_ATTEMPTS; attempt++) {
- const { blockhash, lastValidBlockHeight } = await conn.getLatestBlockhash('confirmed');
+ // The retry exists to escape an expired blockhash, so it forces a fresh
+ // read; the first attempt may take the cached one. When the chain cannot be
+ // read at all, the guard serves a cached hash that is still inside its
+ // validity window rather than failing the transfer outright.
+ const { blockhash, lastValidBlockHeight } = await getRecentBlockhashInfo(
+ conn,
+ blockhashKey({ url: env.SOLANA_RPC_URL }),
+ { forceFresh: attempt > 0 },
+ );
const message = new TransactionMessage({
payerKey: fromKp.publicKey,
recentBlockhash: blockhash,
@@ -760,17 +769,18 @@ async function transferThreeWithReference(conn, fromKp, toAddress, atomic, refer
getAssociatedTokenAddressSync,
createTransferCheckedInstruction,
createAssociatedTokenAccountIdempotentInstruction,
- getMint,
} = await import('@solana/spl-token');
const mintKey = new PublicKey(THREE_MINT());
const recipKey = new PublicKey(toAddress);
- const mintInfo = await getMint(conn, mintKey);
+ // $THREE's decimals are a constant, so this costs no network read and a dead
+ // RPC cannot stall a circulation transfer over a value we already know.
+ const decimals = await mintDecimals(conn, mintKey);
const fromAta = getAssociatedTokenAddressSync(mintKey, fromKp.publicKey);
const toAta = getAssociatedTokenAddressSync(mintKey, recipKey);
const transferIx = createTransferCheckedInstruction(
- fromAta, mintKey, toAta, fromKp.publicKey, atomic, mintInfo.decimals,
+ fromAta, mintKey, toAta, fromKp.publicKey, atomic, decimals,
);
transferIx.keys.push({ pubkey: referenceKey, isSigner: false, isWritable: false });
@@ -784,7 +794,7 @@ async function transferThreeWithReference(conn, fromKp, toAddress, atomic, refer
const feeAta = getAssociatedTokenAddressSync(mintKey, feeKey);
ixs.push(createAssociatedTokenAccountIdempotentInstruction(fromKp.publicKey, feeAta, feeKey, mintKey));
ixs.push(createTransferCheckedInstruction(
- fromAta, mintKey, feeAta, fromKp.publicKey, feeLeg.atomics, mintInfo.decimals,
+ fromAta, mintKey, feeAta, fromKp.publicKey, feeLeg.atomics, decimals,
));
}
diff --git a/api/_lib/irl-drops.js b/api/_lib/irl-drops.js
index 8d78d5028..102f1d3b4 100644
--- a/api/_lib/irl-drops.js
+++ b/api/_lib/irl-drops.js
@@ -22,12 +22,13 @@ import bs58 from 'bs58';
import { Keypair, PublicKey, SystemProgram } from '@solana/web3.js';
import {
getAssociatedTokenAddress,
- createAssociatedTokenAccountInstruction,
+ createAssociatedTokenAccountIdempotentInstruction,
createTransferInstruction,
getAccount,
} from '@solana/spl-token';
import { sql } from './db.js';
+import { ataExists } from './solana/read-guards.js';
import { env } from './env.js';
import { sha256 } from './crypto.js';
import { encodeGeohash } from './geohash.js';
@@ -467,8 +468,14 @@ export async function releaseFromEscrow({ drop, toAddress, atomics }) {
const mint = new PublicKey(mintForAsset(drop.asset, drop.network));
const fromATA = await getAssociatedTokenAddress(mint, escrowKp.publicKey);
const toATA = await getAssociatedTokenAddress(mint, recipient);
- if (!(await conn.getAccountInfo(toATA))) {
- instructions.push(createAssociatedTokenAccountInstruction(feePayer.publicKey, toATA, recipient, mint));
+// The create is the IDEMPOTENT variant on purpose: it pairs with ataExists,
+// which fails open to "missing" when the chain cannot be read. With the plain
+// create that guess would be unsafe (a create for an account that already
+// exists fails the whole transaction); with this one an unnecessary create is a
+// no-op, so a dead RPC costs nothing and the probe-then-submit race disappears
+// with it.
+ if (!(await ataExists(conn, toATA))) {
+ instructions.push(createAssociatedTokenAccountIdempotentInstruction(feePayer.publicKey, toATA, recipient, mint));
}
instructions.push(createTransferInstruction(fromATA, toATA, escrowKp.publicKey, amount));
}
@@ -510,8 +517,8 @@ export async function sweepRefund({ drop }) {
try { amount = (await getAccount(conn, fromATA)).amount; } catch { amount = 0n; }
if (amount <= 0n) return 'empty';
const toATA = await getAssociatedTokenAddress(mint, recipient);
- if (!(await conn.getAccountInfo(toATA))) {
- instructions.push(createAssociatedTokenAccountInstruction(feePayer.publicKey, toATA, recipient, mint));
+ if (!(await ataExists(conn, toATA))) {
+ instructions.push(createAssociatedTokenAccountIdempotentInstruction(feePayer.publicKey, toATA, recipient, mint));
}
instructions.push(createTransferInstruction(fromATA, toATA, escrowKp.publicKey, amount));
}
diff --git a/api/_lib/sealed-drop-funding.js b/api/_lib/sealed-drop-funding.js
index 0e11238db..73a9ff2a8 100644
--- a/api/_lib/sealed-drop-funding.js
+++ b/api/_lib/sealed-drop-funding.js
@@ -40,12 +40,13 @@ import {
} from '@solana/web3.js';
import {
getAssociatedTokenAddress,
- createAssociatedTokenAccountInstruction,
+ createAssociatedTokenAccountIdempotentInstruction,
createTransferInstruction,
getAccount,
} from '@solana/spl-token';
import { env } from './env.js';
+import { ataExists } from './solana/read-guards.js';
import { solanaConnection } from './agent-pumpfun.js';
import { submitProtected } from './execution-engine.js';
import { SOLANA_USDC_MINT } from '../payments/_config.js';
@@ -196,9 +197,14 @@ export async function fundDropAddress({ toAddress, asset, atomics }) {
const mint = new PublicKey(mintForAsset(asset));
const fromATA = await getAssociatedTokenAddress(mint, payer.publicKey);
const toATA = await getAssociatedTokenAddress(mint, recipient);
- const toInfo = await conn.getAccountInfo(toATA);
- if (!toInfo) {
- instructions.push(createAssociatedTokenAccountInstruction(payer.publicKey, toATA, recipient, mint));
+// The create is the IDEMPOTENT variant on purpose: it pairs with ataExists,
+// which fails open to "missing" when the chain cannot be read. With the plain
+// create that guess would be unsafe (a create for an account that already
+// exists fails the whole transaction); with this one an unnecessary create is a
+// no-op, so a dead RPC costs nothing and the probe-then-submit race disappears
+// with it.
+ if (!(await ataExists(conn, toATA))) {
+ instructions.push(createAssociatedTokenAccountIdempotentInstruction(payer.publicKey, toATA, recipient, mint));
}
instructions.push(createTransferInstruction(fromATA, toATA, payer.publicKey, amount));
}
@@ -294,9 +300,8 @@ export async function sweepReclaim({ record, dropSecretKey, toAddress }) {
return { reclaimTx: 'empty', alreadyReclaimed: false };
}
const toATA = await getAssociatedTokenAddress(mint, recipient);
- const toInfo = await conn.getAccountInfo(toATA);
- if (!toInfo) {
- instructions.push(createAssociatedTokenAccountInstruction(feePayer.publicKey, toATA, recipient, mint));
+ if (!(await ataExists(conn, toATA))) {
+ instructions.push(createAssociatedTokenAccountIdempotentInstruction(feePayer.publicKey, toATA, recipient, mint));
}
instructions.push(createTransferInstruction(fromATA, toATA, dropKp.publicKey, amount));
}
diff --git a/api/_lib/token/token-program.js b/api/_lib/token/token-program.js
index 4b860dd07..e882a475f 100644
--- a/api/_lib/token/token-program.js
+++ b/api/_lib/token/token-program.js
@@ -13,6 +13,7 @@
// classification (and throws a typed 422 for a non-SPL owner).
import { PublicKey } from '@solana/web3.js';
+import { readAccountInfoOrNull, rpcUnavailableError } from '../solana/read-guards.js';
import { resolveTokenProgramForMintOwner } from '../pump-trade-args.js';
const cache = new Map();
@@ -29,7 +30,13 @@ export async function tokenProgramIdForMint(connection, mint) {
const cached = cache.get(key);
if (cached) return cached;
- const info = await connection.getAccountInfo(mintPk);
+ // An unreadable chain is NOT a missing mint. Reporting it as 422
+ // mint_not_found told the caller its input was invalid and sent it away for
+ // good, when the right answer is "ask again shortly": the two are
+ // indistinguishable from a bare getAccountInfo, so the transport failure has
+ // to be classified before the null is interpreted.
+ const { info, cause } = await readAccountInfoOrNull(connection, mintPk, { withCause: true });
+ if (cause) throw rpcUnavailableError(cause);
if (!info) {
const e = new Error(`mint account not found: ${key}`);
e.status = 422;
diff --git a/api/irl/drops.js b/api/irl/drops.js
index b6f03e64f..5d6eafda4 100644
--- a/api/irl/drops.js
+++ b/api/irl/drops.js
@@ -20,11 +20,12 @@
import { PublicKey, SystemProgram } from '@solana/web3.js';
import {
getAssociatedTokenAddress,
- createAssociatedTokenAccountInstruction,
+ createAssociatedTokenAccountIdempotentInstruction,
createTransferInstruction,
} from '@solana/spl-token';
import { cors, json, wrap, error, rateLimited, readJson } from '../_lib/http.js';
+import { ataExists } from '../_lib/solana/read-guards.js';
import { limits, clientIp, limitFailClosedRead } from '../_lib/rate-limit.js';
import { getSessionUser } from '../_lib/auth.js';
import { readDeviceToken } from '../_lib/irl-auth.js';
@@ -328,8 +329,14 @@ async function fundEscrowFromAgent({ keypair, escrowAddress, asset, atomics, net
const mint = new PublicKey(mintFor(asset, network));
const fromATA = await getAssociatedTokenAddress(mint, keypair.publicKey);
const toATA = await getAssociatedTokenAddress(mint, recipient);
- if (!(await conn.getAccountInfo(toATA))) {
- instructions.push(createAssociatedTokenAccountInstruction(keypair.publicKey, toATA, recipient, mint));
+// The create is the IDEMPOTENT variant on purpose: it pairs with ataExists,
+// which fails open to "missing" when the chain cannot be read. With the plain
+// create that guess would be unsafe (a create for an account that already
+// exists fails the whole transaction); with this one an unnecessary create is a
+// no-op, so a dead RPC costs nothing and the probe-then-submit race disappears
+// with it.
+ if (!(await ataExists(conn, toATA))) {
+ instructions.push(createAssociatedTokenAccountIdempotentInstruction(keypair.publicKey, toATA, recipient, mint));
}
instructions.push(createTransferInstruction(fromATA, toATA, keypair.publicKey, amount));
}
diff --git a/api/portfolio/[action].js b/api/portfolio/[action].js
index ce22dcd35..95c5ee24f 100644
--- a/api/portfolio/[action].js
+++ b/api/portfolio/[action].js
@@ -361,7 +361,7 @@ async function sendSolana({ agent, asset, recipient, amount, userId }) {
e.status = 400;
throw e;
}
- const { getAssociatedTokenAddress, createAssociatedTokenAccountInstruction, createTransferInstruction } = await import('@solana/spl-token');
+ const { getAssociatedTokenAddress, createAssociatedTokenAccountIdempotentInstruction, createTransferInstruction } = await import('@solana/spl-token');
const mintPk = new PublicKey(asset);
const mintInfo = await conn.getParsedAccountInfo(mintPk);
@@ -374,7 +374,7 @@ async function sendSolana({ agent, asset, recipient, amount, userId }) {
// runtime treats as a no-op, whereas throwing here loses the whole transfer.
const recipientAccountExists = await ataExists(conn, recipientAta);
if (!recipientAccountExists) {
- tx.add(createAssociatedTokenAccountInstruction(kp.publicKey, recipientAta, recipientPk, mintPk));
+ tx.add(createAssociatedTokenAccountIdempotentInstruction(kp.publicKey, recipientAta, recipientPk, mintPk));
}
const amountUnits = parseAmountToBaseUnits(amount, decimals);
tx.add(createTransferInstruction(senderAta, recipientAta, kp.publicKey, amountUnits));