feat(clients/js): add permissioned confidential burn instruction plan

eldarik · claude · eldarik · commit 5f375a49d6d6 · 2026-07-28T23:04:58.000+05:00
Extract the shared proof setup/cleanup/args from
getConfidentialBurnInstructionPlan into buildConfidentialBurnProofPlan,
then add getPermissionedConfidentialBurnInstructionPlan on top of it. The
two variants compute identical proofs and differ only in the middle
instruction and its signer set: the standard variant carries
multiSigners, while the permissioned variant has the mint's configured
permissionedBurnAuthority co-sign alongside the account owner.

token-2022 rejects the standard ConfidentialBurn instruction on mints
carrying the PermissionedBurn extension, so this variant is required for
such mints (as tokenized-security mints use).

Support the case in the test harness by letting
createConfidentialMintBurnMint optionally attach the PermissionedBurn
extension, and add an integration test covering a confidential burn on a
permissioned mint.

Co-Authored-By: Claude Opus 5 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/clients/js/src/confidentialTransferHelpers.ts b/clients/js/src/confidentialTransferHelpers.ts
@@ -80,6 +80,7 @@ import {
     getConfigureConfidentialTransferAccountInstruction,
     getCreateAssociatedTokenIdempotentInstruction,
     getEmptyConfidentialTransferAccountInstruction,
+    getPermissionedConfidentialBurnInstruction,
     getReallocateInstruction,
     getUpdateConfidentialMintBurnDecryptableSupplyInstruction,
     fetchToken,
@@ -328,6 +329,15 @@ type GetConfidentialBurnInstructionPlanBaseInput = {
 export type GetConfidentialBurnInstructionPlanInput = GetConfidentialBurnInstructionPlanBaseInput &
     ConfidentialTransferContextStateProofMode;
 
+export type GetPermissionedConfidentialBurnInstructionPlanInput = GetConfidentialBurnInstructionPlanInput & {
+    /**
+     * The authority configured on the mint's `PermissionedBurn` extension. It
+     * must sign every permissioned burn; the token-2022 program rejects the
+     * standard burn variant when this extension is present.
+     */
+    permissionedBurnAuthority: TransactionSigner;
+};
+
 export type GetUpdateConfidentialMintBurnDecryptableSupplyInstructionFromSupplyInput = {
     mint: Address;
     authority: Address | TransactionSigner;
@@ -1524,18 +1534,18 @@ export async function getConfidentialMintInstructionPlan(
 }
 
 /**
- * Returns an instruction plan that confidentially burns `amount` tokens from a
- * token account's available balance, encrypting the amount on-chain and
- * advancing the mint's encrypted pending burn. Symmetric to
- * `getConfidentialMintInstructionPlan`.
+ * Computes the three burn proofs (equality, grouped-ciphertext validity, U128
+ * range), builds their context-state setup/cleanup plans, and assembles the
+ * burn-instruction arguments shared by both the standard and permissioned burn
+ * variants. Shared by {@link getConfidentialBurnInstructionPlan} and
+ * {@link getPermissionedConfidentialBurnInstructionPlan} — the two differ only
+ * in which middle instruction they emit and its signer set, not in the proofs.
  *
  * The amount is grouped-encrypted under `[source, supply, auditor]`; the source
  * handle (index 0) is homomorphically subtracted from the account's available
  * balance, and the auditor handle (index 2) is carried by the instruction.
  */
-export async function getConfidentialBurnInstructionPlan(
-    input: GetConfidentialBurnInstructionPlanInput,
-): Promise<InstructionPlan> {
+async function buildConfidentialBurnProofPlan(input: GetConfidentialBurnInstructionPlanInput) {
     const sourceAccount = getRequiredConfidentialTransferAccountExtension(input.sourceTokenAccount);
     const mintBurnExtension = getRequiredMintExtension(input.mintAccount, 'ConfidentialMintBurn');
     const amount = BigInt(input.amount);
@@ -1638,31 +1648,80 @@ export async function getConfidentialBurnInstructionPlan(
         buildContextStateProofPlan(rangeProofData.toBytes(), verifyBatchedRangeProofU128, input.payer, input.rpc),
     ]);
 
-    return sequentialInstructionPlan([
-        parallelInstructionPlan([equalityProofPlan.setup, ciphertextValidityProofPlan.setup, rangeProofPlan.setup]),
-        getConfidentialBurnInstruction(
-            {
-                token: input.token,
-                mint: input.mint,
-                equalityRecord: equalityProofPlan.address,
-                ciphertextValidityRecord: ciphertextValidityProofPlan.address,
-                rangeRecord: rangeProofPlan.address,
-                authority: input.authority,
-                newDecryptableAvailableBalance: input.aesKey.encrypt(remainingBalance).toBytes(),
-                burnAmountAuditorCiphertextLo,
-                burnAmountAuditorCiphertextHi,
-                equalityProofInstructionOffset: 0,
-                ciphertextValidityProofInstructionOffset: 0,
-                rangeProofInstructionOffset: 0,
-                multiSigners: input.multiSigners,
-            },
-            { programAddress: getTokenProgramAddress(input.programAddress) },
-        ),
-        parallelInstructionPlan([
+    return {
+        setup: parallelInstructionPlan([
+            equalityProofPlan.setup,
+            ciphertextValidityProofPlan.setup,
+            rangeProofPlan.setup,
+        ]),
+        cleanup: parallelInstructionPlan([
             equalityProofPlan.cleanup,
             ciphertextValidityProofPlan.cleanup,
             rangeProofPlan.cleanup,
         ]),
+        // Arguments common to both burn instruction variants. The account owner
+        // (`authority`) always signs; the variant-specific signer field
+        // (`multiSigners` / `permissionedBurnAuthority`) is added by the caller.
+        burnArgs: {
+            token: input.token,
+            mint: input.mint,
+            equalityRecord: equalityProofPlan.address,
+            ciphertextValidityRecord: ciphertextValidityProofPlan.address,
+            rangeRecord: rangeProofPlan.address,
+            authority: input.authority,
+            newDecryptableAvailableBalance: input.aesKey.encrypt(remainingBalance).toBytes(),
+            burnAmountAuditorCiphertextLo,
+            burnAmountAuditorCiphertextHi,
+            equalityProofInstructionOffset: 0,
+            ciphertextValidityProofInstructionOffset: 0,
+            rangeProofInstructionOffset: 0,
+        },
+    };
+}
+
+/**
+ * Returns an instruction plan that confidentially burns `amount` tokens from a
+ * token account's available balance, encrypting the amount on-chain and
+ * advancing the mint's encrypted pending burn. Symmetric to
+ * `getConfidentialMintInstructionPlan`.
+ *
+ * Emits the **standard** `ConfidentialBurn` instruction. For mints carrying the
+ * `PermissionedBurn` extension the token-2022 program rejects this variant — use
+ * {@link getPermissionedConfidentialBurnInstructionPlan} instead.
+ */
+export async function getConfidentialBurnInstructionPlan(
+    input: GetConfidentialBurnInstructionPlanInput,
+): Promise<InstructionPlan> {
+    const { setup, cleanup, burnArgs } = await buildConfidentialBurnProofPlan(input);
+    return sequentialInstructionPlan([
+        setup,
+        getConfidentialBurnInstruction(
+            { ...burnArgs, multiSigners: input.multiSigners },
+            { programAddress: getTokenProgramAddress(input.programAddress) },
+        ),
+        cleanup,
+    ]);
+}
+
+/**
+ * Like {@link getConfidentialBurnInstructionPlan}, but emits the **permissioned**
+ * burn variant, which token-2022 requires for mints carrying the
+ * `PermissionedBurn` extension (it rejects the standard variant on such mints
+ * with `TokenError::InvalidInstruction`). Identical proofs; the only difference
+ * is the mint's configured `permissionedBurnAuthority` co-signs alongside the
+ * account owner (`authority`).
+ */
+export async function getPermissionedConfidentialBurnInstructionPlan(
+    input: GetPermissionedConfidentialBurnInstructionPlanInput,
+): Promise<InstructionPlan> {
+    const { setup, cleanup, burnArgs } = await buildConfidentialBurnProofPlan(input);
+    return sequentialInstructionPlan([
+        setup,
+        getPermissionedConfidentialBurnInstruction(
+            { ...burnArgs, permissionedBurnAuthority: input.permissionedBurnAuthority },
+            { programAddress: getTokenProgramAddress(input.programAddress) },
+        ),
+        cleanup,
     ]);
 }
 
diff --git a/clients/js/test/_setup.ts b/clients/js/test/_setup.ts
@@ -291,6 +291,12 @@ export const createConfidentialMintBurnMint = async (input: {
     payer: TransactionSigner;
     decimals?: number;
     auditorElgamalPubkey?: Address;
+    /**
+     * When provided, the mint additionally carries the `PermissionedBurn`
+     * extension with this authority — which forces confidential burns to use
+     * the permissioned variant.
+     */
+    permissionedBurnAuthority?: TransactionSigner;
 }): Promise<{
     mint: Address;
     mintAuthority: TransactionSigner;
@@ -322,6 +328,9 @@ export const createConfidentialMintBurnMint = async (input: {
                     supplyElgamalPubkey,
                     pendingBurn: new Uint8Array(64).fill(0),
                 }),
+                ...(input.permissionedBurnAuthority
+                    ? [extension('PermissionedBurn', { authority: some(input.permissionedBurnAuthority.address) })]
+                    : []),
             ],
         })
         .sendTransaction();
diff --git a/clients/js/test/extensions/confidentialMintBurn/getPermissionedConfidentialBurnInstructionPlan.test.ts b/clients/js/test/extensions/confidentialMintBurn/getPermissionedConfidentialBurnInstructionPlan.test.ts
@@ -0,0 +1,134 @@
+import { isSome } from '@solana/kit';
+import { AeCiphertext } from '@solana/zk-sdk/bundler';
+import { expect, it } from 'vitest';
+
+import { Mint, fetchMint, fetchToken, getApplyConfidentialPendingBurnInstruction } from '../../../src';
+import {
+    decryptConfidentialTransferBalance,
+    getApplyConfidentialPendingBalanceInstructionFromToken,
+    getConfidentialMintInstructionPlan,
+    getPermissionedConfidentialBurnInstructionPlan,
+    getUpdateConfidentialMintBurnDecryptableSupplyInstructionFromSupply,
+} from '../../../src/confidential';
+import {
+    createConfidentialMintBurnMint,
+    createConfidentialTokenAccount,
+    createValidatorClient,
+    generateKeyPairSignerWithSol,
+} from '../../_setup';
+
+const DECIMALS = 2;
+const MINT_AMOUNT = 500n;
+const BURN_AMOUNT = 200n;
+
+function getConfidentialMintBurnExtension(mint: Mint) {
+    if (!isSome(mint.extensions)) {
+        throw new Error('Mint account is missing extensions.');
+    }
+    const extension = mint.extensions.value.find(candidate => candidate.__kind === 'ConfidentialMintBurn');
+    if (!extension || extension.__kind !== 'ConfidentialMintBurn') {
+        throw new Error('Mint account is missing the ConfidentialMintBurn extension.');
+    }
+    return extension;
+}
+
+it('confidentially burns from a mint carrying the PermissionedBurn extension', async () => {
+    // Given a mint-burn mint that ALSO carries the PermissionedBurn extension
+    // (as tokenized-security mints do). token-2022 rejects the standard
+    // confidential burn on such mints, so the permissioned variant is required.
+    const client = await createValidatorClient();
+    const payer = client.payer;
+    const owner = await generateKeyPairSignerWithSol(client);
+    const permissionedBurnAuthority = await generateKeyPairSignerWithSol(client);
+    const { mint, mintAuthority, supplyElgamalKeypair, supplyAesKey } = await createConfidentialMintBurnMint({
+        client,
+        payer,
+        decimals: DECIMALS,
+        permissionedBurnAuthority,
+    });
+    const account = await createConfidentialTokenAccount({ client, payer, owner, mint });
+
+    // When the authority confidentially mints into the account's pending balance.
+    const [{ data: destinationTokenAccount }, { data: mintAccount }] = await Promise.all([
+        fetchToken(client.rpc, account.token),
+        fetchMint(client.rpc, mint),
+    ]);
+    await client.sendTransactions(
+        await getConfidentialMintInstructionPlan({
+            payer,
+            rpc: client.rpc,
+            token: account.token,
+            mint,
+            mintAccount,
+            destinationTokenAccount,
+            authority: mintAuthority,
+            amount: MINT_AMOUNT,
+            supplyElgamalKeypair,
+            supplyAesKey,
+        }),
+    );
+
+    // And the owner applies the pending balance so the minted amount is available.
+    const { data: afterMint } = await fetchToken(client.rpc, account.token);
+    await client.sendTransaction([
+        getApplyConfidentialPendingBalanceInstructionFromToken({
+            token: account.token,
+            tokenAccount: afterMint,
+            authority: owner,
+            elgamalSecretKey: account.elgamalKeypair.secret(),
+            aesKey: account.aesKey,
+        }),
+    ]);
+
+    // When the owner confidentially burns part of the available balance via the
+    // permissioned variant, co-signed by the mint's permissioned burn authority.
+    const [{ data: sourceTokenAccount }, { data: mintForBurn }] = await Promise.all([
+        fetchToken(client.rpc, account.token),
+        fetchMint(client.rpc, mint),
+    ]);
+    await client.sendTransactions(
+        await getPermissionedConfidentialBurnInstructionPlan({
+            payer,
+            rpc: client.rpc,
+            token: account.token,
+            mint,
+            mintAccount: mintForBurn,
+            sourceTokenAccount,
+            authority: owner,
+            permissionedBurnAuthority,
+            amount: BURN_AMOUNT,
+            sourceElgamalKeypair: account.elgamalKeypair,
+            aesKey: account.aesKey,
+        }),
+    );
+
+    // Then the available balance drops by the burnt amount.
+    const { data: afterBurn } = await fetchToken(client.rpc, account.token);
+    expect(
+        decryptConfidentialTransferBalance({
+            tokenAccount: afterBurn,
+            elgamalSecretKey: account.elgamalKeypair.secret(),
+            aesKey: account.aesKey,
+        }).availableBalance,
+    ).toBe(MINT_AMOUNT - BURN_AMOUNT);
+
+    // Finally the authority applies the mint's pending burn and re-syncs the
+    // decryptable supply.
+    await client.sendTransaction([
+        getApplyConfidentialPendingBurnInstruction({ mint, authority: mintAuthority }),
+        getUpdateConfidentialMintBurnDecryptableSupplyInstructionFromSupply({
+            mint,
+            authority: mintAuthority,
+            supplyAesKey,
+            supply: MINT_AMOUNT - BURN_AMOUNT,
+        }),
+    ]);
+
+    const { data: finalMint } = await fetchMint(client.rpc, mint);
+    const mintBurnExtension = getConfidentialMintBurnExtension(finalMint);
+    const decryptableSupplyCiphertext = AeCiphertext.fromBytes(new Uint8Array(mintBurnExtension.decryptableSupply));
+    if (!decryptableSupplyCiphertext) {
+        throw new Error('Failed to decode the decryptable supply ciphertext.');
+    }
+    expect(supplyAesKey.decrypt(decryptableSupplyCiphertext)).toBe(MINT_AMOUNT - BURN_AMOUNT);
+});
