Zama confidential tokens (ERC-7984)

This guide shows how to hold, shield, receive, send and unshield Zama confidential tokens (ERC-7984) on Ethereum mainnet through the Utila API.

A Zama confidential token keeps balances and transfer amounts encrypted onchain. Block explorers show the sender and the recipient, but not the amount. Utila decrypts the values for the wallets in your vault and shows them in the API.

Each Zama confidential token is one side of a pair. The other side is the public token that the confidential token wraps.

Zama Protocol uses fully homomorphic encryption (FHE) to compute on encrypted data without decrypting it during computation. For background, see the Zama Protocol overview, the confidential tokens overview and Utila's help center article for managing ERC-7984 tokens.

Concepts

  • Activation gives Utila permission to decrypt the balances and transfer amounts of a wallet. Without activation, Utila cannot show these values.
  • Shield converts a public token into its confidential token, for example USDC into cUSDC.
  • Confidential transfer sends a confidential token from one address to another. The amount stays encrypted onchain.
  • Unshield converts a confidential token back into its public token.

Prerequisites

RequirementWhere to set it up
A wallet on a supported networkUtila console
A Transaction Policy that allows activations, shields and transfersManage transaction policy
Authenticated API access to the vaultSee Authentication and Creating a Service Account. VIEWER is sufficient for read-only balance and transaction monitoring.
Configured approvers and signersFollow the vault's Transaction Policy. Use human signers or a Utila Co-Signer as appropriate.
ETH for onchain gasFund the source wallet for shielding, unshielding, and confidential transfers. Activation is an offchain signature and costs no gas.

Flow

  1. Find the confidential tokens on the network.
  2. Check the activation of the wallet.
  3. Activate the wallet if needed.
  4. Read the balances.
  5. Shield a public token if needed.
  6. Send a confidential transfer.
  7. Unshield a confidential token if needed.

Utila tracks activation, shielding and confidential transfers through its standard transaction workflow. See Transaction tracking to follow their progress.

Start with the path that matches your funds. If the wallet already holds confidential tokens, skip Shield. To receive confidential tokens from another wallet, use Receive confidential tokens; the receiving wallet does not need to shield them first.

1. Find the confidential tokens

List the pairs on the network. See ListERC7984ConfidentialTokens.

GET /v2/networks/ethereum-mainnet/erc7984ConfidentialTokens
{
  "confidentialTokens": [
    {
      "confidentialToken": "assets/erc7984.ethereum-mainnet.0xe978F22157048E5DB8E5d07971376e86671672B2",
      "publicToken": "assets/erc20.ethereum-mainnet.0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
      "provider": "ZAMA",
      "network": "networks/ethereum-mainnet"
    }
  ]
}

Use the confidentialToken value as the asset name in the next steps.

📘

Note

The token identifiers in this guide are illustrative. Use the current values returned by this endpoint for your integration.

2. Check the activation

Get the tokens that the wallet is activated for. See GetEVMZamaConfidentialActivation.

GET /v2/vaults/{vault_id}/wallets/{wallet_id}:getEvmZamaConfidentialActivation?network=networks/ethereum-mainnet
{
  "activatedTokens": [
    {
      "confidentialToken": "assets/erc7984.ethereum-mainnet.0xe978F22157048E5DB8E5d07971376e86671672B2",
      "expireTime": "2027-10-19T19:28:54Z"
    }
  ],
  "pendingTransactions": []
}
  • If a token is not in activatedTokens, the wallet is not activated for that token, or the activation expired.
  • If a token has no expireTime, the activation is still in progress.
  • pendingTransactions lists the activation transactions that are not complete.

3. Activate the wallet

Activate the wallet for one or more confidential tokens. A new activation also renews the existing ones.

POST /v2/vaults/{vault_id}/transactions:initiate
{
  "details": {
    "evmZamaConfidentialActivation": {
      "wallet": "vaults/{vault_id}/wallets/{wallet_id}",
      "network": "networks/ethereum-mainnet",
      "confidentialTokens": [
        "assets/erc7984.ethereum-mainnet.0xe978F22157048E5DB8E5d07971376e86671672B2"
      ]
    }
  }
}

