Solana program upgrade detection comes down to one instruction: Upgrade, sent to the upgradeable loader, with data starting with the 4-byte tag 3 and the replaced program as its second account. Watch for it, plus SetAuthority, SetAuthorityChecked and Close, on the programs you depend on, and confirm the transaction landed before acting.
Upgradeable loader instructions to watch#
Most deployed programs belong to the upgradeable loader, BPFLoaderUpgradeab1e11111111111111111111111. Its instructions are encoded with a 4-byte little-endian variant index, followed by any arguments. The enum in the loader's interface defines eight variants:
| Tag | Instruction | What it means for a watcher | Account to read |
|---|---|---|---|
| 0 | InitializeBuffer | Someone is preparing a buffer, often the first step of a deploy or upgrade | Buffer, authority |
| 1 | Write | Program bytes are being written into a buffer | Buffer |
| 2 | DeployWithMaxDataLen | A new program is deployed | Program (check its position in the interface account list) |
| 3 | Upgrade | An existing program's code is replaced | Program (account 1) |
| 4 | SetAuthority | The upgrade authority changes, or is removed so the program becomes immutable | ProgramData (account 0) |
| 5 | Close | A buffer or a program's data account is closed | Account 0, and the Program (account 3) when closing a program |
| 6 | ExtendProgram | The program's data account grows to fit a larger build | ProgramData (account 0), Program (account 1) |
| 7 | SetAuthorityChecked | Same as SetAuthority, with the new authority also signing | ProgramData (account 0) |
For upgrade detection, tags 3, 4, 5 and 7 are the ones that need an alert. Tags 0, 1 and 6 are useful early signals: a buffer being written and a program being extended often come shortly before an upgrade.
Finding the program an instruction touches#
The Upgrade instruction lists, in order, the ProgramData account, the Program account, the buffer holding the new code, a spill account that receives the buffer's lamports, the Rent and Clock sysvars, and the program's authority. The Program account at position 1 is the address of the program being upgraded, so you can compare it directly with your watchlist.
Authority changes and closes name the ProgramData account instead. A program's ProgramData address is derived from its program id under the loader, so compute it once for each program on your watchlist and match on both addresses.
Remember that account positions refer to the instruction's own account list, which holds indexes into the transaction's keys. Resolve those indexes first, including any keys loaded from lookup tables. The loader itself is always a static key, because a v0 message never loads a program id from a lookup table.
Authority changes and closes#
An upgrade changes code. An authority change decides who can change code next, and that is often the more important event for anyone who depends on a program.
- SetAuthority with no new authority makes the program immutable. That is usually good news for users, and worth recording as the end of the program's upgrade history.
- SetAuthority or SetAuthorityChecked to a new key hands control to someone else. Record the new authority and alert if it is not one you expected.
- Close on a ProgramData account removes the program. Every decoder that depends on it can stop expecting new instructions from that address.
Building the alert#
- Keep a watchlist of program ids you decode or depend on, and derive each one's ProgramData address.
- In the decoder, keep any transaction that has a top-level instruction to the upgradeable loader. This check needs no lookup table state.
- Resolve the instruction's accounts, read the 4-byte tag and match the relevant account against the watchlist.
- On a match, write an event with the tag, the program, the signature, the slot and the signer, marked provisional.
- Send the alert, and say plainly that it is unconfirmed.
- Feed the same event to your layout table, so a decoder whose program was just upgraded starts flagging unknown instructions instead of guessing. IDL drift explains that side.
Confirming before acting#
A transaction seen in shreds is a request, not a result. The upgrade can fail, for example if the buffer authority does not match, and the transaction still lands and pays its fee. Before you pause a bot or switch decoder layouts, check the transaction's status through RPC and, for upgrades, confirm that the ProgramData account changed. Confirming decoded transactions covers the reconciliation step.
Upgrades this method will miss#
Many teams upgrade through a multisig or governance program. In that case the transaction's top-level instruction is the multisig's execute call, and the loader's Upgrade happens as a cross-program call during execution. Raw transactions do not contain those inner calls, so a watcher that reads only top-level instructions sees the multisig, not the upgrade.
To cover them, add the multisig and governance programs your dependencies use to the watchlist, treat their execute instructions as candidate upgrades, and confirm through RPC or by checking whether the ProgramData account changed. Programs owned by loaders other than the upgradeable loader are outside this method as well.
Related reading#
The program IDs page lists the addresses this watcher needs, with their sources. Filtering by program ID shows the cheap first check from step 2. Alerts that fire on unconfirmed data need the same care as any other: wallet alerts without false alarms covers the patterns. To run the watcher on the raw stream, compare the plans.
Sources#
- solana-sdk loader-v3 interface: UpgradeableLoaderInstruction variants and account lists (checked 2026-11-18)
- solana-sdk sdk-ids (upgradeable loader program id) (checked 2026-11-18)
- Solana docs: programs and deployment (checked 2026-11-18)
- solana-transaction-status 4.4.1, TransactionStatusMeta (inner instructions come from execution) (checked 2026-11-18)
Raw shreds on your own server
Ultra Low Latency Shreds is $200 and Standard Shreds is $100. You pay in crypto, tell us which IPv4 address and UDP port should receive the stream, and we wire it up by hand.