Overview
The Token-2022 confidential transfer extension keeps token balances and transfer amounts encrypted on chain while wallet and token account addresses stay public. A confidential token account holds three balances:
Incoming funds always land in the pending balance. Before you can spend them, you apply the pending balance, which moves it into the available balance.
The
@dynamic-labs-sdk/solana/waas package builds, signs, and optionally broadcasts each operation for an embedded Solana wallet, and it can decrypt the encrypted balances so your application can display them. Confidential transfers work only with embedded wallets that use V3 MPC. They are not available for external wallets such as Phantom.
Prerequisites
- An embedded Solana wallet account, and a project environment whose default embedded wallet version is V3.
- SOL in the wallet. The wallet pays the transaction fee, and
configureAccountalso pays the rent to create and grow the token account. - A Token-2022 mint with the confidential transfer extension enabled. If the mint does not auto-approve new accounts, its confidential transfer authority must approve each token account after
configureAccount. The SDK does not send that instruction. - A public balance of the token in the wallet’s associated token account before you
deposit. @solana/web3.jsto derive token account addresses.
Step 1: Get the wallet account and token account
The functions on this page take the embedded SolanawalletAccount. The example below finds it and derives the wallet’s associated token account for your mint.
rpcUrl to the functions that accept it. The cluster behind rpcUrl must match the network you intend to use.
Step 2: Create the confidential seed
Create the confidential seed once for each wallet, before its first confidential operation. The seed is generated inside a secure enclave and stored encrypted, and it never leaves the enclave in plaintext. The function returns the wallet’s ElGamal public key and the derivation version.409 response and the code confidential_seed_exists, and the existing seed is left unchanged.
Step 3: Configure the token account
configureAccount enables confidential transfers on the wallet’s token account, and it creates the associated token account if it does not exist. Every token account that will send or receive confidential funds must be configured, and only the account’s owner can do it: the owner’s wallet signs the transaction, and the enclave uses that wallet’s own ElGamal key. A sender cannot configure a recipient’s account, so each recipient runs configureAccount from their own wallet before they can receive a confidential transfer.
The SDK does not check whether the token account is already configured before it builds the transaction. Running configureAccount on an account that is already configured is not skipped. Token-2022 rejects it with the error ExtensionAlreadyInitialized, the transaction fails, and the account is unchanged. Run configureAccount once for each token account, and skip it for an account you have already configured.
Operations
There are five operations, and each one is a single Solana transaction. Every operation uses the same function with a differentoperation.
amount is a string in the token’s base units, so '1000000' is one token when the mint has 6 decimals, and decimals must match the mint. transfer also accepts an optional auditorElgamalPubkey for mints that configure an auditor.
applyPendingBalance before it can transfer or withdraw those funds.
How signing works
Each call tosignConfidentialTransfer runs the same sequence:
- The SDK reads the token account state and the latest blockhash from the RPC endpoint, because the secure enclave that builds the transaction cannot reach the network.
- The enclave builds one unsigned transaction containing the confidential instruction and its zero-knowledge proofs, using the wallet’s confidential seed.
- The SDK signs the transaction with the wallet’s key share in a single signing session.
- If you set
broadcast: true, the SDK submits the transaction.
serializedTransactions with the signed transaction, signatures, and transactionIds when you broadcast. Broadcasting returns the transaction id without waiting for confirmation, so check that the transaction confirmed before you start the next operation.
Each operation requires one signing approval, so the user may be asked for multi-factor authentication or a step-up before it proceeds, the same as for any other wallet signing action.
Read decrypted balances
getConfidentialBalance decrypts both encrypted balances inside the enclave and returns them as decimal strings in base units.
connection.getTokenAccountBalance(new PublicKey(tokenAccount)).
Sign without broadcasting
Leave outbroadcast to get the signed transaction back without submitting it. Submit it yourself, and confirm it before the next operation.
Supply account state yourself
By default the SDK fetches the token account state from the RPC endpoint. If you already have it, pass it asaccountState to getConfidentialBalance to skip that request. It has the shape { data, lamports, owner }, where data is the base64 account data and lamports and owner are strings.