HandleLifecycle

Category: Basic | Difficulty: Intermediate | Chapters: Handles | Concept: Store encrypted handles and reuse them across calls

Show how encrypted handles can be stored and reused safely.

Why this example

This example focuses on Store encrypted handles and reuse them across calls. It is designed to be self-contained and easy to run locally.

Quick start

npm install
npm run test:mocked -- test/basic/HandleLifecycle.test.ts

Dependencies

None

Contract and test

HandleLifecycle.sol

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.27;

import {FHE, euint64, externalEuint64} from "@fhevm/solidity/lib/FHE.sol";
import {ZamaEthereumConfig} from "@fhevm/solidity/config/ZamaConfig.sol";

/**
 * @title HandleLifecycle
 * @author Gustavo Valverde
 * @notice Show how encrypted handles can be stored and reused safely.
 * @dev Example for fhEVM Examples - Basic Category
 *
 * @custom:category basic
 * @custom:chapter handles
 * @custom:concept Store encrypted handles and reuse them across calls
 * @custom:difficulty intermediate
 */
contract HandleLifecycle is ZamaEthereumConfig {
    mapping(address user => euint64 value) private storedValues;

    /// @notice Store an encrypted value for the sender.
    /// @param encValue Encrypted value handle
    /// @param inputProof Proof for the encrypted input
    function storeValue(externalEuint64 encValue, bytes calldata inputProof) external {
        euint64 value = FHE.fromExternal(encValue, inputProof);
        storedValues[msg.sender] = value;
        FHE.allowThis(value);
        FHE.allow(value, msg.sender);
    }

    /// @notice Add an encrypted value to the stored handle.
    /// @param encValue Encrypted value handle
    /// @param inputProof Proof for the encrypted input
    function addToStored(externalEuint64 encValue, bytes calldata inputProof) external {
        euint64 value = FHE.fromExternal(encValue, inputProof);
        euint64 updated = FHE.add(storedValues[msg.sender], value);
        storedValues[msg.sender] = updated;
        FHE.allowThis(updated);
        FHE.allow(updated, msg.sender);
    }

    /// @notice Retrieve the stored encrypted value.
    /// @param user Account holding the encrypted value
    /// @return The stored encrypted value
    function getStoredValue(address user) external view returns (euint64) {
        return storedValues[user];
    }
}

HandleLifecycle.test.ts

Pitfalls to avoid

No pitfalls are highlighted in the tests for this example.

API Reference

Overview

Show how encrypted handles can be stored and reused safely.

Developer Notes

Example for fhEVM Examples - Basic Category

storeValue

function storeValue(externalEuint64 encValue, bytes inputProof) external

Store an encrypted value for the sender.

Parameters

Name	Type	Description
encValue	externalEuint64	Encrypted value handle
inputProof	bytes	Proof for the encrypted input

addToStored

function addToStored(externalEuint64 encValue, bytes inputProof) external

Add an encrypted value to the stored handle.

Parameters

Name	Type	Description
encValue	externalEuint64	Encrypted value handle
inputProof	bytes	Proof for the encrypted input

getStoredValue

function getStoredValue(address user) external view returns (euint64)

Retrieve the stored encrypted value.

Parameters

Name	Type	Description
user	address	Account holding the encrypted value

Return Values

Name	Type	Description
[0]	euint64	The stored encrypted value