Confidential Asset (CA)

The @aptos-labs/confidential-asset package provides a high-level TypeScript API for interacting with the Confidential Asset protocol on Aptos.

Installation

npm install @aptos-labs/confidential-asset @aptos-labs/ts-sdk

@aptos-labs/confidential-asset-bindings is a transitive dependency that ships the WebAssembly glue used for range proof generation/verification and discrete log solving. You don’t need to install it directly.

WASM initialization

The .wasm binary is loaded lazily — it is not bundled with the SDK, so apps that never use confidential assets don’t pay the ~774 KiB binary cost. The first call to a function that needs WASM will trigger a one-time load (from node_modules in Node.js, or from a CDN in the browser). No explicit initializeWasm() call is required.

For native apps, you can generate Android and iOS bindings from the confidential-asset-wasm-bindings repository.

---

Create the ConfidentialAsset client:

import { AptosConfig, Network } from "@aptos-labs/ts-sdk";
import { ConfidentialAsset } from "@aptos-labs/confidential-asset";

const config = new AptosConfig({ network: Network.TESTNET });
const confidentialAsset = new ConfidentialAsset({ config });

The constructor also accepts:

• confidentialAssetModuleAddress — override the framework address (defaults to 0x1).
• withFeePayer — when true, every transaction submitted by this client is built with a fee-payer address.

Create Decryption Key (DK)

To interact with the confidential asset, create a unique key pair first.

Generate new:

import { TwistedEd25519PrivateKey } from "@aptos-labs/confidential-asset";

const dk = TwistedEd25519PrivateKey.generate();

Or import an existing one:

const dk = new TwistedEd25519PrivateKey("0x...");

You can also derive it from a signature (for testing purposes, don’t use in production):

import { Account } from "@aptos-labs/ts-sdk";

const user = Account.generate();
const signature = user.sign(TwistedEd25519PrivateKey.decryptionKeyDerivationMessage);
const dk = TwistedEd25519PrivateKey.fromSignature(signature);

Or derive a DK from a BIP-44 mnemonic + hardened derivation path (Ed25519 supports hardened derivation only):

const dk = TwistedEd25519PrivateKey.fromDerivationPath(
  "m/44'/637'/0'/0'/0'",
  "your twelve word mnemonic here ...",
);

Register

Before using confidential balances, register an encryption key for the asset type:

const registerTxResponse = await confidentialAsset.registerBalance({
  signer: user,
  tokenAddress: TOKEN_ADDRESS,
  decryptionKey: dk,
});

Check if a user has already registered for a specific asset type:

const isRegistered = await confidentialAsset.hasUserRegistered({
  accountAddress: user.accountAddress,
  tokenAddress: TOKEN_ADDRESS,
});

Deposit

Deposit tokens from a non-confidential FA balance into a confidential balance:

const depositTxResponse = await confidentialAsset.deposit({
  signer: user,
  tokenAddress: TOKEN_ADDRESS,
  amount: 100n,
  recipient: someAddress, // Optional — defaults to the signer's own confidential balance
});

Get User’s Balance

Check the user’s balance after the deposit. The getBalance method returns the decrypted pending and available balances:

const balance = await confidentialAsset.getBalance({
  accountAddress: user.accountAddress,
  tokenAddress: TOKEN_ADDRESS,
  decryptionKey: dk,
});

console.log("Available:", balance.availableBalance()); // bigint
console.log("Pending:", balance.pendingBalance());     // bigint

注意

availableBalance() returns the balance that can be spent (via transfer or withdrawal). pendingBalance() returns incoming funds that need to be rolled over first.

Rollover

After depositing, the funds are in the pending balance. A user cannot spend pending balance directly — it must be rolled over to the available balance.

警告

The available balance must be normalized before a rollover. The SDK handles this automatically if you provide a senderDecryptionKey.

const rolloverTxResponses = await confidentialAsset.rolloverPendingBalance({
  signer: user,
  tokenAddress: TOKEN_ADDRESS,
  senderDecryptionKey: dk, // Required if balance might not be normalized
  withPauseIncoming: false, // Set to true to also pause incoming transfers (for key rotation flows)
});

This may return multiple transaction responses (a normalization transaction followed by a rollover transaction) if the available balance was not already normalized.

Set withPauseIncoming: true to invoke the on-chain rollover_pending_balance_and_pause entry function, which atomically rolls over and pauses incoming transfers — the prerequisite for key rotation.

---

Normalization

Usually you don’t need to call normalization explicitly — rolloverPendingBalance handles it automatically when given a senderDecryptionKey.

If you want to normalize manually:

警告

Check if the balance is already normalized before calling this — normalizing an already-normalized balance will fail.

const isNormalized = await confidentialAsset.isBalanceNormalized({
  accountAddress: user.accountAddress,
  tokenAddress: TOKEN_ADDRESS,
});

if (!isNormalized) {
  const normalizeTxResponse = await confidentialAsset.normalizeBalance({
    signer: user,
    senderDecryptionKey: dk,
    tokenAddress: TOKEN_ADDRESS,
  });
}

Withdraw

Withdraw assets from a confidential balance back to a non-confidential FA balance:

