Skip to main content

Confidential transfers

Use the optional confidential module to build encrypted MPT transactions and their proofs. Most applications should start with builders, not the native cryptography API.

You need this module if your application generates ciphertexts or proofs, or decrypts confidential balances. If another implementation supplies those values, core alone can encode, sign, and submit the transactions. Core field validation does not verify a ZK proof.

Before you start​

  • Follow installation for the module version and native toolchain.
  • Use a ledger with the required amendments enabled. SDK support and a final specification do not establish Mainnet availability.
  • Keep wallet signing keys separate from confidential encryption keys. Wallets authorize transactions. ElGamal keys encrypt amounts, decrypt balances, and support proofs.

How the flow fits together​

configure issuance -> register issuer/auditor encryption keys
-> authorize holder -> opt in with holder encryption key
public MPT -> convert -> confidential inbox -> merge -> spending balance
-> send -> recipient inbox
-> convert back -> public MPT

Builders read the needed ledger state, prepare ciphertexts and proofs, and return typed transactions. You still autofill remaining network fields, sign with a core wallet, submit, and check the validated result. Do not change a sequence or Ticket after preparing a proof that binds it.

Choose a guide​

GoalGuide
Build, sign, and submit a confidential operationBuilders
Read a spendable confidential balanceBalance reads
Combine dependent operations atomicallyConfidential batches
Assemble encrypted fields and proofs yourselfCryptographic helpers
Work with fixed-size bytes and native proof contractsNative API reference

Operations​

TransactionPurpose
ConfidentialMPTConvertConvert public MPT and optionally register a holder key on first use
ConfidentialMPTMergeInboxMake inbox funds available in the spending balance
ConfidentialMPTSendTransfer between opted-in holders
ConfidentialMPTConvertBackReturn confidential funds to public balance
ConfidentialMPTClawbackLet the issuer reclaim a holder's confidential balance

These transaction models and their ledger fields belong to core. See MPT operations for issuance capabilities and key registration. The XLS-96 specification defines the protocol.

Transaction cost​

Confidential MPT transactions cost ten network base fees: one base fee plus an extra multiplier of nine. Multisigning adds the usual one base fee per signer. The multiplier also applies to a confidential transaction inside a Batch.

RPC and WebSocket autofill apply this cost only when Fee is absent. A manually supplied fee is not overwritten. A fee sized for an ordinary transaction can underpay and fail with telINSUF_FEE_P. See Submission and finality for the SDK's autofill behavior.

Examples​

  • Offline example: prepares an issuance, key registration, a holder conversion, and an inbox merge. It does not connect, sign, or submit. Proof generation still requires the native toolchain.
  • RPC lifecycle and WebSocket lifecycle: fund test wallets, configure an issuance and holders, and submit transactions on Devnet.

Read the examples before running them. For a repository checkout, follow the workspace instructions. For version changes, use the confidential changelog.

Security​

Protect signing secrets and encryption private keys. Do not print, log, commit, or send them to telemetry. Test with non-production funds and read the security and audit notice before production use.