ConfidentialFungibleToken API

Per-(owner, spender) encrypted escrow. Stored as two ciphertexts of the same value: one to the spender, one to the owner. No public cap.

Spendable (confirmed) balances, encrypted under each account's ElGamal key. Debits draw from here. Paired with _pending: only the owner moves pending into spendable, via sweep, so a third party spamming dust credits cannot churn a victim's spendable ciphertext and invalidate their in-flight spend proofs. A wallet's total is balanceOf + pendingOf.

Incoming (unconfirmed) balances, encrypted under each account's ElGamal key. Credits land here rather than in _balances; the owner moves them across with sweep.

Mapping from account identifiers to their ElGamal public key, set by register. Membership in this map is what "registered" means throughout the module. Registration is one-shot: a second registration for the same account is rejected.

Mapping from account identifiers to their memo list. Every credit pushes one memo carrying the credited amount, encrypted to the recipient's key, to the front of the list, so the newest memo comes first. Memos record credits only; debits leave none.

Mapping from owner accounts to spender accounts to their EscrowEntry. Membership is checked independently of the entry, so an allowance that was never escrowed is unspendable. A spend also requires both owner and spender to be registered, so an entry written here for an unregistered account (for example by a composing contract) is unspendable as well.

Per-(owner, spender) escrow-spend counter, folded into the randomness _spendEscrow derives so repeat spends by one spender against one owner never share a one-time pad. It restarts for each pair, which is why both counterparties are bound in too; see SpendRandomnessPreimage.

Kept out of EscrowEntry: approve replaces that entry wholesale, so a counter living there would restart on every re-approve.

Note that this exposes a per-pair spend count which is already derivable from tx history.

Per-account credit counter. _credit uses it as the nonce that keeps each credit's randomness distinct, so it MUST only ever increase. No circuit resets it. It is kept out of _memos for that reason: the memo list is prunable by its owner, and a nonce that could be walked back would let a reused seed repeat an earlier credit's randomness. The cost is that an account's lifetime credit count is permanently readable from state.

Counter is chosen for no-reset monotonicity, not commutativity. Its increment emits no pinned read, but _credit reads the value back to derive the nonce, and that read pins the recipient's key. Credits to one recipient still serialize; see the Concurrency note above.

Whether initialize has run. Guards against re-initialization and against use before initialization.

The token's human-readable name, set once at construction.

The token's ticker symbol, set once at construction.

The number of decimals used to display balances, set once at construction. Purely presentational; no circuit scales by it.

Returns the caller's account secret. Verified in-circuit by matching persistentHash(SK) against the public accountId.

Returns the caller's ElGamal secret. Verified in-circuit by ElGamal_assertDecryptsTo, which re-derives the pk and compares against the stored pk.