const withdrawTxResponse = await confidentialAsset.withdraw({
  signer: user,
  senderDecryptionKey: dk,
  tokenAddress: TOKEN_ADDRESS,
  amount: 50n,
  recipient: recipientAddress, // Optional — defaults to signer's address
});

If the available balance is insufficient but the total (available + pending) is enough, use withdrawWithTotalBalance which automatically rolls over the pending balance first:

const withdrawTxResponses = await confidentialAsset.withdrawWithTotalBalance({
  signer: user,
  senderDecryptionKey: dk,
  tokenAddress: TOKEN_ADDRESS,
  amount: 50n,
});

Transfer

For a confidential transfer, you need the recipient’s account address. The SDK automatically fetches the recipient’s on-chain encryption key:

const transferTxResponse = await confidentialAsset.transfer({
  signer: user,
  recipient: recipientAddress,
  tokenAddress: TOKEN_ADDRESS,
  amount: 50n,
  senderDecryptionKey: dk,
  additionalAuditorEncryptionKeys: [], // Optional voluntary auditors
  memo: new TextEncoder().encode("invoice-42"), // Optional, up to 256 bytes
});

注意

If an effective auditor (global or asset-specific) is configured, the SDK automatically includes the auditor’s ciphertext in the transfer. You do not need to add it manually.

注意

The SDK pre-checks the recipient’s confidential store: it throws if the recipient hasn’t registered for the asset type or has paused incoming transfers, so you avoid generating a proof that the contract would just reject. Memo length is also validated against the on-chain get_max_memo_bytes() limit (default 256).

警告

The memo is stored on-chain in plaintext as part of the Transferred event. Encrypt sensitive payloads client-side before passing them in.

Like with withdrawals, you can use transferWithTotalBalance to automatically roll over the pending balance if the available balance is insufficient:

const transferTxResponses = await confidentialAsset.transferWithTotalBalance({
  signer: user,
  recipient: recipientAddress,
  tokenAddress: TOKEN_ADDRESS,
  amount: 50n,
  senderDecryptionKey: dk,
});

You can also look up a user’s encryption key directly:

const recipientEK = await confidentialAsset.getEncryptionKey({
  accountAddress: recipientAddress,
  tokenAddress: TOKEN_ADDRESS,
});

Key Rotation

To rotate the encryption key, provide the current and new decryption keys. The SDK handles pausing incoming transfers, rolling over pending balance, rotating the key, and resuming transfers:

const newDk = TwistedEd25519PrivateKey.generate();

const rotationTxResponses = await confidentialAsset.rotateEncryptionKey({
  signer: user,
  senderDecryptionKey: dk,
  newSenderDecryptionKey: newDk,
  tokenAddress: TOKEN_ADDRESS,
});

// Save the new decryption key — the old one is no longer valid
console.log("New DK:", newDk.toString());

警告

After key rotation, you must use the new decryption key for all subsequent operations. The old key will no longer be able to decrypt the balance.

Pause/Unpause Incoming Transfers

Check if a user’s incoming transfers are paused:

const isPaused = await confidentialAsset.isIncomingTransfersPaused({
  accountAddress: user.accountAddress,
  tokenAddress: TOKEN_ADDRESS,
});

Auditors

Query auditor configuration for an asset type:

// Get effective auditor encryption key (asset-specific if set, otherwise global)
const auditorEK = await confidentialAsset.getAssetAuditorEncryptionKey({
  tokenAddress: TOKEN_ADDRESS,
});

Read the auditor hint recorded against the user’s confidential store. Auditors compare its (isGlobal, epoch) against the current effective auditor config to detect stale ciphertexts:

const hint = await confidentialAsset.getEffectiveAuditorHint({
  accountAddress: user.accountAddress,
  tokenAddress: TOKEN_ADDRESS,
});

if (hint) {
  console.log(`Encrypted under ${hint.isGlobal ? "global" : "asset-specific"} auditor at epoch ${hint.epoch}`);
}

Emergency Pause

Governance can pause all user operations on the protocol via set_emergency_paused. Check the current state before submitting transactions:

const paused = await confidentialAsset.isEmergencyPaused();

Indexer Activities

Query confidential asset activity for an account from the indexer. Each row is a discriminated union keyed on event_type ("Registered", "Deposited", "Withdrawn", "Transferred", "Normalized", "RolledOver", "KeyRotated", "IncomingTransfersPauseChanged", "AllowListingChanged", "ConfidentialityForAssetTypeChanged", "GlobalAuditorChanged", "AssetSpecificAuditorChanged"):

const activities = await confidentialAsset.getActivities({
  where: { owner_address: { _eq: user.accountAddress.toStringLong() } },
  orderBy: [{ transaction_version: "desc" }],
  limit: 20,
});

for (const a of activities) {
  if (a.event_type === "Transferred") {
    // Narrowed to TransferredActivity — counterparty_address is non-null,
    // event_data has amount_P / amount_R_* / memo / sender_auditor_hint.
    console.log(a.counterparty_address, a.event_data.memo);
  } else if (a.event_type === "Withdrawn") {
    // Narrowed to WithdrawnActivity — `amount` is plaintext.
    console.log(a.amount, a.event_data.auditor_hint);
  }
}