brainblast 0.7.5 → 0.7.6

package/dist/packs/README.md

@@ -0,0 +1,33 @@
+# Protocol Pack Library
+
+Every Solana app is built on some combination of Jupiter, Raydium, Pyth, Meteora, Jito, … — each with its own silent footguns. A **pack per protocol** means you opt into research-and-enforcement for the exact stack you build on, before a line is written:
+
+```bash
+brainblast --packs jupiter,pyth .
+```
+
+Packs are **opt-in** (not loaded by default), **pure data** (rules bind only to brainblast's vetted checker templates — no executable code ships in a pack), and **proven** (every rule ships `vulnerable/` + `fixed/` fixtures that must go RED → GREEN). List them anytime:
+
+```bash
+brainblast packs            # the library, by protocol name
+brainblast pack validate <dir>   # re-prove a pack RED → GREEN
+```
+
+## Bundled packs
+
+| Protocol | Pack | Trap |
+|----------|------|------|
+| **Jupiter** | `jupiter-quote-zero-slippage` | `quoteGet({ slippageBps: 0 })` — MEV/sandwich exposure |
+| **Raydium** | `raydium-compute-zero-slippage` | `computeAmountOut({ slippage: 0 })` — no min-out floor |
+| **Pyth** | `pyth-price-unchecked-staleness` | `getPriceUnchecked()` — trades on a stale oracle |
+| **Meteora** | `meteora-dlmm-zero-min-out` | `swap({ minOutAmount: new BN(0) })` — no slippage floor |
+| **Jito** | `jito-bundle-zero-tip` | `sendBundle({ tipLamports: new BN(0) })` — bundle never lands |
+| **Metaplex** | `metaplex-nft-royalty-zero` | `create({ sellerFeeBasisPoints: 0 })` — zero royalties |
+| **Solana** | `solana-sendtx-unconfirmed` | `sendTransaction()` without confirmation — silent drop |
+| **SPL** | `spl-transfer-not-checked-in-payout` | `createTransferInstruction` vs `…Checked` |
+
+`--packs <name>` resolves a protocol name (e.g. `pyth`) to its pack, or takes an explicit pack directory.
+
+## The compounding moat
+
+Each pack someone contributes makes brainblast more valuable for the next dev building on that protocol. To add one: `brainblast pack init packs/<id> --id <id> …`, write a rule that binds to a vetted checker, add `fixtures/<id>/{vulnerable,fixed}/`, and `brainblast pack validate packs/<id>` until it proves RED → GREEN. See any pack here as a template.

package/dist/packs/jito-bundle-zero-tip/README.md

@@ -0,0 +1,33 @@
+# jito-bundle-zero-tip
+
+**Severity:** HIGH
+
+## What's the trap?
+
+Jito bundles are ordered by their **tip**. The block engine prioritizes bundles that pay more; a bundle that tips **0** is deprioritized and, under any competition, simply never lands.
+
+The trap is that sending a zero-tip bundle still *succeeds* at the API level — you get a bundle id back — so the code proceeds as if the transactions submitted. They didn't. For an arbitrage or liquidation bot, "the bundle silently never landed" is the difference between a profit and a missed opportunity (or a half-executed position).
+
+## Why it's silent
+
+`sendBundle(...)` returns a bundle id regardless of the tip. Nothing throws. The bundle just isn't included, and you only notice when on-chain state never reflects your transactions.
+
+## The fix
+
+```typescript
+// BEFORE (vulnerable — no tip, bundle won't land)
+return sendBundle({ transactions, tipLamports: new BN(0) });
+
+// AFTER (fixed — nonzero tip the block engine can prioritize)
+return sendBundle({ transactions, tipLamports: new BN(100_000) });
+```
+
+In production, **scale the tip with competition** rather than hardcoding it.
+
+## Scope
+
+This rule (`object-arg-property-forbidden-literal`, `BN(0)`-aware) targets the common wrapper signature `sendBundle({ ..., tipLamports })` and fires only in files that import a Jito SDK. The positional `Bundle.addTipTx(payer, lamports, tipAccount, blockhash)` form isn't matched by a single object-field rule — verify that path manually, or add a project-local rule for your exact tip-builder signature.
+
+## References
+
+- [Jito — low-latency transaction send](https://docs.jito.wtf/lowlatencytxnsend/)

package/dist/packs/jito-bundle-zero-tip/brainblast-pack.yaml

@@ -0,0 +1,5 @@
+id: jito-bundle-zero-tip
+name: Jito bundle zero tip
+version: 0.1.0
+author: DSB-117
+description: "Flags Jito bundle sends with a tip of 0 (including new BN(0)) — a bundle with no tip is deprioritized by the block engine and typically never lands."

package/dist/packs/jito-bundle-zero-tip/fixtures/jito-bundle-zero-tip/fixed/bundle.ts

@@ -0,0 +1,13 @@
+import { searcherClient } from "jito-ts/dist/sdk/block-engine/searcher.js";
+import BN from "bn.js";
+
+async function sendBundle(opts: { transactions: any[]; tipLamports: BN }) {
+  const client = searcherClient("https://mainnet.block-engine.jito.wtf");
+  return (client as any).sendBundle(opts.transactions, opts.tipLamports);
+}
+
+// FIXED — a nonzero tip (100,000 lamports) so the block engine can prioritize
+// the bundle. In production, scale the tip with observed competition.
+export async function submitArb(transactions: any[]) {
+  return sendBundle({ transactions, tipLamports: new BN(100_000) });
+}

package/dist/packs/jito-bundle-zero-tip/fixtures/jito-bundle-zero-tip/vulnerable/bundle.ts

@@ -0,0 +1,16 @@
+import { searcherClient } from "jito-ts/dist/sdk/block-engine/searcher.js";
+import BN from "bn.js";
+
+// A thin project wrapper around the Jito searcher client, as most teams write.
+async function sendBundle(opts: { transactions: any[]; tipLamports: BN }) {
+  const client = searcherClient("https://mainnet.block-engine.jito.wtf");
+  // ... build bundle with the tip, then client.sendBundle(...)
+  return (client as any).sendBundle(opts.transactions, opts.tipLamports);
+}
+
+// VULNERABLE — tipLamports: new BN(0). The bundle has no tip, so the Jito block
+// engine deprioritizes it and it never lands under competition. sendBundle
+// still returns a bundle id, so the caller assumes the transactions submitted.
+export async function submitArb(transactions: any[]) {
+  return sendBundle({ transactions, tipLamports: new BN(0) });
+}

package/dist/packs/jito-bundle-zero-tip/rules/jito-bundle-zero-tip.yaml

@@ -0,0 +1,54 @@
+# Pure-data rule. Binds to the vetted `object-arg-property-forbidden-literal`
+# checker (BN(0)-aware as of brainblast v0.7.6).
+#
+# Jito bundles are ordered by their tip. A bundle that tips 0 is deprioritized
+# by the block engine and, under any competition, simply never lands — yet the
+# send call returns a bundle id and the code proceeds as if it submitted.
+# This rule targets the common wrapper signature `sendBundle({ ..., tipLamports })`
+# (and `new BN(0)`). The positional `Bundle.addTipTx(payer, lamports, ...)` form
+# is a complementary manual check — see the pack README.
+#
+# Scope note: this fires only in files that import a Jito SDK (detect.modules),
+# so a zero-amount transfer elsewhere won't trip it.
+id: jito-bundle-zero-tip
+severity: high
+title: Jito bundle sent with a tip of 0 — bundle is deprioritized and will not land
+component:
+  name: Jito (block engine / bundles)
+  type: Blockchain
+  version: unversioned
+  sourceUrl: https://docs.jito.wtf/lowlatencytxnsend/
+detect:
+  modules:
+    - "jito-ts"
+    - "jito-js-rpc"
+    - "@jito-foundation/sdk"
+  nameRegex: bundle|jito|send|submit|tip|mev
+  triggerCalls:
+    - sendBundle
+    - sendJitoBundle
+check:
+  kind: object-arg-property-forbidden-literal
+  params:
+    call: sendBundle
+    argIndex: 0
+    propName: tipLamports
+    forbiddenValue: 0
+    passDetail: >-
+      sendBundle is called with a nonzero tipLamports — the bundle has a tip the
+      block engine can prioritize.
+    failDetail: >-
+      sendBundle is called with tipLamports of 0 (or new BN(0)). A Jito bundle
+      with no tip is deprioritized by the block engine and, under any
+      competition, never lands — but the call still returns a bundle id, so the
+      code proceeds as if the transactions submitted. Set a nonzero tip (and
+      ideally scale it with priority/competition).
+    absentCallDetail: >-
+      Handler is in Jito scope but does not call sendBundle; the zero-tip rule
+      does not apply here.
+    absentArgDetail: >-
+      sendBundle's options object does not set tipLamports as an inline literal;
+      the tip cannot be confirmed statically. Verify it resolves to a nonzero
+      value.
+test:
+  kind: none

package/dist/packs/jupiter-quote-zero-slippage/brainblast-pack.yaml

@@ -0,0 +1,5 @@
+id: jupiter-quote-zero-slippage
+name: Jupiter zero-slippage quote
+version: 0.1.0
+author: DSB-117
+description: "Flags Jupiter aggregator quote/swap calls that hardcode slippageBps: 0, disabling sandwich/MEV protection."

package/dist/packs/jupiter-quote-zero-slippage/fixtures/jupiter-quote-zero-slippage/fixed/arb.ts

@@ -0,0 +1,17 @@
+import { createJupiterApiClient } from "@jup-ag/api";
+
+const jupiterQuoteApi = createJupiterApiClient();
+
+const wSolMint = "So11111111111111111111111111111111111111112";
+const usdcMint = "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v";
+
+export async function getArbQuote(amountInJSBI: number) {
+  return jupiterQuoteApi.quoteGet({
+    inputMint: wSolMint,
+    outputMint: usdcMint,
+    amount: amountInJSBI,
+    onlyDirectRoutes: false,
+    slippageBps: 50,
+    maxAccounts: 20,
+  });
+}

package/dist/packs/jupiter-quote-zero-slippage/fixtures/jupiter-quote-zero-slippage/vulnerable/arb.ts

@@ -0,0 +1,17 @@
+import { createJupiterApiClient } from "@jup-ag/api";
+
+const jupiterQuoteApi = createJupiterApiClient();
+
+const wSolMint = "So11111111111111111111111111111111111111112";
+const usdcMint = "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v";
+
+export async function getArbQuote(amountInJSBI: number) {
+  return jupiterQuoteApi.quoteGet({
+    inputMint: wSolMint,
+    outputMint: usdcMint,
+    amount: amountInJSBI,
+    onlyDirectRoutes: false,
+    slippageBps: 0,
+    maxAccounts: 20,
+  });
+}

package/dist/packs/jupiter-quote-zero-slippage/rules/jupiter-quote-zero-slippage.yaml

@@ -0,0 +1,51 @@
+# Pure-data rule (facts). Binds to the vetted `object-arg-property-forbidden-literal`
+# checker template.
+#
+# Real-world instances of this exact pattern:
+#   - WSOL12/Solana-Arbitrage-Bot (510 stars, 208 forks), src/index.ts —
+#     `quoteUrl` fetch params include `slippageBps: 0`.
+#   - Forked verbatim into ChainBuff/sol-arb-bot, src/index.ts (same lines).
+#   - ARBProtocol/solana-jupiter-bot, src/bot/setup.js — same field on the
+#     Jupiter quote call.
+id: jupiter-quote-zero-slippage
+severity: high
+title: Jupiter quote/swap call hardcodes slippageBps to 0
+component:
+  name: Jupiter Aggregator API
+  type: Blockchain
+  version: unversioned
+  sourceUrl: https://station.jup.ag/docs/apis/swap-api
+detect:
+  modules: ["@jup-ag/api"]
+  # Keep broad enough to catch arb/swap bots that wrap the Jupiter quote
+  # call in their own helper (getQuote, fetchQuote, getArbQuote, swap, ...).
+  nameRegex: "quote|swap|arb"
+  triggerCalls: [quoteGet]
+check:
+  kind: object-arg-property-forbidden-literal
+  params:
+    call: quoteGet
+    argIndex: 0
+    propName: slippageBps
+    forbiddenValue: 0
+    passDetail: >-
+      quoteGet's slippageBps is a nonzero literal — the swap has explicit
+      slippage protection.
+    failDetail: >-
+      quoteGet is called with slippageBps: 0, which disables slippage
+      protection entirely. Any price movement between the quote and the
+      on-chain swap (including a sandwich attack) executes the trade at
+      whatever price results, with no minimum-output guarantee. Set
+      slippageBps to a nonzero value (e.g. 50 = 0.5%) or use
+      `dynamicSlippage` so the swap reverts if the price moves too far.
+    absentCallDetail: >-
+      Handler is in the Jupiter-quote scope but does not call quoteGet; the
+      zero-slippage rule does not apply here.
+    absentArgDetail: >-
+      quoteGet's options object does not set slippageBps as an inline
+      literal — cannot determine statically whether slippage protection is
+      disabled. If slippageBps is omitted entirely, the Jupiter API defaults
+      to 50 bps (0.5%), which is safe; if it's a non-literal expression,
+      verify the resolved value is nonzero.
+test:
+  kind: none

package/dist/packs/metaplex-nft-royalty-zero/README.md

@@ -0,0 +1,39 @@
+# metaplex-nft-royalty-zero
+
+**Severity:** HIGH
+
+## What's the trap?
+
+When minting an NFT with `@metaplex-foundation/js`, the `sellerFeeBasisPoints` field in `create()` sets the on-chain royalty percentage for the NFT's entire lifetime. A value of `0` means:
+
+- Creators earn **zero** royalties on every secondary sale
+- This is **immutable** — Metaplex token-metadata cannot be changed after mint without burning the NFT and reminting it
+
+AI code generators frequently use `0` as a "fill in later" placeholder, and launch teams sometimes leave it in to appear collection-friendly. Either way, the economic harm is permanent.
+
+## Why it's silent
+
+The `create()` call succeeds with `sellerFeeBasisPoints: 0` — there is no warning, no validation error, no on-chain check. The NFT mints normally and is immediately tradeable. The royalty loss only becomes apparent when secondary sales generate no creator income.
+
+## The fix
+
+```typescript
+// BEFORE (vulnerable — zero royalties, permanent)
+return metaplex.nfts().create({
+  uri,
+  name: "My NFT",
+  sellerFeeBasisPoints: 0,   // ← trap
+});
+
+// AFTER (fixed — 5% royalties)
+return metaplex.nfts().create({
+  uri,
+  name: "My NFT",
+  sellerFeeBasisPoints: 500, // 500 basis points = 5%
+});
+```
+
+## References
+
+- [Metaplex Token Metadata — Mint docs](https://developers.metaplex.com/token-metadata/mint)
+- `CreateNftInput.sellerFeeBasisPoints` — required field, immutable after mint

package/dist/packs/metaplex-nft-royalty-zero/brainblast-pack.yaml

@@ -0,0 +1,5 @@
+id: metaplex-nft-royalty-zero
+name: Metaplex NFT minted with zero royalties
+version: 0.1.0
+author: DSB-117
+description: "Detects metaplex.nfts().create() called with sellerFeeBasisPoints: 0 — royalties are immutably burned to zero at mint time"

package/dist/packs/metaplex-nft-royalty-zero/fixtures/metaplex-nft-royalty-zero/fixed/mint.ts

@@ -0,0 +1,11 @@
+import { Metaplex } from "@metaplex-foundation/js";
+
+export async function mintNft(metaplex: Metaplex, uri: string) {
+  // FIXED: 5% royalty on secondary sales
+  return metaplex.nfts().create({
+    uri,
+    name: "My NFT",
+    sellerFeeBasisPoints: 500,
+    symbol: "MNFT",
+  });
+}

package/dist/packs/metaplex-nft-royalty-zero/fixtures/metaplex-nft-royalty-zero/vulnerable/mint.ts

@@ -0,0 +1,11 @@
+import { Metaplex } from "@metaplex-foundation/js";
+
+export async function mintNft(metaplex: Metaplex, uri: string) {
+  // VULNERABLE: royalties are permanently set to zero — cannot be changed after mint
+  return metaplex.nfts().create({
+    uri,
+    name: "My NFT",
+    sellerFeeBasisPoints: 0,
+    symbol: "MNFT",
+  });
+}

package/dist/packs/metaplex-nft-royalty-zero/rules/metaplex-nft-royalty-zero.yaml

@@ -0,0 +1,39 @@
+# Auto-synthesized from a research Finding (proof-as-classifier loop).
+# Pure data — every kind below resolves to a HUMAN-VETTED template in core.
+id: metaplex-nft-royalty-zero
+severity: high
+title: "NFT minted with sellerFeeBasisPoints: 0 — creators receive zero
+  royalties on secondary sales"
+component:
+  name: "@metaplex-foundation/js"
+  type: Blockchain
+  version: ">=0.18.0"
+  sourceUrl: https://developers.metaplex.com/token-metadata/mint
+detect:
+  modules:
+    - "@metaplex-foundation/js"
+  nameRegex: mint|create|nft|deploy
+  triggerCalls:
+    - create
+check:
+  kind: object-arg-property-forbidden-literal
+  params:
+    call: create
+    argIndex: 0
+    propName: sellerFeeBasisPoints
+    forbiddenValue: 0
+    passDetail: create() sets sellerFeeBasisPoints to a nonzero literal — creators
+      will receive royalties on secondary sales.
+    failDetail: "create() is called with sellerFeeBasisPoints: 0, which bakes zero
+      royalties into the NFT's on-chain metadata. Secondary marketplaces that
+      honour on-chain royalties will pay creators nothing. Metaplex
+      token-metadata is immutable after mint — this cannot be corrected without
+      burning and reminting. Set sellerFeeBasisPoints to the intended basis
+      points (e.g. 500 = 5%)."
+    absentCallDetail: Handler is in the NFT-mint scope but does not call create();
+      this rule does not apply here.
+    absentArgDetail: create() does not include a sellerFeeBasisPoints literal in its
+      options object; the royalty rate cannot be confirmed statically. Verify
+      the resolved value is the intended nonzero royalty.
+test:
+  kind: none

package/dist/packs/meteora-dlmm-zero-min-out/README.md

@@ -0,0 +1,32 @@
+# meteora-dlmm-zero-min-out
+
+**Severity:** HIGH
+
+## What's the trap?
+
+Meteora DLMM's `swap()` takes a `minOutAmount` — the minimum number of output tokens the swap must return, or it reverts. Passing `new BN(0)` (or `0`) removes that floor entirely.
+
+With no floor, any price movement between when you quoted and when the swap lands on-chain — including a deliberate **sandwich attack** — fills the swap at whatever price results. There is no protection.
+
+AI-written swap bots reach for `minOutAmount: new BN(0)` to "just make the swap go through," not realizing they've disabled all slippage protection.
+
+## Why it's silent
+
+`swap()` with `minOutAmount: new BN(0)` builds and submits successfully. The trade executes. The loss only shows up as consistently worse-than-quoted fills — value quietly extracted by MEV.
+
+## The fix
+
+```typescript
+// BEFORE (vulnerable — no floor)
+return dlmmPool.swap({ /* ... */, minOutAmount: new BN(0) });
+
+// AFTER (fixed — floor from the quote + slippage tolerance)
+const quote = dlmmPool.swapQuote(inAmount, swapForY, new BN(50), binArrays); // 0.5%
+return dlmmPool.swap({ /* ... */, minOutAmount: quote.minOutAmount });
+```
+
+> This rule is `BN(0)`-aware (brainblast v0.7.6): it flags `minOutAmount: 0` **and** the idiomatic `minOutAmount: new BN(0)`.
+
+## References
+
+- [Meteora DLMM overview](https://docs.meteora.ag/product-overview/meteora-liquidity-pools/dlmm-overview)

package/dist/packs/meteora-dlmm-zero-min-out/brainblast-pack.yaml

@@ -0,0 +1,5 @@
+id: meteora-dlmm-zero-min-out
+name: Meteora DLMM zero minimum-out
+version: 0.1.0
+author: DSB-117
+description: "Flags Meteora DLMM swap() calls with minOutAmount of 0 (including new BN(0)) — no minimum-output floor, so a sandwich attack executes the swap at any price."

package/dist/packs/meteora-dlmm-zero-min-out/fixtures/meteora-dlmm-zero-min-out/fixed/swap.ts

@@ -0,0 +1,19 @@
+import DLMM from "@meteora-ag/dlmm";
+import BN from "bn.js";
+
+// FIXED — minOutAmount is derived from the on-chain quote and a 0.5% slippage
+// tolerance, so the swap reverts if it would return less than expected.
+export async function swapExactIn(dlmmPool: DLMM, user: any, inAmount: BN) {
+  const swapForY = true;
+  const binArrays = await dlmmPool.getBinArrayForSwap(swapForY);
+  const quote = dlmmPool.swapQuote(inAmount, swapForY, new BN(50), binArrays); // 50 bps = 0.5%
+  return dlmmPool.swap({
+    inToken: (dlmmPool as any).tokenX.publicKey,
+    outToken: (dlmmPool as any).tokenY.publicKey,
+    inAmount,
+    minOutAmount: quote.minOutAmount,
+    lbPair: (dlmmPool as any).pubkey,
+    user,
+    binArraysPubkey: binArrays.map((b: any) => b.publicKey),
+  });
+}

package/dist/packs/meteora-dlmm-zero-min-out/fixtures/meteora-dlmm-zero-min-out/vulnerable/swap.ts

@@ -0,0 +1,19 @@
+import DLMM from "@meteora-ag/dlmm";
+import BN from "bn.js";
+
+// VULNERABLE — minOutAmount: new BN(0) removes the slippage floor. The swap
+// will fill at any price; a sandwich bot can move the pool and extract value
+// with no revert protection.
+export async function swapExactIn(dlmmPool: DLMM, user: any, inAmount: BN) {
+  const swapForY = true;
+  const binArrays = await dlmmPool.getBinArrayForSwap(swapForY);
+  return dlmmPool.swap({
+    inToken: (dlmmPool as any).tokenX.publicKey,
+    outToken: (dlmmPool as any).tokenY.publicKey,
+    inAmount,
+    minOutAmount: new BN(0),
+    lbPair: (dlmmPool as any).pubkey,
+    user,
+    binArraysPubkey: binArrays.map((b: any) => b.publicKey),
+  });
+}

package/dist/packs/meteora-dlmm-zero-min-out/rules/meteora-dlmm-zero-min-out.yaml

@@ -0,0 +1,47 @@
+# Pure-data rule. Binds to the vetted `object-arg-property-forbidden-literal`
+# checker (BN(0)-aware as of brainblast v0.7.6).
+#
+# Meteora DLMM's swap() takes `minOutAmount` — the floor the swap must return or
+# it reverts. Passing `new BN(0)` (or 0) removes that floor entirely: any price
+# movement between quote and execution, including a sandwich, fills the swap at
+# whatever price results. AI-written swap bots reach for minOutAmount: new BN(0)
+# to "just make the swap go through," silently disabling slippage protection.
+id: meteora-dlmm-zero-min-out
+severity: high
+title: Meteora DLMM swap called with minOutAmount of 0 — no slippage floor
+component:
+  name: "@meteora-ag/dlmm"
+  type: Blockchain
+  version: unversioned
+  sourceUrl: https://docs.meteora.ag/product-overview/meteora-liquidity-pools/dlmm-overview
+detect:
+  modules:
+    - "@meteora-ag/dlmm"
+  nameRegex: swap|trade|exchange|buy|sell|arb
+  triggerCalls:
+    - swap
+check:
+  kind: object-arg-property-forbidden-literal
+  params:
+    call: swap
+    argIndex: 0
+    propName: minOutAmount
+    forbiddenValue: 0
+    passDetail: >-
+      swap() is called with a nonzero minOutAmount — the swap reverts if it
+      would return less, enforcing a minimum-output floor.
+    failDetail: >-
+      swap() is called with minOutAmount of 0 (or new BN(0)), which removes the
+      minimum-output floor. Any price movement between quote and on-chain
+      execution — including a sandwich attack — fills the swap at whatever price
+      results, with no revert protection. Compute minOutAmount from the quote
+      and a slippage tolerance (e.g. quote.minOutAmount or quote * (1 - 0.005)).
+    absentCallDetail: >-
+      Handler is in the Meteora DLMM swap scope but does not call swap(); this
+      rule does not apply here.
+    absentArgDetail: >-
+      swap()'s options object does not set minOutAmount as an inline literal;
+      the minimum-output floor cannot be confirmed statically. Verify it is
+      derived from the quote and a nonzero slippage tolerance.
+test:
+  kind: none

package/dist/packs/pyth-price-unchecked-staleness/README.md

@@ -0,0 +1,34 @@
+# pyth-price-unchecked-staleness
+
+**Severity:** HIGH
+
+## What's the trap?
+
+Pyth `PriceFeed` objects expose two ways to read a price:
+
+- **`getPriceUnchecked()`** — returns the most recent price **regardless of how old it is**.
+- **`getPriceNoOlderThan(maxAgeSeconds)`** — returns the price only if it's fresh, otherwise `undefined`.
+
+Using `getPriceUnchecked()` means that if the feed stops updating — a publisher outage, network congestion, a halted market — your protocol keeps pricing swaps, loans, and liquidations against a **stale price** with no guard.
+
+## Why it's silent
+
+`getPriceUnchecked()` always succeeds and always returns a number. Nothing throws. The bug only surfaces when the feed goes stale at exactly the wrong moment — and by then someone has been liquidated at a wrong price, or drained an over-valued position.
+
+## The fix
+
+```typescript
+// BEFORE (vulnerable — ignores staleness)
+const price = feed.getPriceUnchecked();
+
+// AFTER (fixed — refuse stale prices)
+const price = feed.getPriceNoOlderThan(60); // 60s max age
+if (!price) throw new Error("Pyth price is stale — refusing to trade");
+```
+
+Pyth's own best-practices doc says to **never** use `getPriceUnchecked()` in production.
+
+## References
+
+- [Pyth — price availability best practices](https://docs.pyth.network/price-feeds/best-practices#price-availability)
+- Companion: `brainblast oracle <account>` checks the same staleness question live, on-chain.

package/dist/packs/pyth-price-unchecked-staleness/brainblast-pack.yaml

@@ -0,0 +1,5 @@
+id: pyth-price-unchecked-staleness
+name: Pyth unchecked price staleness
+version: 0.1.0
+author: DSB-117
+description: "Flags Pyth price reads via getPriceUnchecked() (ignores staleness) instead of getPriceNoOlderThan(maxAge), which can return an arbitrarily old price."

package/dist/packs/pyth-price-unchecked-staleness/fixtures/pyth-price-unchecked-staleness/fixed/price.ts

@@ -0,0 +1,14 @@
+import { PriceServiceConnection } from "@pythnetwork/price-service-client";
+
+const connection = new PriceServiceConnection("https://hermes.pyth.network");
+const SOL_USD = "0xef0d8b6fda2ceba41da15d4095d1da392a0d2f8ed0c6c7bc0f4cfac8c280b56d";
+
+// FIXED — getPriceNoOlderThan(60) returns undefined when the feed is more than
+// 60 seconds old, so we refuse to price against a stale oracle.
+export async function getSolPrice() {
+  const feeds = await connection.getLatestPriceFeeds([SOL_USD]);
+  const feed = feeds![0];
+  const price = feed.getPriceNoOlderThan(60);
+  if (!price) throw new Error("Pyth SOL/USD price is stale (>60s) — refusing to trade");
+  return Number(price.price) * 10 ** price.expo;
+}

package/dist/packs/pyth-price-unchecked-staleness/fixtures/pyth-price-unchecked-staleness/vulnerable/price.ts

@@ -0,0 +1,14 @@
+import { PriceServiceConnection } from "@pythnetwork/price-service-client";
+
+const connection = new PriceServiceConnection("https://hermes.pyth.network");
+const SOL_USD = "0xef0d8b6fda2ceba41da15d4095d1da392a0d2f8ed0c6c7bc0f4cfac8c280b56d";
+
+// VULNERABLE — getPriceUnchecked() ignores staleness. If the SOL/USD feed
+// stops updating, this returns the last (possibly very old) price and the
+// caller trades against it with no guard.
+export async function getSolPrice() {
+  const feeds = await connection.getLatestPriceFeeds([SOL_USD]);
+  const feed = feeds![0];
+  const price = feed.getPriceUnchecked();
+  return Number(price.price) * 10 ** price.expo;
+}

package/dist/packs/pyth-price-unchecked-staleness/rules/pyth-price-unchecked-staleness.yaml

@@ -0,0 +1,47 @@
+# Pure-data rule. Binds to the vetted `forbidden-call-replacement` checker.
+#
+# Pyth's own docs are explicit: NEVER use getPriceUnchecked() in production —
+# it returns the last price regardless of how old it is. A feed can stop
+# updating (publisher outage, network congestion) and getPriceUnchecked() will
+# happily hand you a stale price, which a protocol then prices liquidations /
+# swaps against. Use getPriceNoOlderThan(maxAge), which returns undefined when
+# the price is older than maxAge so the caller can refuse to trade.
+id: pyth-price-unchecked-staleness
+severity: high
+title: Pyth price read with getPriceUnchecked() instead of getPriceNoOlderThan()
+component:
+  name: Pyth Network price feeds
+  type: Blockchain
+  version: unversioned
+  sourceUrl: https://docs.pyth.network/price-feeds/best-practices#price-availability
+detect:
+  modules:
+    - "@pythnetwork/price-service-client"
+    - "@pythnetwork/pyth-solana-receiver"
+    - "@pythnetwork/hermes-client"
+  nameRegex: price|oracle|quote|value|fetch|get
+  triggerCalls:
+    - getPriceUnchecked
+    - getPriceNoOlderThan
+check:
+  kind: forbidden-call-replacement
+  params:
+    forbiddenCalls:
+      - getPriceUnchecked
+    saferCalls:
+      - getPriceNoOlderThan
+    passDetail: >-
+      Handler reads the Pyth price via getPriceNoOlderThan(maxAge), which
+      returns no price when the feed is older than maxAge — the caller can
+      refuse to trade on a stale oracle.
+    failDetail: >-
+      Handler calls getPriceUnchecked(), which returns the most recent Pyth
+      price REGARDLESS of how old it is. If the feed stops updating (publisher
+      outage, congestion), the protocol prices swaps/liquidations against a
+      stale value with no guard. Use getPriceNoOlderThan(maxAge) (e.g. 60s) and
+      handle the undefined/stale case explicitly.
+    absentDetail: >-
+      Handler is in Pyth scope but calls neither getPriceUnchecked nor
+      getPriceNoOlderThan; the staleness rule does not apply here.
+test:
+  kind: none