# gmucerg/dilithium architecture

> Architecture diagram of the GitHub repository gmucerg/dilithium, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/gmucerg/dilithium
- Repository: https://github.com/gmucerg/dilithium

## Overview

This repository is an FPGA implementation of CRYSTALS-Dilithium supporting key generation, signing, and verification at security levels 2, 3, and 5. Its principal workflow is an operation request to the `combined_top` hardware, which produces the corresponding key or signature result. The RTL tree identifies supporting hashing, sampling, polynomial, and NTT components, but their wiring is not shown in the sampled source, so those connections are omitted. `dilithium-256` provides a separate NTT-2x2 implementation and reference model; its relationship to the top-level RTL is not established by the available evidence.

Main entry points: [`rtl_src/combined_top.v`](https://github.com/gmucerg/dilithium/blob/master/rtl_src/combined_top.v) (Keygen sign verify)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_top["Top-level operations"]
  node_topmod["Keygen sign verify<br/>[combined_top.v]"]
  node_operation["Operation control<br/>[operation_module.v]"]
end

subgraph group_crypto["Crypto primitives"]
  node_keccak["Keccak engine<br/>[keccak_top.vhd]"]
  node_sha3["SHA3 control<br/>[sha3_fsm3.vhd]"]
  node_samplers["Secret sampling<br/>[sampler_s.v]"]
  node_matrix["Matrix sampling<br/>[sampler_a_ext.v]"]
  node_mask["Mask sampling<br/>[sampler_y_ext.v]"]
end

subgraph group_poly["Polynomial hardware"]
  node_polyops["Coefficient operations<br/>[coeff_decomposer.v]"]
  node_hints["Hint processing<br/>[makehint.v]"]
  node_norm["Norm checking<br/>[norm_check.v]"]
end

subgraph group_ntt["NTT models"]
  node_butterfly["Butterfly arithmetic<br/>[butterfly2x2.v]"]
  node_ram[("Coefficient memory<br/>[dual_port_ram.v]")]
  node_swntt["Reference NTT<br/>[ref_ntt.cpp]"]
  node_ntt2x2["NTT-2x2 model<br/>[ntt2x2_fwdntt.cpp]"]
end

node_operator(("Operation requester"))
node_result["Key or signature result"]

node_operator -->|"requests operation"| node_topmod
node_topmod -->|"produces result"| node_result

click node_topmod "https://github.com/gmucerg/dilithium/blob/master/rtl_src/combined_top.v"
click node_operation "https://github.com/gmucerg/dilithium/blob/master/rtl_src/operation_module.v"
click node_keccak "https://github.com/gmucerg/dilithium/blob/master/rtl_src/keccak_top.vhd"
click node_sha3 "https://github.com/gmucerg/dilithium/blob/master/rtl_src/sha3_fsm3.vhd"
click node_samplers "https://github.com/gmucerg/dilithium/blob/master/rtl_src/sampler_s.v"
click node_matrix "https://github.com/gmucerg/dilithium/blob/master/rtl_src/sampler_a_ext.v"
click node_mask "https://github.com/gmucerg/dilithium/blob/master/rtl_src/sampler_y_ext.v"
click node_polyops "https://github.com/gmucerg/dilithium/blob/master/rtl_src/coeff_decomposer.v"
click node_hints "https://github.com/gmucerg/dilithium/blob/master/rtl_src/makehint.v"
click node_norm "https://github.com/gmucerg/dilithium/blob/master/rtl_src/norm_check.v"
click node_butterfly "https://github.com/gmucerg/dilithium/blob/master/rtl_src/butterfly2x2.v"
click node_ram "https://github.com/gmucerg/dilithium/blob/master/rtl_src/dual_port_ram.v"
click node_swntt "https://github.com/gmucerg/dilithium/blob/master/dilithium-256/reference_code/ref_ntt.cpp"
click node_ntt2x2 "https://github.com/gmucerg/dilithium/blob/master/dilithium-256/hardware_code/ntt2x2_fwdntt.cpp"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_topmod,node_operation toneBlue
class node_keccak,node_sha3,node_samplers,node_matrix,node_mask toneAmber
class node_polyops,node_hints,node_norm,node_operator toneMint
class node_butterfly,node_ram,node_swntt,node_ntt2x2 toneRose
class node_result toneIndigo
```

## Components

### Top-level operations

- [Keygen sign verify](https://github.com/gmucerg/dilithium/blob/master/rtl_src/combined_top.v): `rtl_src/combined_top.v`
- [Operation control](https://github.com/gmucerg/dilithium/blob/master/rtl_src/operation_module.v): `rtl_src/operation_module.v`

### Crypto primitives

- [Keccak engine](https://github.com/gmucerg/dilithium/blob/master/rtl_src/keccak_top.vhd): `rtl_src/keccak_top.vhd`
- [SHA3 control](https://github.com/gmucerg/dilithium/blob/master/rtl_src/sha3_fsm3.vhd): `rtl_src/sha3_fsm3.vhd`
- [Secret sampling](https://github.com/gmucerg/dilithium/blob/master/rtl_src/sampler_s.v): `rtl_src/sampler_s.v`
- [Matrix sampling](https://github.com/gmucerg/dilithium/blob/master/rtl_src/sampler_a_ext.v): `rtl_src/sampler_a_ext.v`
- [Mask sampling](https://github.com/gmucerg/dilithium/blob/master/rtl_src/sampler_y_ext.v): `rtl_src/sampler_y_ext.v`

### Polynomial hardware

- [Coefficient operations](https://github.com/gmucerg/dilithium/blob/master/rtl_src/coeff_decomposer.v): `rtl_src/coeff_decomposer.v`
- [Hint processing](https://github.com/gmucerg/dilithium/blob/master/rtl_src/makehint.v): `rtl_src/makehint.v`
- [Norm checking](https://github.com/gmucerg/dilithium/blob/master/rtl_src/norm_check.v): `rtl_src/norm_check.v`

### NTT models

- [Butterfly arithmetic](https://github.com/gmucerg/dilithium/blob/master/rtl_src/butterfly2x2.v): `rtl_src/butterfly2x2.v`
- [Coefficient memory](https://github.com/gmucerg/dilithium/blob/master/rtl_src/dual_port_ram.v): `rtl_src/dual_port_ram.v`
- [Reference NTT](https://github.com/gmucerg/dilithium/blob/master/dilithium-256/reference_code/ref_ntt.cpp): `dilithium-256/reference_code/ref_ntt.cpp`
- [NTT-2x2 model](https://github.com/gmucerg/dilithium/blob/master/dilithium-256/hardware_code/ntt2x2_fwdntt.cpp): `dilithium-256/hardware_code/ntt2x2_fwdntt.cpp`

### Other components

- **Operation requester**
- **Key or signature result**

## Connections

- Operation requester → Keygen sign verify: requests operation
- Keygen sign verify → Key or signature result: produces result