The activation is an offchain signature. It costs no gas and is valid for 365 days. One signature covers a maximum of 10 tokens. If you activate more tokens, Utila asks for more than one signature.

🚧

Renew before expiry

Activate again before expireTime. After the activation expires, Utila cannot decrypt new values for that token.

After signing, Utila fetches and decrypts the wallet's confidential balances, which might take a few seconds.

4. Read the balances

Query the wallet balances. See QueryWalletBalances.

POST /v2/vaults/{vault_id}/wallets/{wallet_id}:queryBalances
{ "filter": "network(\"networks/ethereum-mainnet\")" }

Four fields tell you whether a value is decrypted:

FieldIf true
walletBalance.unknownValueUtila has not decrypted this balance; value and rawValue are "0" placeholders. Check activation for this wallet/token. Activate or renew if missing or expired; if active, check for pending or failed decryption.
balance.incompleteValueThe total leaves out one or more balances that Utila cannot decrypt.
wallet.incompleteValueThe converted value of the wallet leaves out one or more balances that Utila cannot decrypt.
transfer.unknownAmountUtila cannot decrypt the amount of this transfer.
❗️

Important

Do not read "0" as an empty balance if unknownValue is true.

5. Shield a public token

Convert a public token into its confidential token. The wallet must hold the public token and gas. Send these details to transactions:initiate, as in step 3.

{
  "details": {
    "evmZamaConfidentialShield": {
      "source": "vaults/{vault_id}/wallets/{wallet_id}",
      "asset": "assets/erc7984.ethereum-mainnet.0xe978F22157048E5DB8E5d07971376e86671672B2",
      "amount": "1.5"
    }
  }
}
  • asset is the confidential token. Utila spends the public token of the same pair.
  • amount is in units of the public token.
  • The shield amount is public onchain. Only the confidential balance after the shield is encrypted.

Utila sends one EIP-7702 transaction that approves and wraps the public token. The bundle can also contain an EVM_ACCOUNT_DELEGATION transaction. Sign all transactions in the bundle.

6. Send a confidential transfer

Use assetTransfer with the confidential token as the asset. See Asset Transfer.

The destination field also accepts a wallet resource name (vaults/{vault_id}/wallets/{wallet_id}) or a specific wallet-address resource name (vaults/{vault_id}/wallets/{wallet_id}/addresses/{address_id}). The JSON below uses a raw Ethereum address.

Replace {destination_address} with the recipient's full Ethereum address on the same network before submitting the request.

{
  "details": {
    "assetTransfer": {
      "asset": "assets/erc7984.ethereum-mainnet.0xe978F22157048E5DB8E5d07971376e86671672B2",
      "amount": "0.5",
      "source": "vaults/{vault_id}/wallets/{wallet_id}",
      "destination": "{destination_address}"
    }
  }
}

Utila encrypts the amount before it sends the transaction. Onchain, the transfer event shows only an encrypted handle.

❗️

Important

Check the decrypted balance before you send. If the amount is more than the balance, the token contract moves 0 and the transaction still succeeds onchain. Utila marks this transfer as Failed. validateOnly does not check the balance.

  • The amount must fit the decimals of the confidential token. Zama confidential tokens use 6 decimals.
  • The recipient sees the amount in Utila only if the recipient wallet is activated for the token.

7. Unshield

Convert a confidential token back into its public token. The wallet must hold the confidential token and gas. Send these details to transactions:initiate, as in step 3.

{
  "details": {
    "evmZamaConfidentialUnshield": {
      "source": "vaults/{vault_id}/wallets/{wallet_id}",
      "asset": "assets/erc7984.ethereum-mainnet.0xe978F22157048E5DB8E5d07971376e86671672B2",
      "amount": "0.5"
    }
  }
}
  • asset is the confidential token. Utila returns the public token of the same pair to the source wallet.
  • amount is in units of the confidential token.
  • The unshielded amount is public onchain when the public token is released.

An unshield needs two onchain transactions, but you make only one API call. Utila sends the unwrap transaction, waits for the decryption proof, and then creates and signs the finalize transaction for you. Both transactions have subType UNSHIELD. The public token arrives only after the finalize transaction is confirmed.