Returns the wallet's cached plaintext for the given ciphertext. Called whenever the circuit needs to verify a ciphertext's plaintext value (sender's main balance, escrow ciphertext during spend, prior escrow during refund, etc.).

The ciphertext is passed explicitly so the wallet can route to the right cached plaintext by ciphertext identity. This avoids call-order conventions (which would be brittle to circuit refactors) and lets the wallet maintain a Map<ElGamal_Ciphertext, Uint248> lookup.

Verified in-circuit by ElGamal_assertDecryptsTo: a wrong plaintext fails the assertion Dec(ct, EK) == claimedValue.

Returns a single 32-byte seed from which all per-operation randomness (and each memo's ephemeral) is derived in-circuit.

Seed freshness is load-bearing for confidentiality on EVERY path (see the module header). The derivation is deterministic and public, so an observer who knows the seed can strip a memo's mask and read the delivered amount, and recover balance/escrow amounts from the public ciphertexts. Seed REUSE leaks plaintext differences and the circuit does NOT prevent it on most paths. _spendEscrow is an exception (its randomness folds the spend epoch and both counterparties); the credit path folds the recipient's _creditEpochs counter as defense in depth, and that covers credits alone. The seed MUST be fresh, high-entropy, and secret for every invocation.

Maximum allowed value per single transfer / mint / burn / approve: the Uint<128> maximum. The prior 2^48 cap existed only to keep wallet-side discrete-log recovery tractable; with the ECDH memo delivering values directly (see crypto/EcdhMask), that constraint is gone. Values stay well under the Jubjub scalar-field order, so homomorphic sums do not wrap.

Initializes the token's name, symbol, and decimals. Intended to be called once, from the deploying contract's constructor.

Requirements:

• Contract is not already initialized.

Returns account's balance ciphertext, or the default (zero) ciphertext if the account is unregistered. The amount is encrypted; only the account (or an authorized viewer) can decrypt it.

Requirements:

• Contract is initialized.

Returns account's PENDING balance ciphertext (incoming credits not yet swept into spendable), or Enc(0) if unregistered. The spendable balance is balanceOf; a wallet's total is the sum of the two. See the dual-balance note on the ledger declarations.

Requirements:

• Contract is initialized.

Returns the escrow entry (the encrypted allowance) that owner granted spender. When no allowance exists, returns a placeholder entry rather than default<EscrowEntry>: the returned Jubjub points are on-curve, so the view is safe to prove (e.g. through a contract-to-contract call), whereas a zeroed default holds off-curve points. The cap is encrypted, not public.

Returns whether account has registered an encryption key.

Registers the caller: derives their encryption public key from wit_ConfidentialTokenEK and initializes their balance to an encryption of zero. Registration is a prerequisite for sending or receiving.

Requirements:

• Contract is initialized.
• The caller is not already registered.

Mints value to account: _credit under its intent name. The building block for a composing contract's gated mint; it performs no supply accounting. Pair it with a supply tracker (see extensions/ConfidentialFungibleTokenPublicSupply) if the deployment tracks totalSupply.

Requirements:

• Contract is initialized.
• value is within MAX_TRANSFER_VALUE.
• account is registered.

Burns value from the caller's own balance: _debit under its intent name. The building block for a composing contract's burn; it performs no supply accounting. Pair it with a supply tracker (see extensions/ConfidentialFungibleTokenPublicSupply) if the deployment tracks totalSupply.

Requirements:

• Contract is initialized.
• value is within MAX_TRANSFER_VALUE.
• The caller is registered and has a balance of at least value.

Transfers value from the caller to to: debits the caller, credits to, and pushes an encrypted memo to to. The amount is hidden; the (sender, recipient) pair is public.

Requirements:

• Contract is initialized.
• value is within MAX_TRANSFER_VALUE.
• The caller is registered with a balance of at least value.
• to is registered and is not the caller (no self-transfer).

The conserving value-movement primitive: debits the caller and credits to by the same value, net zero. It NEVER changes supply, so it is the safe surface for composition and the primitive this supply-free base exposes. transfer is _move plus a self-transfer guard; supply-changing operations (mint/burn) live in a separate layer outside this conserving surface, and only they may break conservation.

Self-move (to == caller) is PERMITTED here, unlike transfer, which rejects it. A self-move is conserving and safe: it debits the caller's spendable and credits the caller's own pending (net zero, distinct ledger cells; the value is recovered with sweep). transfer's self-transfer guard is therefore a UX choice, not a safety requirement: it spares users a self-transfer with no foreseeable benefit (a shuffle of spendable into pending plus a self-memo). This primitive stays permissive so a composer can set its own policy; add a to != caller check in the wrapper to reject a self-move.

Requirements:

• Contract is initialized.
• The caller is registered with a spendable balance of at least value.
• to is registered.

Sweeps the caller's incoming pending pool into their spendable balance. Credits land in pending (see the dual-balance note); this sweep is the ONLY path from pending into spendable, and only the owner can invoke it (the caller proves BOTH witness secrets: the account secret identifies the account, the encryption secret proves the caller can read it). So a third party spamming credits cannot force a victim's spendable ciphertext to change, which is what would otherwise invalidate the victim's in-flight spend proofs (a liveness grief).

Requirements:

• Contract is initialized.
• The caller is registered.
• The caller holds the encryption secret registered for their account.

Sets spender's allowance over the caller's balance to value via an escrow: the caller's main balance is debited by value, and matching encryptions are stored for the spender and the owner. Re-approving first refunds any prior escrow, so allowances replace rather than stack. The cap is not public.

The allowance is funded at approve time, and funding is required: the spender holds no owner encryption key, so at spend time it can only prove against its own escrow copy, never that the owner's balance covers the allowance. An approve conserves the owner's holdings (spendable plus every outstanding escrow), so allowances across spenders can sum to the whole holding but never exceed it.

Also stores an owner-readable ownerMemo (ECDH one-time pad; see crypto/EcdhMask) in the escrow entry, carrying the current remaining allowance (= value here, refreshed to the reduced remaining on every spend). This is what lets the owner prove the post-refund balance on a later re-approve or revoke after a partial spend; without it a partial spend would strand the escrow. See the EscrowEntry field doc.

Requirements:

• Contract is initialized.
• value is within MAX_TRANSFER_VALUE.
• spender is registered, is not the zero account, and is not the caller.
• The caller is registered with a balance of at least value.

Spends value from fromAddress's escrow (granted to the caller via approve) and credits it to to, reducing both escrow copies by value. The amount is hidden.

Requirements:

• Contract is initialized.
• value is within MAX_TRANSFER_VALUE.
• to is registered and is not the zero account.
• An escrow from fromAddress to the caller exists with at least value.
• fromAddress and the caller are registered.

Clears the caller's memo list, letting a wallet that has folded its memos into its local balance cache prune on-chain memo storage.

expectedEpoch is the caller's view of its _creditEpochs value at the moment it read the list. The call is rejected unless that still matches, so a credit landing between the read and this transaction is never silently discarded. The wallet retries against the memos it has now seen. A wallet therefore reads its memo list and its epoch together, folds the memos into its cache, and passes that epoch back here.

Requirements:

• Contract is initialized.
• The caller is registered.
• The caller holds the encryption secret registered for their account.
• The caller has a memo list.
• expectedEpoch equals the caller's current credit epoch.

Derives the public accountId from a secret key, as persistentHash(sk). Pure, so a wallet can compute its own account identifier off-chain (no proof) before transacting.

Delegates to Utils.computeAccountId rather than reimplementing the hash. The identifier is deliberately GLOBAL. The same key material yields the same id in every module that derives it.

Burns value from fromAddress by consuming an escrow that owner granted to the caller: _spendEscrow under its intent name, with no recipient credit. The building block for a composing contract's burnFrom; it performs no supply accounting (see _burn).

Requirements:

• Contract is initialized.
• value is within MAX_TRANSFER_VALUE.
• An escrow from fromAddress to the caller exists with at least value.
• fromAddress and the caller are registered.

Total tokens in circulation, tracked in the clear even though balances are encrypted. Raised by _addSupply and lowered by _subSupply, each rejecting over/underflow.

Increases totalSupply by value. Call alongside the token module's _mint. The added amount is disclosed via the supply delta.

Requirements:

• totalSupply + value does not overflow Uint<128>.

Decreases totalSupply by value. Call alongside the token module's _burn or _burnFrom. The removed amount is disclosed via the supply delta.

Requirements:

• totalSupply is at least value.

Returns the public total token supply.