From b584e2dda769e55c90b2cda199fe037f8a4d06ec Mon Sep 17 00:00:00 2001 From: amilz <85324096+amilz@users.noreply.github.com> Date: Thu, 29 Oct 2026 08:04:23 -0700 Subject: [PATCH 1/2] feat(js): add fetchProgramUpgradeAuthority --- clients/js/src/utils.ts | 107 +++++++++++++++ clients/js/test/_setup.ts | 12 +- .../test/fetchProgramUpgradeAuthority.test.ts | 122 ++++++++++++++++++ 3 files changed, 237 insertions(+), 4 deletions(-) create mode 100644 clients/js/test/fetchProgramUpgradeAuthority.test.ts diff --git a/clients/js/src/utils.ts b/clients/js/src/utils.ts index 443f73b..7e9a2bf 100644 --- a/clients/js/src/utils.ts +++ b/clients/js/src/utils.ts @@ -18,8 +18,10 @@ import { getU64Decoder, HasAddress, Instruction, + isOffCurveAddress, MessagePackerInstructionPlan, MicroLamports, + parseBase64RpcAccount, ReadonlyUint8Array, Rpc, SOLANA_ERROR__INSTRUCTION_PLANS__MAX_INSTRUCTIONS_PER_TRANSACTION_EXCEEDED, @@ -66,6 +68,9 @@ export const REALLOC_LIMIT = 10_240; export const LOADER_V3_PROGRAM_ADDRESS = 'BPFLoaderUpgradeab1e11111111111111111111111' as Address<'BPFLoaderUpgradeab1e11111111111111111111111'>; +export const LOADER_V2_PROGRAM_ADDRESS = + 'BPFLoader2111111111111111111111111111111111' as Address<'BPFLoader2111111111111111111111111111111111'>; + export type MetadataInput = { payer: TransactionSigner; authority: TransactionSigner; @@ -225,6 +230,108 @@ async function getProgramAuthorityForLoaderV3(rpc: Rpc, progr }; } +/** + * What kind of account holds a program's upgrade authority: + * + * - `none`: no authority; the program is immutable. + * - `keypair`: an on-curve address; a single private key can redeploy the + * program. + * - `pda`: an off-curve address, such as a multisig vault or another program. + */ +export type UpgradeAuthorityKind = 'none' | 'keypair' | 'pda'; + +export type ProgramUpgradeAuthority = + | { + authority: null; + authorityKind: 'none'; + loader: 'v2'; + program: Address; + } + | { + /** The address allowed to redeploy the program, or `null` once made immutable. */ + authority: Address | null; + authorityKind: UpgradeAuthorityKind; + /** Slot of the most recent deploy or upgrade. */ + lastDeployedSlot: bigint; + loader: 'v3'; + program: Address; + programData: Address; + }; + +/** Discriminator (4) + program data address (32). */ +const LOADER_V3_PROGRAM_HEADER_LENGTH = 36; + +/** Discriminator (4) + slot (8) + optional authority (1 + 32). */ +const LOADER_V3_PROGRAM_DATA_HEADER_LENGTH = 45; + +/** + * Reports who can replace the code of a program — the same data + * `solana program show` prints under `Authority` and `Last Deployed In Slot`. + * + * - Loader v2 programs are immutable by construction. + * - Loader v3 programs report the upgrade authority and deploy slot stored in + * their program data account. + * + * Unlike {@link getProgramAuthority}, which resolves the authority allowed to + * manage canonical metadata, this reports the upgrade authority only, so + * immutable programs have no authority. + * + * Only account headers are fetched, so the program ELF is never downloaded. + * Throws if the account is not an executable program owned by loader v2 or v3. + */ +export async function fetchProgramUpgradeAuthority( + rpc: Rpc, + program: Address | HasAddress, +): Promise { + const programAddress = toAddress(program); + const programAccount = await fetchEncodedAccountHeader(rpc, programAddress, LOADER_V3_PROGRAM_HEADER_LENGTH); + assertAccountExists(programAccount); + + if (!programAccount.executable) { + throw Error('Program account must be executable'); + } + + if (programAccount.programAddress === LOADER_V2_PROGRAM_ADDRESS) { + return { authority: null, authorityKind: 'none', loader: 'v2', program: programAddress }; + } + + if (programAccount.programAddress !== LOADER_V3_PROGRAM_ADDRESS) { + throw Error('Invalid loader program, expected loader v2 or v3'); + } + + const [programDecoder, programDataDecoder] = getLoaderV3Decoders(); + const programAccountData = programDecoder.decode(programAccount.data); + if (programAccountData.discriminator !== 2) { + throw Error('Invalid program discriminator'); + } + + const programData = programAccountData.programData; + const programDataAccount = await fetchEncodedAccountHeader(rpc, programData, LOADER_V3_PROGRAM_DATA_HEADER_LENGTH); + assertAccountExists(programDataAccount); + + const programDataAccountData = programDataDecoder.decode(programDataAccount.data); + if (programDataAccountData.discriminator !== 3) { + throw Error('Invalid program data discriminator'); + } + + const authority = unwrapOption(programDataAccountData.authority); + return { + authority, + authorityKind: authority === null ? 'none' : isOffCurveAddress(authority) ? 'pda' : 'keypair', + lastDeployedSlot: programDataAccountData.slot, + loader: 'v3', + program: programAddress, + programData, + }; +} + +async function fetchEncodedAccountHeader(rpc: Rpc, address: Address, length: number) { + const { value } = await rpc + .getAccountInfo(address, { dataSlice: { length, offset: 0 }, encoding: 'base64' }) + .send(); + return parseBase64RpcAccount(address, value); +} + function getLoaderV3Decoders() { return [ getStructDecoder([ diff --git a/clients/js/test/_setup.ts b/clients/js/test/_setup.ts index eced81c..4d638bb 100644 --- a/clients/js/test/_setup.ts +++ b/clients/js/test/_setup.ts @@ -12,9 +12,11 @@ import { getU32Encoder, getU64Encoder, getUtf8Encoder, + HasAddress, KeyPairSigner, lamports, Lamports, + none, sol, solToLamports, some, @@ -33,10 +35,11 @@ import { PROGRAM_METADATA_PROGRAM_ADDRESS, programMetadataProgram, } from '../src'; +import { toAddress } from '../src/internals'; export { REALLOC_LIMIT } from '../src'; -const PROGRAM_METADATA_BINARY_PATH = path.resolve( +export const PROGRAM_METADATA_BINARY_PATH = path.resolve( __dirname, '..', '..', @@ -102,7 +105,8 @@ const getLoaderV3ProgramDataAccountEncoder = () => */ export const createDeployedProgram = async ( client: TestClient, - authority: KeyPairSigner, + authority: Address | HasAddress | null, + slot: bigint = 0n, ): Promise<[Address, Address]> => { const program = await generateKeyPairSigner(); const [programData] = await getLoaderV3ProgramDataPda(program.address); @@ -113,8 +117,8 @@ export const createDeployedProgram = async ( }); const programDataAccountData = getLoaderV3ProgramDataAccountEncoder().encode({ discriminator: 3, - slot: 0n, - authority: some(authority.address), + slot, + authority: authority ? some(toAddress(authority)) : none(), }); const programSpace = BigInt(programAccountData.length); diff --git a/clients/js/test/fetchProgramUpgradeAuthority.test.ts b/clients/js/test/fetchProgramUpgradeAuthority.test.ts new file mode 100644 index 0000000..36bb017 --- /dev/null +++ b/clients/js/test/fetchProgramUpgradeAuthority.test.ts @@ -0,0 +1,122 @@ +import { readFileSync } from 'node:fs'; + +import { generateKeyPairSigner, getProgramDerivedAddress } from '@solana/kit'; +import { expect, it } from 'vitest'; + +import { fetchProgramUpgradeAuthority, LOADER_V2_PROGRAM_ADDRESS } from '../src'; +import { + createDeployedProgram, + createNativeProgram, + createTestClient, + generateKeyPairSignerWithSol, + PROGRAM_METADATA_BINARY_PATH, +} from './_setup'; + +it('reports a keypair upgrade authority and the last deployed slot', async () => { + // Given a loader-v3 program upgradeable by a keypair and deployed at slot 123,456. + const client = await createTestClient(); + const authority = await generateKeyPairSigner(); + const [program, programData] = await createDeployedProgram(client, authority, 123_456n); + + // When we fetch its upgrade authority. + const result = await fetchProgramUpgradeAuthority(client.rpc, program); + + // Then we expect the keypair authority and deploy slot to be returned. + expect(result).toStrictEqual({ + authority: authority.address, + authorityKind: 'keypair', + lastDeployedSlot: 123_456n, + loader: 'v3', + program, + programData, + }); +}); + +it('reports a PDA upgrade authority', async () => { + // Given a loader-v3 program upgradeable by a PDA, e.g. a multisig vault. + const client = await createTestClient(); + const [vault] = await getProgramDerivedAddress({ + programAddress: (await generateKeyPairSigner()).address, + seeds: ['vault'], + }); + const [program] = await createDeployedProgram(client, vault); + + // When we fetch its upgrade authority. + const result = await fetchProgramUpgradeAuthority(client.rpc, program); + + // Then we expect the authority to be flagged as a PDA. + expect(result).toMatchObject({ authority: vault, authorityKind: 'pda' }); +}); + +it('reports a loader-v3 program made immutable', async () => { + // Given a loader-v3 program whose upgrade authority was removed. + const client = await createTestClient(); + const [program, programData] = await createDeployedProgram(client, null, 42n); + + // When we fetch its upgrade authority. + const result = await fetchProgramUpgradeAuthority(client.rpc, program); + + // Then we expect no authority to be returned. + expect(result).toStrictEqual({ + authority: null, + authorityKind: 'none', + lastDeployedSlot: 42n, + loader: 'v3', + program, + programData, + }); +}); + +it('reports a loader-v2 program as immutable', async () => { + // Given a program deployed with loader v2. + const client = await createTestClient(); + const program = (await generateKeyPairSigner()).address; + client.svm.addProgramWithLoader(program, readFileSync(PROGRAM_METADATA_BINARY_PATH), LOADER_V2_PROGRAM_ADDRESS); + + // When we fetch its upgrade authority. + const result = await fetchProgramUpgradeAuthority(client.rpc, program); + + // Then we expect it to be reported as immutable. + expect(result).toStrictEqual({ + authority: null, + authorityKind: 'none', + loader: 'v2', + program, + }); +}); + +it('fails for missing accounts', async () => { + // Given an address with no account. + const client = await createTestClient(); + const missing = (await generateKeyPairSigner()).address; + + // When we try to fetch its upgrade authority. + const promise = fetchProgramUpgradeAuthority(client.rpc, missing); + + // Then we expect an error to be thrown. + await expect(promise).rejects.toThrow(); +}); + +it('fails for non-executable accounts', async () => { + // Given a plain, non-executable wallet account. + const client = await createTestClient(); + const wallet = await generateKeyPairSignerWithSol(client); + + // When we try to fetch its upgrade authority. + const promise = fetchProgramUpgradeAuthority(client.rpc, wallet); + + // Then we expect an error to be thrown. + await expect(promise).rejects.toThrow('Program account must be executable'); +}); + +it('fails for programs not owned by loader v2 or v3', async () => { + // Given a native program. + const client = await createTestClient(); + const program = await createNativeProgram(client); + + // When we try to fetch its upgrade authority. + const promise = fetchProgramUpgradeAuthority(client.rpc, program); + + // Then we expect an error to be thrown. + await expect(promise).rejects.toThrow('Invalid loader program, expected loader v2 or v3'); +}); From 86e518cb550f60f2a551c4f9fa1d0b09f7617e67 Mon Sep 17 00:00:00 2001 From: amilz <85324096+amilz@users.noreply.github.com> Date: Thu, 29 Oct 2026 09:44:58 -0700 Subject: [PATCH 2/2] refactor(js): name loader v3 discriminators --- clients/js/src/utils.ts | 38 +++++++++++++++++++------------------- 1 file changed, 19 insertions(+), 19 deletions(-) diff --git a/clients/js/src/utils.ts b/clients/js/src/utils.ts index 7e9a2bf..6388e43 100644 --- a/clients/js/src/utils.ts +++ b/clients/js/src/utils.ts @@ -214,10 +214,10 @@ async function getProgramAuthorityForLoaderV3(rpc: Rpc, progr const programDataAccountData = programDataDecoder.decode(programDataAccount.data); // Ensure both accounts are valid. - if (programAccountData.discriminator !== 2) { + if (programAccountData.discriminator !== LOADER_V3_PROGRAM_DISCRIMINATOR) { throw Error('Invalid program discriminator'); } - if (programDataAccountData.discriminator !== 3) { + if (programDataAccountData.discriminator !== LOADER_V3_PROGRAM_DATA_DISCRIMINATOR) { throw Error('Invalid program data discriminator'); } if (programAccountData.programData !== programDataAccount.address) { @@ -258,12 +258,6 @@ export type ProgramUpgradeAuthority = programData: Address; }; -/** Discriminator (4) + program data address (32). */ -const LOADER_V3_PROGRAM_HEADER_LENGTH = 36; - -/** Discriminator (4) + slot (8) + optional authority (1 + 32). */ -const LOADER_V3_PROGRAM_DATA_HEADER_LENGTH = 45; - /** * Reports who can replace the code of a program — the same data * `solana program show` prints under `Authority` and `Last Deployed In Slot`. @@ -276,7 +270,8 @@ const LOADER_V3_PROGRAM_DATA_HEADER_LENGTH = 45; * manage canonical metadata, this reports the upgrade authority only, so * immutable programs have no authority. * - * Only account headers are fetched, so the program ELF is never downloaded. + * Only the header of the program data account is fetched, so the ELF of a + * loader v3 program is never downloaded. * Throws if the account is not an executable program owned by loader v2 or v3. */ export async function fetchProgramUpgradeAuthority( @@ -284,7 +279,7 @@ export async function fetchProgramUpgradeAuthority( program: Address | HasAddress, ): Promise { const programAddress = toAddress(program); - const programAccount = await fetchEncodedAccountHeader(rpc, programAddress, LOADER_V3_PROGRAM_HEADER_LENGTH); + const programAccount = await fetchEncodedAccount(rpc, programAddress); assertAccountExists(programAccount); if (!programAccount.executable) { @@ -301,16 +296,22 @@ export async function fetchProgramUpgradeAuthority( const [programDecoder, programDataDecoder] = getLoaderV3Decoders(); const programAccountData = programDecoder.decode(programAccount.data); - if (programAccountData.discriminator !== 2) { + if (programAccountData.discriminator !== LOADER_V3_PROGRAM_DISCRIMINATOR) { throw Error('Invalid program discriminator'); } const programData = programAccountData.programData; - const programDataAccount = await fetchEncodedAccountHeader(rpc, programData, LOADER_V3_PROGRAM_DATA_HEADER_LENGTH); + const { value } = await rpc + .getAccountInfo(programData, { + dataSlice: { length: LOADER_V3_PROGRAM_DATA_HEADER_LENGTH, offset: 0 }, + encoding: 'base64', + }) + .send(); + const programDataAccount = parseBase64RpcAccount(programData, value); assertAccountExists(programDataAccount); const programDataAccountData = programDataDecoder.decode(programDataAccount.data); - if (programDataAccountData.discriminator !== 3) { + if (programDataAccountData.discriminator !== LOADER_V3_PROGRAM_DATA_DISCRIMINATOR) { throw Error('Invalid program data discriminator'); } @@ -325,12 +326,11 @@ export async function fetchProgramUpgradeAuthority( }; } -async function fetchEncodedAccountHeader(rpc: Rpc, address: Address, length: number) { - const { value } = await rpc - .getAccountInfo(address, { dataSlice: { length, offset: 0 }, encoding: 'base64' }) - .send(); - return parseBase64RpcAccount(address, value); -} +const LOADER_V3_PROGRAM_DISCRIMINATOR = 2; +const LOADER_V3_PROGRAM_DATA_DISCRIMINATOR = 3; + +/** Discriminator (4) + slot (8) + optional authority (1 + 32). */ +const LOADER_V3_PROGRAM_DATA_HEADER_LENGTH = 45; function getLoaderV3Decoders() { return [