Monitoring · November 18, 2026 · 6 min read

Watching for program upgrades as they happen

When a program you depend on is redeployed, its upgrade is an ordinary instruction to the upgradeable loader. Here is how to recognise it, and its authority changes, in raw transactions.

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:

TagInstructionWhat it means for a watcherAccount to read
0InitializeBufferSomeone is preparing a buffer, often the first step of a deploy or upgradeBuffer, authority
1WriteProgram bytes are being written into a bufferBuffer
2DeployWithMaxDataLenA new program is deployedProgram (check its position in the interface account list)
3UpgradeAn existing program's code is replacedProgram (account 1)
4SetAuthorityThe upgrade authority changes, or is removed so the program becomes immutableProgramData (account 0)
5CloseA buffer or a program's data account is closedAccount 0, and the Program (account 3) when closing a program
6ExtendProgramThe program's data account grows to fit a larger buildProgramData (account 0), Program (account 1)
7SetAuthorityCheckedSame as SetAuthority, with the new authority also signingProgramData (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#

  1. Keep a watchlist of program ids you decode or depend on, and derive each one's ProgramData address.
  2. In the decoder, keep any transaction that has a top-level instruction to the upgradeable loader. This check needs no lookup table state.
  3. Resolve the instruction's accounts, read the 4-byte tag and match the relevant account against the watchlist.
  4. On a match, write an event with the tag, the program, the signature, the slot and the signer, marked provisional.
  5. Send the alert, and say plainly that it is unconfirmed.
  6. 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.

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#

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.

Read nextEvent schemas that last: modelling decoded Solana activity