docs: Add confidential transfer issuer guide

[gitteri]

Adds an issuer-facing guide for the Confidential Transfer extension, the issuer counterpart to the integration guide in #1524. Modeled on the Scaled UI Amount issuer guide.

New page: tokens/extensions/confidential-transfer/issuer-guide, registered in meta.json and linked via a Card from the confidential transfer index.

Audience: teams creating and operating a confidential mint (stablecoin and tokenized-asset issuers), as distinct from holders (step pages) and product integrators (integration guide).

Sections:

• Decisions made at creation (approve policy, auditor, companion extensions)
• Create a confidential mint and choose an approve policy (auto vs manual)
• Configure and rotate a global auditor
• Approve accounts under a manual policy
• Confidential transfer fees: init, harvest, withdraw withheld
• Confidential mint and burn: encrypted supply, mint/burn/apply-pending-burn, supply key rotation
• Operational and compliance considerations (auditor key custody, KYT posture, onboarding via the registry, network requirements, txv1)

Examples use CLI, Rust, and JS where each exists. Honest about the gaps: account approval and fees have no CLI; confidential mint/burn is Rust only today (no JS instruction builders, no CLI). All signatures verified against spl-token-client and the token-2022 JS client.

Note: this PR and #1524 both edit confidential-transfer/meta.json and index.mdx, so whichever merges second will have a trivial conflict to resolve.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
solana-com-docs	Ready	Preview, Comment	Jun 17, 2026 3:57pm

5 Skipped Deployments

Project	Deployment	Actions	Updated (UTC)
solana-com	Skipped		Jun 17, 2026 3:57pm
solana-com-accelerate	Skipped		Jun 17, 2026 3:57pm
solana-com-breakpoint-2	Skipped		Jun 17, 2026 3:57pm
solana-com-media	Skipped		Jun 17, 2026 3:57pm
templates	Skipped		Jun 17, 2026 3:57pm

[vercel]

@gitteri is attempting to deploy a commit to the Solana Foundation Team on Vercel.

A member of the Team first needs to authorize it.

[greptile-apps]

Greptile Summary

This PR adds a new issuer-facing guide (issuer-guide.mdx) for the Confidential Transfer extension, targeting stablecoin and tokenized-asset issuers rather than holders or integrators. It is registered in meta.json and surfaced via a new Card on the index.mdx overview page.

• New page covers all issuer lifecycle operations: mint creation (approve policy, auditor, companion extensions), auditor rotation, account approval under a manual policy, confidential transfer fees (init, harvest, withdraw), and confidential mint/burn with supply key rotation.
• Multi-language examples are provided in CLI, Rust (spl-token-client), and TypeScript (@solana-program/token-2022) where each client supports the operation; gaps (no CLI or JS for confidential mint/burn) are called out explicitly with <Callout> blocks.
• Minor navigational risk: two links on lines 16 and 416 point to /docs/tokens/extensions/confidential-transfer/integration-guide, which is added by the sibling PR docs: Add confidential transfer integration guide #1524 and absent from meta.json in this branch — those links return 404 if this PR merges before docs: Add confidential transfer integration guide #1524.

Confidence Score: 4/5

Safe to merge once #1524 is merged first (or immediately after), given the outbound links to the integration guide do not resolve until that sibling PR lands.

The new guide is a documentation-only addition with no runtime code changes. The one actionable issue is that two links on lines 16 and 416 point to the integration guide page introduced by #1524, which is absent from this branch — those links will 404 if this PR lands before its sibling. All code snippets are well-formed and match the spl-token-client and @solana-program/token-2022 APIs; the burn step is present; and the TS harvest-withdraw gap is handled with explicit prose. The only other finding is a trivial comment typo.

issuer-guide.mdx — verify merge order with #1524 before landing to avoid broken links to the integration guide.

Important Files Changed

