Incidents (#242): `pending_squads_upgrade` — Solana program-upgrade early warning

[szhygulin]

Tracking the `pending_squads_upgrade` signal scoped out of #246's parent investigation. Part of the #242 v2 follow-up.

Signal

Any pending Squads multisig transaction that targets `BPFLoaderUpgradeable::Upgrade` against a program the user is exposed to. Fires before the upgrade lands — earliest possible warning, complementing the existing `recent_program_upgrade` signal which fires only post-execution.

Data path

• Squads V4 program ID: typically `SMPLecH534NA9acpos4G6x7uf3LWbCAwZQE9e8ZekMu` (claim — needs `rnd` verification before code; per memory `feedback_verify_external_facts` Solana program ID drift is a real footgun).
• For each program in the user's exposure set with `upgradeAuthority` matching a Squads PDA: fetch all pending transactions on that multisig, decode each, flag any that target `BPFLoaderUpgradeable`.
• Squads SDK exposes typed account decoding for transaction state (`Pending` / `Approved` / `Executed`).

Decisions

Decision	Options	Recommendation
Squads version coverage	V3 only; V4 only; both	V4 only initially — V3 is legacy; most active programs are V4 now. Document V3 as out of scope. Verify with `rnd` skill before committing — Squads program ID drift across versions is a known footgun.
Dependency	`@sqds/multisig` SDK; or hand-roll Anchor IDL decoding	SDK — saves ~300 LoC of decoder code, and Squads ships the IDL with each release.
Performance	Scan all pending tx on every call; cache per-multisig per-block	Cache per-(multisig, slot). Pending tx state changes are slot-bounded events.
Multisig discovery	Per-program `upgradeAuthority` lookup; also scan SetUpgradeAuthority history	Just upgradeAuthority. Historical scanning is a separate forensic question.

Scope estimate

~400-600 LoC + tests. New file `src/modules/incidents/squads-pending.ts`. SDK adds ~5MB transitive. New signal emitter in `chain-solana.ts`.

Risk

Medium-high. Squads program-ID and IDL drift is real (per memory `feedback_verify_external_facts` — PR #33 clear-signing labels were backwards because external SDK assumptions weren't verified). Must empirically validate Squads V4 program ID, account layout, and tx-state enum values before shipping.

Cross-references

• Parent: [agent-request] Add Solana smart-contract incident layer: program-upgrade detection, Token-2022 freeze events, oracle staleness, curated exploit feed #242 (Solana program-layer incidents)
• Sibling: Incidents (#242): pending_squads_upgrade — Solana program-upgrade early warning #251 (`token_extension_change`) — both Solana program-layer follow-ups; per the deferred-work investigation, these two could plausibly bundle into one PR since both need `rnd`-verified external account layouts
• Predecessor: `b9b17ac` shipped v1 of [agent-request] Add Solana smart-contract incident layer: program-upgrade detection, Token-2022 freeze events, oracle staleness, curated exploit feed #242 (recent_program_upgrade, known_exploit, token_freeze_event, oracle_staleness)

---

Filed via gh CLI by an AI agent (Claude Code) after the deferred-work investigation in #246's PR thread.

[szhygulin]

Correction to the body's cross-reference: the sibling token_extension_change issue is #252, not #251 (this issue). Filed sequentially right after this one.

[szhygulin]

Empirical correction — verified Squads V4 program ID

The body of this issue cited the program ID as SMPLecH534NA9acpos4G6x7uf3LWbCAwZQE9e8ZekMu (claim — needs rnd verification). The rnd scope-probe done before implementation verified that this is wrong.

Verified: Squads V4 program ID = SQDS4ep65T869zMMBKyuUq6aD6EgTu8psMjkvj52pCf

Source: @sqds/multisig SDK v2.1.4, file lib/generated/index.d.ts:

export declare const PROGRAM_ADDRESS = "SQDS4ep65T869zMMBKyuUq6aD6EgTu8psMjkvj52pCf";

This is exactly the PR #33 backwards-labels precedent the issue body cited — claims about external systems must be source-cited, never inferred. The wrong ID would have produced silent available:false (no Squads-governed programs found) rather than alerting on real upgrades.

Other empirically-verified facts from the same probe

• SDK compatibility check: @sqds/multisig v2.1.4 depends on @solana/web3.js: ^1.70.3 — compatible with host's ^1.98.4. No parallel-core-library red flag.
• ProposalStatus enum variants (from lib/generated/types/ProposalStatus.d.ts): Draft | Active | Rejected | Approved | Executing | Executed | Cancelled. "Pending" filter must accept BOTH Active and Approved (Approved-but-not-yet-Executing is still pre-execution).
• Account decode path: Proposal.gpaBuilder() and VaultTransaction.gpaBuilder() (from lib/generated/accounts/Proposal.d.ts and VaultTransaction.d.ts) provide getProgramAccounts filter builders to enumerate all proposals/txs for a given multisig efficiently.
• Compiled instruction shape (from lib/generated/types/MultisigCompiledInstruction.d.ts): { programIdIndex: number, accountIndexes: Uint8Array, data: Uint8Array } — programIdIndex resolves into the message's accountKeys[].
• BPFLoaderUpgradeable program ID = BPFLoaderUpgradeab1e11111111111111111111111 (cross-checked via @kamino-finance/klend-sdk's utils/seeds.ts).

Conservative-default decision (rule 3 of the rnd skill)

The implementation will flag any pending vault tx whose programIdIndex resolves to BPFLoaderUpgradeab1e1..., not narrowly on the Upgrade discriminator (3). Wrong direction is "flag a SetAuthority too" — operationally safe, still alerts the user. Reverse direction (narrow filter) silently misses if the discriminator byte we believe is wrong.

v1 scope correction

The implementation will ship KNOWN_SQUADS_GOVERNED_PROGRAMS empty. SDK does not expose a programId → multisigPda map; per-protocol governance verification (does Marinade actually use Squads V4? Jito? Kamino? MarginFi? Drift?) is manual research and was not in this probe's scope. Empty + a clear note: "vendor list is empty pending per-protocol governance verification" in the signal output is honest; PR curation policy will mirror KNOWN_SOLANA_INCIDENTS (every entry needs a source).

This will be cited in the implementation PR.

[szhygulin]

Resolved by PR #260 (commit a9745d4). pending_squads_upgrade signal is live in src/modules/incidents/chain-solana.ts and the squads-pending.ts helper module; surfaces under get_market_incident_status({ protocol: 'solana-protocols' }).