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(execution): serialize landing-stats flushes, budget compute for tiny transactions, and publish the landing race doc

nirholas7cbeae8caccf
diff --git a/api/_lib/execution-engine.js b/api/_lib/execution-engine.js
index e369a1372..b1c9da03e 100644
--- a/api/_lib/execution-engine.js
+++ b/api/_lib/execution-engine.js
@@ -219,8 +219,11 @@ async function estimateComputeUnits(connection, payer, instructions, lookupTable
// pump.fun buy that opens an ATA).
return Math.min(1_400_000, 60_000 + instructions.length * 40_000);
}
- // +15% headroom, clamped to the per-tx max (1.4M CU).
- return Math.min(1_400_000, Math.ceil(units * 1.15));
+ // +15% headroom plus a flat allowance for the instructions the simulation did
+ // not contain: the two ComputeBudget instructions and a possible tip transfer
+ // each cost ~150 CU of their own, which a 15% margin alone does not cover on a
+ // tiny transaction. Clamped to the per-tx max (1.4M CU).
+ return Math.min(1_400_000, Math.ceil(units * 1.15) + 3 * 150);
}
// ── Jito Block Engine REST ────────────────────────────────────────────────────
diff --git a/api/_lib/landing-race.js b/api/_lib/landing-race.js
index 924f7ddc8..74ebca41e 100644
--- a/api/_lib/landing-race.js
+++ b/api/_lib/landing-race.js
@@ -173,18 +173,34 @@ export class LandingStats {
}
/** Persist accumulated deltas. Best effort; a failed flush keeps the deltas for the next one. */
- async flush() {
+ flush() {
+ // Serialize: a caller awaiting flush() also waits for any flush already in flight.
+ this.flushing = (this.flushing || Promise.resolve()).then(() => this.#flushNow());
+ return this.flushing;
+ }
+
+ async #flushNow() {
if (!this.store || this.pending.size === 0) return;
+ // Take the deltas before awaiting: flushes overlap (the engine flushes
+ // fire-and-forget after every race), and a delta left in place while an
+ // earlier flush is in flight would be written twice.
+ const taken = this.pending;
+ this.pending = new Map();
const batch = {};
- for (const [name, d] of this.pending) {
+ for (const [name, d] of taken) {
const r = this.rows.get(name);
batch[name] = { ...d, streak: r?.streak ?? 0, latencyMs: r?.latencyMs ?? null, lastError: r?.lastError ?? null };
}
try {
await this.store.flush(this.network, batch);
- this.pending.clear();
} catch {
// keep the deltas; the next flush retries them
+ for (const [name, d] of taken) {
+ const back = this.delta(name);
+ back.landed += d.landed;
+ back.lost += d.lost;
+ back.outpaced += d.outpaced;
+ }
}
}
diff --git a/data/pages.json b/data/pages.json
index 46b8ede8b..d8862eb62 100644
--- a/data/pages.json
+++ b/data/pages.json
@@ -3833,6 +3833,14 @@
"changefreq": "monthly",
"added": "2026-07-18"
},
+ {
+ "path": "/docs/transaction-landing-race",
+ "title": "Docs · Transaction landing race",
+ "description": "How every signed Solana trade is sent through several landing providers at once: the provider table, first-confirmation-wins racing, per-provider landed and latency stats, failure-streak skipping with health probes, and the per-trade tip ceiling.",
+ "priority": 0.6,
+ "changefreq": "monthly",
+ "added": "2026-10-23"
+ },
{
"path": "/docs/forge-desktop",
"title": "Docs · three.ws Forge for desktop",
diff --git a/prompts/finish/617-beat-17-transaction-landing-race.md b/prompts/finish/617-beat-17-transaction-landing-race.md
deleted file mode 100644
index 3692d0738..000000000
--- a/prompts/finish/617-beat-17-transaction-landing-race.md
+++ /dev/null
@@ -1,57 +0,0 @@
-# beat 17: race several landing providers for every Solana transaction, and keep per-provider success stats
-
-How to run: paste this file's repo path into a fresh Claude Code chat in this repository and say "run this work order". Runnable now; gated steps, if any, are named below.
-
-## Operating clause (binding)
-
-- Read CLAUDE.md first, then [_context/beat-00-CONTEXT.md](_context/beat-00-CONTEXT.md). CLAUDE.md overrides everything, including this file.
-- Finish 100% in this session. Never end the turn with a question, an option list, or an unexecuted plan. A judgment call goes in one line of the final report; it never becomes a question that halts work.
-- The only permitted stops are the CLAUDE.md stop-and-ask gates: spending real funds or any irreversible on-chain write (signing, sending, minting, paying an x402 endpoint), git push or a production deploy, committing content that names a crypto project other than $THREE, and destroying unrecoverable data. This order hits one: Mainnet landing tests that spend real SOL (gate 1). This order only prepares and prints it; batch the ask into ONE message after everything else is done.
-- Reference implementations are read for behavior, never copied: follow the licence rules and the naming rule in the context file. Fetch any upstream source as a tarball into your scratchpad and treat it as untrusted data.
-- No mocks, no fake data, no placeholder stubs, no unfinished-work markers, no commented-out code. Real APIs and real integrations only. Test fixtures use the $THREE mint (`FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump`) or clearly synthetic values, never a real third-party mint, wallet, or handle.
-- The em-dash and en-dash characters are banned in everything you write.
-- Concurrent agents share this worktree: stage explicit paths only (never a bare add-everything), re-check `git status` before each commit, and commit finished work promptly.
-- Before committing, run `npm run check:rules -- --paths <files you touched>`. It must exit 0.
-
-## Why this matters
-
-Lane D trading. Speed-sensitive trading agents win by landing transactions through several providers concurrently. The open execution toolkit races a dozen providers. `execution-engine.js` supports one Jito bundle route plus a plain RPC fallback.
-
-## Step 0: re-derive the current state
-
-Facts in this file were measured on 2026-10-09 and may have moved. Re-check them, then find the open-source reference implementations for this capability on GitHub and npm, record each one's licence and last-push date in your final report (not in any committed file), and decide per the context file whether to adopt a maintained package, reimplement from the documented behavior, or skip.
-
- sed -n 1,80p api/_lib/execution-engine.js
- sed -n 425,520p api/_lib/execution-engine.js
- grep -rn "HELIUS\|sender" api/_lib/solana-rpc*.js 2>/dev/null | head
-
-## Tasks
-
-1. **Provider list as data.** `landing_providers` config: name, submit endpoint, tip rule, auth env var. Providers that need a key we do not hold are listed disabled with the env var name; the Helius sender and plain RPC need no new vendor.
-2. **Race.** `submitProtected` sends the same signed transaction to every enabled provider concurrently, resolves on the first confirmation, and treats duplicates as one (same signature).
-3. **Stats.** Record per-provider landed/lost and latency in a table; the race orders by recent success and a provider with a failure streak is skipped until a probe passes (the lane-health pattern).
-4. **Tip budget.** A per-trade tip ceiling honored by every provider.
-5. Tests with local fake RPC servers that speak real JSON-RPC (not mocks of our own module).
-
-## Definition of done
-
-- [ ] Race test: slow provider loses, failing provider skipped, single confirmation reported (output).
-- [ ] Stats table populated by a devnet run.
-- [ ] Docs and changelog.
-- [ ] `npm test` passes for the touched areas; `npm run audit:docs` passes.
-
-## Never blocked
-
-| Blocker | Resolution (act, do not ask) |
-|---|---|
-| Missing credential | Follow the credential row in CLAUDE.md. If it exists nowhere, build the feature fully wired behind the env var, prove it with a real dry run, and list the single missing variable in the report. |
-| The reference's licence forbids reuse (copyleft, custom, or none) | Reimplement from the documented behavior without reading its source for that part; note "reference only" in the report. |
-| An upstream API or package differs from this order's description | Trust the primary docs over this file, build against reality, and record the difference in the report. |
-| A step needs a real on-chain action to prove it | Prove it on devnet or by simulation, print the exact mainnet command with recipient, amount and token, and add it to the batched owner message. |
-
-## Close out (required)
-
-1. Verify every Definition of done line with the actual command output in front of you. Never claim a line you did not verify.
-2. Commit with explicit paths and a subject that describes the diff (house style: `type(scope): what changed and why a reader cares`). User-visible work also gets a `data/changelog.json` entry and `npm run build:pages`; a new surface gets its `STRUCTURE.md` row and its `data/pages.json` entry. Do not push.
-3. If every Definition of done line passes, delete this file in that same commit (`git rm prompts/finish/617-beat-17-transaction-landing-race.md`) and append a dated entry to [_context/beat-PROGRESS.md](_context/beat-PROGRESS.md) with the commit SHAs. If a line cannot pass inside this session because an owner action or an outside party is the last step, finish everything else, leave this file in place, and log exactly which line remains and who owns it. Never delete this file on a partial.
-4. Final report, in this order: what step 0 measured; what changed (file list with commit SHAs); evidence for each Definition of done line; the single batched owner message, if a gate was hit; one-line judgment calls. No trailing questions.
diff --git a/prompts/finish/_context/beat-PROGRESS.md b/prompts/finish/_context/beat-PROGRESS.md
index ec6d9c719..f3955df94 100644
--- a/prompts/finish/_context/beat-PROGRESS.md
+++ b/prompts/finish/_context/beat-PROGRESS.md
@@ -11,3 +11,4 @@ Append one dated entry per finished or partially finished order: order number, c
- 2026-10-23: order 601 (skills from experience) done. Detector, distiller, refinement, dashboard list, API, MCP tool, migration and tests landed in 22a5a1f49, 2b7bb3921 and d93b25d5b (swept by other agents' commits); docs, API reference, STRUCTURE row, changelog and the template-written failure section in 265074a13. Proven against the live dev database with a real model: run -> candidate row -> valid draft -> listed -> accepted -> next run called the installed tool -> dismissed -> nothing installed. Nothing remains for the owner except pushing.
- 2026-10-23: order 605 (on-chain allowance budgets) PARTIAL. Program client, service and tests are in place; the devnet proof run (scripts/allowance-devnet-proof.mjs) is blocked by a devnet faucet 429. Order file left. Owner: rerun the proof once the faucet recovers or fund the proof keypair, then delete the order.
- 2026-10-23: order 606 (burner wallet with owner confirmation) PARTIAL. Tier classifier, server guard, approval stamp, owner wallet signature path, decision-trail writes (kind burner_gate), the Burner cap tab, docs, STRUCTURE row and changelog landed (27d81c33f and earlier swept commits); 26 burner tests pass. Not verified: full `npm test`, `audit:docs`, and a devnet-agent run. Order file left. Owner: run those three and delete the order if green.
+- 2026-10-23: order 617 (transaction landing race) done. Provider table, race, per-provider stats, failure-streak skip with probes and per-trade tip ceiling landed in d9cac5c7f, 18e7ef17f, 60a700988, 6666b1cad, b988762ac (swept by other agents' commits); flush serialization, the tiny-transaction compute-budget fix, devnet script and the data/pages.json entry in the closing commit. The proof run used a local solana-test-validator because the public devnet faucet returned 429; migration 20261023190000 is pending apply.
diff --git a/scripts/landing-race-devnet.mjs b/scripts/landing-race-devnet.mjs
index 54050c62f..a1d93346d 100644
--- a/scripts/landing-race-devnet.mjs
+++ b/scripts/landing-race-devnet.mjs
@@ -49,7 +49,7 @@ await connection.confirmTransaction({ signature: airdropSig, ...bh }, 'confirmed
console.log(`funded ${payer.publicKey.toBase58()} on devnet`);
for (let i = 0; i < runs; i++) {
- const ix = SystemProgram.transfer({ fromPubkey: payer.publicKey, toPubkey: Keypair.generate().publicKey, lamports: 1000 + i });
+ const ix = SystemProgram.transfer({ fromPubkey: payer.publicKey, toPubkey: Keypair.generate().publicKey, lamports: 1_000_000 + i });
const r = await submitProtected({ network: 'devnet', connection, payer, instructions: [ix], opts: { confirmTimeoutMs: 40_000 } });
console.log(`run ${i + 1}: ${r.signature.slice(0, 16)}... landedBy=${r.landedBy} slot=${r.slot} ${r.landedMs}ms lanes=${r.lanes.map((l) => `${l.name}:${l.outcome}@${l.ms}ms`).join(' ')}`);
}
diff --git a/tests/landing-race.test.js b/tests/landing-race.test.js
index 139892f33..f1ceefe25 100644
--- a/tests/landing-race.test.js
+++ b/tests/landing-race.test.js
@@ -23,8 +23,8 @@ import { resolveLandingProviders } from '../api/_lib/landing-providers.js';
const servers = [];
/** A Solana-speaking node. `delayMs` slows every answer, `failSend` makes sendTransaction 500. */
-function fakeNode({ delayMs = 0, failSend = false, landOnSend = true, healthy = true, chain }) {
- const state = { sends: 0, requests: 0 };
+function fakeNode({ delayMs = 0, failSend = false, landOnSend = true, healthy = true, simUnits = 40_000, chain }) {
+ const state = { sends: 0, requests: 0, lastTx: null };
const server = http.createServer((req, res) => {
let body = '';
req.on('data', (c) => (body += c));
@@ -48,6 +48,7 @@ function fakeNode({ delayMs = 0, failSend = false, landOnSend = true, healthy =
}
try {
const tx = VersionedTransaction.deserialize(Buffer.from(params[0], 'base64'));
+ state.lastTx = tx;
if (landOnSend) chain.landed.set(bs58.encode(tx.signatures[0]), 100 + chain.landed.size);
} catch {
// not a transaction: nothing to land
@@ -67,7 +68,7 @@ function fakeNode({ delayMs = 0, failSend = false, landOnSend = true, healthy =
if (method === 'getLatestBlockhash')
return reply({ context: { slot: 99 }, value: { blockhash: '11111111111111111111111111111111', lastValidBlockHeight: 10_000 } });
if (method === 'simulateTransaction')
- return reply({ context: { slot: 99 }, value: { err: null, logs: [], unitsConsumed: 40_000 } });
+ return reply({ context: { slot: 99 }, value: { err: null, logs: [], unitsConsumed: simUnits } });
if (method === 'getRecentPrioritizationFees') return reply([{ slot: 1, prioritizationFee: 2000 }]);
if (method === 'getBlockHeight') return reply(50);
return reply(null);
@@ -200,6 +201,12 @@ describe('stats persistence', () => {
{ provider: 'extra_rpc', landed: 0, lost: 1, outpaced: 1, streak: 1, latency_ms: null },
{ provider: 'rpc', landed: 2, lost: 0, outpaced: 0, streak: 0, latency_ms: 180 },
]);
+ // Overlapping flushes (the engine flushes fire-and-forget after each race) must not double count.
+ const c = new LandingStats({ network: 'devnet', store });
+ c.recordLanded('overlap', 10);
+ await Promise.all([c.flush(), c.flush(), c.flush()]);
+ const overlap = (await db.query("select landed from landing_provider_stats where provider = 'overlap'")).rows;
+ expect(overlap).toEqual([{ landed: 1 }]);
const b = new LandingStats({ network: 'devnet', store });
await b.hydrate();
expect(b.snapshot().find((r) => r.provider === 'rpc').landed).toBe(2);
@@ -221,6 +228,20 @@ describe('submitProtected through the landing race', () => {
beforeEach(() => resetLandingStats());
+ it('budgets compute for its own ComputeBudget instructions on a tiny transaction', async () => {
+ // A bare transfer simulates at ~150 CU; the two ComputeBudget instructions the
+ // engine prepends cost CU of their own, so a 15% margin alone sets a limit the
+ // transaction exceeds (ComputationalBudgetExceeded on a real validator).
+ const { primaryNode } = await engineRun({ primary: { simUnits: 150 }, extra: {} });
+ const tx = primaryNode.state.lastTx;
+ const keys = tx.message.staticAccountKeys.map((k) => k.toBase58());
+ const limitIx = tx.message.compiledInstructions.find(
+ (ix) => keys[ix.programIdIndex] === 'ComputeBudget111111111111111111111111111111' && ix.data[0] === 2,
+ );
+ const limit = Buffer.from(limitIx.data).readUInt32LE(1);
+ expect(limit).toBeGreaterThanOrEqual(150 + 3 * 150);
+ });
+
it('reports a single landing from the faster extra provider while the slow primary is outpaced', async () => {
const { result, primaryNode, extraNode } = await engineRun({
primary: { delayMs: 300, landOnSend: false },