Skip to content

Migration Guide: DESILO FHE 1.x to 2.0

DESILO FHE 2.0 introduces several breaking changes to its API, supported configurations, and serialization format.

This guide explains the changes required to migrate existing applications from DESILO FHE 1.x to 2.0. For a complete overview of new features and performance improvements, see the release notes.

1. Update Engine Construction

All arguments to the Engine constructor are now keyword-only. Additionally, two arguments have been renamed:

1.x 2.0
use_bootstrap bootstrap
use_multiparty multiparty

Before:

from desilofhe import Engine

engine = Engine("gpu", use_bootstrap=True)

After:

from desilofhe import Engine

engine = Engine(mode="gpu", bootstrap=True)

The same change applies to multiparty configurations:

engine = Engine(mode="gpu", multiparty=True)

Creating an engine without arguments is still supported:

engine = Engine()

The default configuration is a CKKS engine with seven multiplicative levels.

2. Update Rotation and Roll Operations

DESILO FHE 2.0 distinguishes between roll and rotate:

  • roll shifts elements to the right.
  • rotate shifts elements to the left.

In previous versions, rotate used the direction now associated with roll. To preserve the behavior of existing code, replace rotate with roll. Additionally, the argument representing the shift amount has been renamed from delta to shift across all roll-related functions.

Before:

rotated = engine.rotate(ciphertext, rotation_key, delta=1)

After:

rolled = engine.roll(ciphertext, roll_key, shift=1)

The corresponding functions, keys, and arguments have changed as follows:

1.x 2.0
rotate roll
rotate_many roll_many
create_rotation_key create_roll_key
create_fixed_rotation_key create_fixed_roll_key
delta shift
Rotation key Roll key
Fixed rotation key Fixed roll key

The delta to shift rename applies to all roll-related functions, including key creation and operations that accept multiple shift amounts. Code already using roll, introduced in version 1.15, does not require a change in shift direction.

Creating Roll Keys

Use the new roll key creation functions:

secret_key = engine.create_secret_key()

roll_key = engine.create_roll_key(secret_key)
fixed_roll_key = engine.create_fixed_roll_key(secret_key, shift=1)

Fixed roll keys are supported by both CKKS and GL.

For GL, a fixed roll key requires an axis:

fixed_roll_key = engine.create_fixed_roll_key(secret_key, shift=1, axis=0)

For CKKS, the axis property is None.

The level argument must now be passed by keyword:

fixed_roll_key = engine.create_fixed_roll_key(secret_key, shift=1, level=2)

This avoids ambiguity between shift, axis, and level.

Reusing Bootstrap Keys

Bootstrap keys can now be used directly with roll, roll_many, and rotate. If your application already uses bootstrapping, you may be able to eliminate separate roll keys and reduce memory usage.

3. Update Evaluation Keys

DESILO FHE 2.0 introduces a unified Evaluation Key that can be used for operations requiring evaluation keys. Previously, some operations, particularly bootstrapping, required multiple separate keys. The Evaluation Key simplifies key management by combining the keys required for evaluation. Encryption and decryption still use their respective keys. When migrating existing code, consider using an Evaluation Key instead of passing multiple individual evaluation keys.

4. Update GL Multiplication

The GL Hadamard multiplication API has been renamed to match CKKS.

1.x 2.0
hadamard_multiply multiply
Hadamard multiplication key Relinearization key

Before:

result = engine.hadamard_multiply(
    ciphertext1, ciphertext2, hadamard_multiplication_key
)

After:

result = engine.multiply(ciphertext1, ciphertext2, relinearization_key)

GL multiplication can now also be performed without relinearization. The resulting ciphertext contains three polynomials rather than two and can be decrypted directly. This can eliminate unnecessary relinearization overhead when no subsequent operation requires a relinearized ciphertext. As of 2.0.0, the only operation available for a ciphertext with three polynomials is decryption, but more operations will be supported in the future.

5. Update Bootstrapping Configurations

DESILO FHE 2.0 supports only 17-level bootstrapping.

The following configurations and features are no longer supported:

1.x 2.0
Other regular bootstrap variants Use 17-level bootstrapping
Lossy bootstrapping Use regular bootstrapping
Sign bootstrapping No direct replacement
Large bootstrap keys Use the supported bootstrap key
Custom bootstrap stage counts Use the default configuration