❗️

Important

Check the decrypted balance before you unshield. As with transfers, the API accepts an amount that is more than the balance, and validateOnly does not check the balance.

Receive confidential tokens

A wallet can receive a supported confidential token at its Ethereum address before Utila activation. Receiving tokens and granting Utila permission to decrypt their values are separate operations.

  1. Share the receiving wallet's Ethereum address on the correct network.
  2. Use Accept inbound deposits to detect and track the incoming transaction. Fetch it with GetTransaction and check direction = INCOMING and its confirmation state. Also check transfers[].unknownAmount: when true, the amount has not been decrypted and must not be treated as zero. For wallet balances, check unknownValue, as described in Read the balances.
  3. Check activation for the receiving wallet and confidential token. Activate or renew if needed; wait for a future expireTime.
  4. Re-fetch the transaction and balances. Treat the amount as known only when unknownAmount is false, and the balance as known only when unknownValue is false.
🚧

Confirmation is not decryption

Confirmation establishes onchain progress, not decryption readiness. Do not use an unknown amount or a zero placeholder for crediting or reconciliation.

Transaction tracking

Track confidential transactions like other transactions. See Accept inbound deposits for webhooks, polling and transaction states. To find each step, use the subType:

StepsubType
ActivationEVM_ZAMA_CONFIDENTIAL_TOKEN_ACTIVATION
ShieldSHIELD
Confidential transferTOKEN_TRANSFER
UnshieldUNSHIELD

Keep the transaction resource name returned by transactions:initiate. The example below illustrates a confidential transfer response with other fields omitted; the state shown is not guaranteed to be the first state.

{
  "transaction": {
    "name": "vaults/{vault_id}/transactions/{transaction_id}",
    "subType": "TOKEN_TRANSFER",
    "state": "AWAITING_POLICY_CHECK"
  }
}

For bundled operations, retain and follow every transaction returned, including any delegation transaction that needs signing.

Fetch the latest record using GetTransaction:

GET /v2/vaults/{vault_id}/transactions/{transaction_id}

Use the returned state to distinguish policy checks, approval and signature steps from publication and confirmation. A transaction waiting for approvals or signatures has not yet been sent onchain. Follow the vault's configured approval and signing workflow, then continue tracking the same transaction.

After an onchain transaction is CONFIRMED, check transfers[].unknownAmount before reading transfers[].amount. If unknownAmount is true, the amount is unavailable, even if it is returned as "0". Recheck activation and decryption instead of treating it as a zero-value transfer.

Activation is offchain: establish readiness from GetEVMZamaConfidentialActivation, not blockchain confirmations.

Safe retries

For transaction initiation, set requestId to a new, non-zero UUID for each distinct operation. Retry an uncertain submission with the same requestId and the same request. Utila guarantees deduplication for at least 60 minutes after the first request. Once you have the transaction resource name, track it rather than initiating another transfer because confirmation is slow. See InitiateTransaction.

Troubleshooting

Check the relevant wallet, token and transaction before retrying.

SymptomCheckNext action
Balance or amount is unknownunknownValue / unknownAmount; activation and expiry for the relevant wallet/token.Activate or renew only if needed. If already active, re-query after decryption and investigate persistent failures with Utila. Do not treat the placeholder as zero.
Activation remains pendingpendingTransactions, missing expireTime, and outstanding approvals or signatures.Complete the required approvals and signatures, then repeat the activation lookup. Do not submit repeated activations solely because decryption is delayed.
Policy denialThe vault's Transaction Policy and any rejection details returned.Review the denied action with the vault administrator. Correct the policy or request before retrying.
Awaiting signaturesThe transaction state and outstanding signers for every transaction in the bundle.Complete every required signature through the configured signer or Co-Signer. Keep tracking the same transaction.
Transfer marked Failed in Utila despite a successful onchain transactionThe decrypted transfer amount (unknownAmount = false) and whether the requested amount exceeded the available balance.An insufficient-balance transfer can succeed onchain without moving tokens. Utila marks this as Failed. Check the available decrypted balance before trying again.