Filename	Overview
apps/docs/content/docs/en/tokens/extensions/confidential-transfer/issuer-guide.mdx	New 420-line issuer guide; well-structured with CLI/Rust/TS examples and explicit callouts for unsupported operations. Contains two outbound links to the integration-guide page (not yet in meta.json) and a minor comment typo in the Rust update-mint snippet.
apps/docs/content/docs/en/tokens/extensions/confidential-transfer/index.mdx	Minimal change — adds a single Card linking to the new issuer-guide page. No logic changes.
apps/docs/content/docs/en/tokens/extensions/confidential-transfer/meta.json	Adds issuer-guide to the sidebar navigation list. Correct placement; does not include integration-guide (expected since #1524 is a separate PR).

Sequence Diagram

%%{init: {'theme': 'neutral'}}%%
sequenceDiagram
    participant Issuer as Issuer
    participant CLI_Rust_TS as CLI / Rust / TS
    participant Token22 as Token-2022 Program
    participant ZKProgram as ZK ElGamal Proof Program
    participant TokenAccount as Holder Token Account

    rect rgba(120, 160, 235, 0.3)
    Note over Issuer,Token22: Mint Creation (one-time, irreversible)
    Issuer->>CLI_Rust_TS: Create mint (approve policy, optional auditor)
    CLI_Rust_TS->>Token22: InitializeConfidentialTransferMint + InitializeMint
    Token22-->>Issuer: Mint created
    end

    rect rgba(130, 210, 170, 0.3)
    Note over Issuer,Token22: Auditor Management (ongoing)
    Issuer->>CLI_Rust_TS: Update auditor ElGamal pubkey / policy
    CLI_Rust_TS->>Token22: UpdateConfidentialTransferMint
    Token22-->>Issuer: Auditor rotated (future transfers only)
    end

    rect rgba(200, 180, 100, 0.3)
    Note over Issuer,TokenAccount: Account Approval (manual policy only)
    TokenAccount->>Token22: ConfigureAccount (holder's signature)
    Issuer->>CLI_Rust_TS: ApproveAccount (Rust/TS only, no CLI)
    CLI_Rust_TS->>Token22: ApproveConfidentialTransferAccount
    Token22-->>TokenAccount: Account approved for confidential transfers
    end

    rect rgba(235, 120, 120, 0.3)
    Note over Issuer,ZKProgram: Confidential Mint/Burn (Rust only)
    Issuer->>CLI_Rust_TS: confidential_transfer_mint(amount)
    CLI_Rust_TS->>ZKProgram: Verify equality, ciphertext validity, range proofs
    CLI_Rust_TS->>Token22: ConfidentialMint to recipient pending balance
    Issuer->>CLI_Rust_TS: confidential_transfer_burn(amount)
    CLI_Rust_TS->>ZKProgram: Verify proofs
    CLI_Rust_TS->>Token22: ConfidentialBurn to mint pending burn
    Issuer->>Token22: ApplyPendingBurn - supply updated
    end

    rect rgba(180, 150, 235, 0.3)
    Note over Issuer,Token22: Fee Harvest and Withdrawal (Rust/TS, no CLI)
    Token22-->>Token22: Withheld fees accumulate on accounts (encrypted)
    CLI_Rust_TS->>Token22: HarvestWithheldTokensToMint (permissionless)
    Issuer->>CLI_Rust_TS: WithdrawWithheldTokensFromMint
    CLI_Rust_TS->>ZKProgram: Verify equality + range proofs
    CLI_Rust_TS->>Token22: Withdraw withheld fees to destination
    end

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
sequenceDiagram
    participant Issuer as Issuer
    participant CLI_Rust_TS as CLI / Rust / TS
    participant Token22 as Token-2022 Program
    participant ZKProgram as ZK ElGamal Proof Program
    participant TokenAccount as Holder Token Account

    rect rgba(120, 160, 235, 0.3)
    Note over Issuer,Token22: Mint Creation (one-time, irreversible)
    Issuer->>CLI_Rust_TS: Create mint (approve policy, optional auditor)
    CLI_Rust_TS->>Token22: InitializeConfidentialTransferMint + InitializeMint
    Token22-->>Issuer: Mint created
    end

    rect rgba(130, 210, 170, 0.3)
    Note over Issuer,Token22: Auditor Management (ongoing)
    Issuer->>CLI_Rust_TS: Update auditor ElGamal pubkey / policy
    CLI_Rust_TS->>Token22: UpdateConfidentialTransferMint
    Token22-->>Issuer: Auditor rotated (future transfers only)
    end

    rect rgba(200, 180, 100, 0.3)
    Note over Issuer,TokenAccount: Account Approval (manual policy only)
    TokenAccount->>Token22: ConfigureAccount (holder's signature)
    Issuer->>CLI_Rust_TS: ApproveAccount (Rust/TS only, no CLI)
    CLI_Rust_TS->>Token22: ApproveConfidentialTransferAccount
    Token22-->>TokenAccount: Account approved for confidential transfers
    end

    rect rgba(235, 120, 120, 0.3)
    Note over Issuer,ZKProgram: Confidential Mint/Burn (Rust only)
    Issuer->>CLI_Rust_TS: confidential_transfer_mint(amount)
    CLI_Rust_TS->>ZKProgram: Verify equality, ciphertext validity, range proofs
    CLI_Rust_TS->>Token22: ConfidentialMint to recipient pending balance
    Issuer->>CLI_Rust_TS: confidential_transfer_burn(amount)
    CLI_Rust_TS->>ZKProgram: Verify proofs
    CLI_Rust_TS->>Token22: ConfidentialBurn to mint pending burn
    Issuer->>Token22: ApplyPendingBurn - supply updated
    end

    rect rgba(180, 150, 235, 0.3)
    Note over Issuer,Token22: Fee Harvest and Withdrawal (Rust/TS, no CLI)
    Token22-->>Token22: Withheld fees accumulate on accounts (encrypted)
    CLI_Rust_TS->>Token22: HarvestWithheldTokensToMint (permissionless)
    Issuer->>CLI_Rust_TS: WithdrawWithheldTokensFromMint
    CLI_Rust_TS->>ZKProgram: Verify equality + range proofs
    CLI_Rust_TS->>Token22: Withdraw withheld fees to destination
    end

Loading

_{Reviews (7): Last reviewed commit: "docs: Fix approve snippet (token field) ..." | Re-trigger Greptile}

[catmcgee]

is this done by mint authority? or by the confidential transfer fee authority. maybe usually the same but technically different

https://github.com/solana-program/token-2022/blob/8e41eb3499ff/interface/src/extension/confidential_transfer_fee/instruction.rs#L181-L191

[gitteri]

Good catch, they are technically distinct. Fixed in 5c812c8: enable/disable harvest is gated on the ConfidentialTransferFeeConfig authority, while withdrawing withheld fees uses the transfer fee extension's withdraw withheld authority, and either can differ from the mint authority.

[ZYJLiu]

It looks like the mint-burn snippet is missing the surrounding <CodeTabs>, which causes the code block not to display on the preview

[gitteri]

Good catch, fixed in 4445db2. Also moved a stray prose paragraph out of the harvest/withdraw CodeTabs block, it had the same problem.

[ZYJLiu]

btw since this PR and the integration page on #1524 both edit the same meta.json, it will cause a minor merge conflict that when merging this one after the first is merged.

assuming this page comes after since the content links to the integration page