The mod_raise function and secret keys with custom secret values are deprecated. These features were intended for custom bootstrapping, which is no longer supported by the modulus configuration used for 17-level bootstrapping. Applications using custom bootstrapping pipelines must be redesigned to use the supported bootstrapping configuration.

6. Update CKKS Parameters

CKKS configurations with 32,768 slots are no longer supported. These configurations required excessively large keys and suffered from significant encoding and decoding errors at low levels. If your application uses 32,768 slots, migrate to a supported CKKS configuration. Applications requiring more than the 36 multiplicative levels provided by the largest supported CKKS engine should use a bootstrap-enabled engine.

Custom configuration of the logarithm of the polynomial coefficient count and the number of special primes is also no longer supported. Use the predefined engine configurations instead.

7. Update GL Shapes

GL shapes with an innermost dimension 256 and larger are no longer supported. Applications using these shapes must select a supported configuration.

DESILO FHE 2.0 also introduces batch counts of 162 and 486, which may provide additional options when selecting a GL shape. For the complete list of supported GL shapes and maximum levels, see supported shapes.

8. Migrate Matrix Multiplication and Sparse Encoding

CKKS matrix multiplication and sparse encoding are no longer supported. Applications relying on these features require changes to their computation pipelines.

Depending on the workload, possible alternatives include:

  • Implementing CKKS matrix multiplication using efficient packing techniques with ciphertext rotations and multiplications.
  • Migrating suitable matrix-oriented computations to GL.

Note that GL shapes may be too large for some small-scale applications. Additional examples or library functionality for CKKS matrix multiplication are planned for future releases. There is no direct API replacement for the removed CKKS matrix multiplication and sparse encoding features.

9. Update CUDA Environments

DESILO FHE 2.0 supports only CUDA 13.2 and CUDA 13.4. Applications using older CUDA toolchains must update their build and runtime environments.

In particular, CUDA 13.0 is no longer supported because of a compiler bug involving nested thread divergence that can silently produce incorrect results. The issue was introduced in CUDA 12.8 and fixed in CUDA 13.2.2. Although this issue has not been observed in DESILO FHE, support for affected CUDA versions has been removed as a preventive measure.

When upgrading, verify that the installed NVIDIA driver is compatible with the selected CUDA version.

10. Migrate Serialized Data and Keys

DESILO FHE 2.0 uses a completely redesigned serialization format.

Serialized data and keys from previous versions are not compatible with 2.0.

You must regenerate any data and keys required by your application.

A recommended migration procedure is:

  1. Use the previous library version to deserialize existing data.
  2. Recover the original plaintext data where possible.
  3. Upgrade to DESILO FHE 2.0.
  4. Generate new keys using the updated engine configuration.
  5. Re-encode and re-encrypt the original data.
  6. Serialize the new data and keys using DESILO FHE 2.0.

If the original plaintext is unavailable, migration may require access to the appropriate secret keys and the previous library version. Direct conversion between the old and new serialization formats is not supported.

Migration Checklist

Before deploying an application with DESILO FHE 2.0, verify the following:

  • [ ] All Engine constructor arguments use keywords.
  • [ ] use_bootstrap and use_multiparty have been renamed.
  • [ ] Existing rotate calls have been reviewed and changed to roll where necessary.
  • [ ] Rotation keys have been migrated to roll keys.
  • [ ] Fixed rotation keys have been migrated to fixed roll keys.
  • [ ] Fixed roll key creation uses keyword arguments for level.
  • [ ] The delta argument has been renamed to shift in all roll-related functions.
  • [ ] GL hadamard_multiply calls have been replaced with multiply.
  • [ ] GL Hadamard multiplication keys have been replaced with relinearization keys.
  • [ ] Bootstrapping uses the 17-level configuration.
  • [ ] Removed CKKS matrix multiplication and sparse encoding features are no longer used.
  • [ ] CKKS and GL configurations use supported shapes and parameters.
  • [ ] CUDA environments use a supported version.
  • [ ] Previously serialized data and keys have been migrated.
  • [ ] Application tests have been re-run to verify numerical accuracy and correctness.

For additional information about the changes introduced in DESILO FHE 2.0, see the release notes.