# ZK Circuit Registry

***

### Core Circuits

These circuits are hardcoded in the bootloader (highest trust level):

#### BOOT\_AUTHORITY Circuit

```
Name:         BOOT_AUTHORITY
Category:     Core
Permissions:  BootAuthority, Attestation

Program Hash: fa02d10e8804169a47233e34a6ff3566248958adff55e1248d50304aff4ab230
VK Hash:      bf6d8ae8b77c2c0bb9ee46c8a847dfba9114363738cb22f28703a6cd9451a584

Domain:       "NONOS:ZK:PROGRAM:v1"
```

#### UPDATE\_AUTHORITY Circuit

```
Name:         UPDATE_AUTHORITY
Category:     Core
Permissions:  UpdateAuthority

Program Hash: 8b3ca7195ef2710adc4592b86d33aa4f17e9285c447bf6913ace08d5621f73e4
VK Hash:      bf6d8ae8b77c2c0bb9ee46c8a847dfba9114363738cb22f28703a6cd9451a584

Domain:       "NONOS:ZK:PROGRAM:v1"
```

#### RECOVERY\_KEY Circuit

```
Name:         RECOVERY_KEY
Category:     Core
Permissions:  RecoveryKey

Program Hash: 2f9158c4a36bdd876e12149f5708ce13ab924670d5fa83c16ee7d954201bacf58
VK Hash:      bf6d8ae8b77c2c0bb9ee46c8a847dfba9114363738cb22f28703a6cd9451a584

Domain:       "NONOS:ZK:PROGRAM:v1"
```

***

### Verifying Key (VK)

The BOOT\_AUTHORITY verifying key (584 bytes, BLS12-381):

```hex
a15e3012b17588d8f3d7ac61afcf2a4d44edae7b1a3dff4f57acd2755858e5ec
0c0c05612fa339d8f68b83b73689c2c70a480f1a32161614f1ffef5c4a6836f1
93a83e7aee13ebb9aaca596ba93f8e1b7624c95757d3423ad671b714eee20ab5
e0c4e1363d4e4f5afed1b21cf4bd965fa7c583b5ad1ff1d8ba6daf1bb8863f9e
fb4389e04c1cb105efcb19097fc073ceadf7a99ad8e718a2c4046...
(584 bytes total, truncated for display)
```

***

### Permission Flags

Each circuit has a permission bitmap:

| Permission       | Bit | Hex Value    |
| ---------------- | --- | ------------ |
| BootAuthority    | 0   | `0x00000001` |
| UpdateAuthority  | 1   | `0x00000002` |
| RecoveryKey      | 2   | `0x00000004` |
| CommunityKey     | 3   | `0x00000008` |
| UserCircuit      | 4   | `0x00000010` |
| Attestation      | 5   | `0x00000020` |
| CircuitAdmin     | 6   | `0x00000040` |
| NetworkAccess    | 7   | `0x00000080` |
| FilesystemAccess | 8   | `0x00000100` |
| HardwareAccess   | 9   | `0x00000200` |

***

### Circuit Categories

| Category  | Trust Level | Source                   | Can Modify             |
| --------- | ----------- | ------------------------ | ---------------------- |
| Core      | Highest     | Compiled into bootloader | Bootloader update only |
| System    | High        | Signed ELF sections      | Kernel update          |
| Community | Medium      | N-of-M multisig          | Governance vote        |
| User      | Sandboxed   | User-installed           | User action            |

***

### Section Magic

ZK circuit sections are identified by magic bytes:

```
Magic: 0x4E 0xC3 0x5A 0x4B
ASCII: "NØZK"
```

### `Groth16 Proof Format`

| Component | Size          | Description           |
| --------- | ------------- | --------------------- |
| A         | 48 bytes      | G1 point (compressed) |
| B         | 96 bytes      | G2 point (compressed) |
| C         | 48 bytes      | G1 point (compressed) |
| **Total** | **192 bytes** | Complete proof        |

### `Proof Limits`

| Limit             | Value  |
| ----------------- | ------ |
| Max Public Inputs | 256 KB |
| Max Proof Size    | 2 MB   |
| Verification Time | \~5 ms |

### `Domain Separators`

| Domain                        | Purpose                    |
| ----------------------------- | -------------------------- |
| `NONOS:ZK:PROGRAM:v1`         | Program hash derivation    |
| `NONOS:CIRCUIT_KEY:v1`        | Circuit key derivation     |
| `NONOS:CAPSULE:COMMITMENT:v1` | Default commitment binding |

### `Hash Derivation`

Program hashes are derived using BLAKE3:

```rust
let program_hash = blake3::derive_key(
    "NONOS:ZK:PROGRAM:v1",
    &circuit_definition_bytes
);
```

***

### Capsule Metadata

ZK proofs are wrapped in capsules:

```rust
CapsuleMetadata {
    offset_sig: usize,
    len_sig: usize,
    offset_payload: usize,
    len_payload: usize,
    signer_keyid: Option<[u8; 32]>,
    payload_hash: [u8; 32],
    header_version: u32,
    header_timestamp: u64,
}
```

### Verification Flow

```
1. Extract proof from capsule
2. Look up circuit by program_hash
3. Verify circuit has required permissions
4. Deserialize proof (A, B, C points)
5. Compute public input commitment
6. Verify: e(A,B) = e(α,β) · e(L,γ) · e(C,δ)
7. Return VALID or INVALID
```

***

### Adding New Circuits

#### `System Circuit`

1. Define circuit constraints
2. Run trusted setup ceremony
3. Compute program hash
4. Embed VK in kernel
5. Register in SYSTEM\_CIRCUITS

#### `Community Circuit`

1. Define circuit and run setup
2. Submit to governance
3. Collect N-of-M signatures
4. Register via community process

#### `User Circuit`

1. Define circuit locally
2. Run setup locally
3. Install via user API
4. Runs sandboxed (limited permissions)

***

### Circuit Tools

| Tool                | Location                                     | Purpose             |
| ------------------- | -------------------------------------------- | ------------------- |
| zk-embed            | `nonos-boot/tools/zk-embed`                  | Embed VK in binary  |
| zk-ceremony         | `nonos-boot/tools/zk-ceremony`               | MPC setup           |
| attestation-circuit | `nonos-boot/tools/nonos-attestation-circuit` | Attestation circuit |