Confidential Wholesale CBDC Wrapper API Workflow

The confidential wholesale central bank digital currency (CBDC) scenario represents currency that is distributed through a structured financial institution hierarchy, with sensitive information stored privately.

The confidential version of the wholesale CBDC scenario differs in how transaction data is handled. Non-sensitive information such as basic transaction details and organizational account information is stored on the public ledger. Sensitive information (such as user IDs, actual balance values, and blinding factors) is stored in each organization's private data collection and passed to the chaincode via a transient map, so that it is never written to the public ledger. Account balances and on-hold balances are represented as Pedersen commitment values on the public ledger, allowing public verification through zero-knowledge proofs without exposing the underlying amounts. At the central bank level, hold transfers use a two-phase commit process for an atomic transaction that requires simultaneous execution of both the executeHoldTokensSender and executeHoldTokensReceiver APIs, which maintains confidentiality throughout the transfer. Transfers at the financial institution level use the standard single executeHoldTokens API.

The following table summarizes the key differences between the non-confidential and confidential versions of the wholesale CBDC scenario.

Operation/Data	Non-Confidential CBDC	Confidential CBDC
Inter-Organization Transfer (central bank approver executes hold)	executeHoldTokens API (single call)	executeHoldTokensSender and executeHoldTokensReceiver APIs (two simultaneous calls done in two-phase commit)
Intra-Organization Transfer (financial institution approver executes hold)	executeHoldTokens API (single call)	executeHoldTokens API (single call, no difference)
Transaction Data on Ledger	All data stored in plain form on the public ledger, no data separation	Non-sensitive data on public ledger, sensitive data (user IDs, actual balances, blinding factors) stored in each organization's private data collection
Balance Representation	Actual balance values stored directly	Balances represented as Pedersen commitment values, actual amounts not exposed on the public ledger
Verification Method	Direct: values are readable on the ledger	Zero-knowledge proofs enable public verification without revealing underlying amounts
Sensitive Data Handling	Stored on public ledger	Passed via transient map to chaincode, not written to the public ledger

Note:

The executeHoldTokensSender and executeHoldTokensReceiver APIs must be called simultaneously as part of a two-phase commit process. Calling only one without the other results in an error.

The following diagram shows a typical process flow when using the sample confidential wholesale CBDC wrapper APIs.

Description of the illustration cbdc_confidential_-_wrapperapi.png