# HEIR: Homomorphic Encryption Intermediate Representation

![GitHub Workflow Status (with event)](https://img.shields.io/github/actions/workflow/status/google/heir/build_and_test.yml)
![GitHub Contributors](https://img.shields.io/github/contributors/google/heir)
![GitHub Discussions](https://img.shields.io/github/discussions/google/heir)
![GitHub License](https://img.shields.io/github/license/google/heir)
[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/google/heir/badge)](https://securityscorecards.dev/viewer/?uri=github.com/google/heir)

An MLIR-based toolchain for
[homomorphic encryption](https://en.wikipedia.org/wiki/Homomorphic_encryption)
compilers. Read the docs at [the HEIR website](https://heir.dev).

For more information on MLIR, see the [MLIR homepage](https://mlir.llvm.org/).

## Quickstart (Python)

Pip install the `heir_py` package

```bash
pip install heir_py
```

Then run an example:

```python
from heir import compile
from heir.mlir import I64, Secret

@compile()  # defaults to scheme="bgv", OpenFHE backend, and debug=False
def func(x: Secret[I64], y: Secret[I64]):
    sum = x + y
    diff = x - y
    mul = x * y
    expression = sum * diff + mul
    deadcode = expression * mul
    return expression

func.setup()
enc_x = func.encrypt_x(7)
enc_y = func.encrypt_y(8)
result_enc = func.eval(enc_x, enc_y)
result = func.decrypt_result(result_enc)

print(
  f"Expected result for `func`: {func.original(7,8)}, FHE result:"
  f" {result}"
)
```

This will compile the function above using the BGV scheme to machine code via
the [OpenFHE](https://openfhe-development.readthedocs.io/en/latest/) backend.
Then calling the function will encrypt the inputs, run the function, and return
the decrypted result. The function call `foo(7, 8)` runs the entire
encrypt-run-decrypt flow for ease of testing.

## Building from source

This project uses `bazel` for its build system. Install
[bazelisk](https://github.com/bazelbuild/bazelisk) to manage the bazel version
automatically. Then, with `bazel` on your path (pointing to `bazelisk`), run the
following to build the main pass-running tool.

```bash
bazel build //tools:heir-opt
```

Or run an end-to-end test like

```bash
bazel test //tests/Examples/openfhe/ckks/halevi_shoup_matvec:all
```

HEIR depends on LLVM (from source) so a clean build may take 30 minutes
depending on your machine. For faster builds, use
[BuildBuddy](https://www.buildbuddy.io/). Sign up for an account, create an API
key, and add the following to `.bazelrc.user` in the root of the HEIR workspace:

```
common --remote_header=x-buildbuddy-api-key=<YOUR_API_KEY>
common --config=remote
```

This should reduce a clean build time to about 5 minutes.

See the [bazel tips](https://heir.dev/docs/development/bazel/) page for more
example commands and tips on using bazel.

## Supported backends and schemes

| Backend Library | BGV | BFV | CKKS | CGGI |
| --------------- | --- | --- | ---- | ---- |
| OpenFHE         | ✅  | ✅  | ✅   | ❌   |
| Lattigo         | ✅  | ✅  | ✅   | ❌   |
| tfhe-rs         | ❌  | ❌  | ❌   | ✅   |
| Jaxite          | ❌  | ❌  | ❌   | ✅   |

Note some backends do not support all schemes.

## Contributing

There are many ways to contribute to HEIR:

- Come to our [monthly meetings](https://heir.dev/community/) to discuss active
  work on HEIR and future project directions. The meetings are recorded and
  posted to our [blog](https://heir.dev/blog/) and
  [YouTube channel](https://www.youtube.com/@HEIRCompiler).
- Come to our [weekly office hours](https://heir.dev/community/) for informal
  discussions and debugging help.
- Ask questions or discuss feature ideas in the `#heir` channel on
  [the FHE.org discord](https://discord.fhe.org/).
- Work on an issue marked
  ["good first issue"](https://github.com/google/heir/contribute) or browse
  issues [labeled by topic](https://github.com/google/heir/labels).
- Help us understand new FHE research: either
  - Read a paper tagged under
    [research synthesis](https://github.com/google/heir/labels/research%20synthesis)
    and summarize the novel techniques that could be ported to HEIR.
  - File new issues under
    [research synthesis](https://github.com/google/heir/labels/research%20synthesis)
    to alert us of papers that should be investigated and incorporated into
    HEIR.

## Citations

The HEIR project can be cited in academic work through the following entry:

```text
@misc{ali2025heir,
      title={HEIR: A Universal Compiler for Homomorphic Encryption},
      author={Asra Ali and Jaeho Choi and Bryant Gipson and Shruthi Gorantala
              and Jeremy Kun and Wouter Legiest and Lawrence Lim and Alexander
              Viand and Meron Zerihun Demissie and Hongren Zheng},
      year={2025},
      eprint={2508.11095},
      archivePrefix={arXiv},
      primaryClass={cs.CR},
      url={https://arxiv.org/abs/2508.11095},
}
```

## Support disclaimer

This is not an officially supported Google product.

<!-- mdformat global-off -->
