# Firefly Static Parser Architectural Specification & Cryptographic Deep Dive
This technical specification provides an exhaustive, code-level analysis of **`Firefly-Static-Parser`** (by AzenKain), an offline, static reverse-engineering framework and IL2CPP metadata extractor implemented in Rust. Unlike in-process dynamic dumpers (such as `honkai-dumper`), `Firefly-Static-Parser` operates **completely offline** without launching, injecting, or hooking into the game client process.
It achieves this by completely reverse-engineering the proprietary metadata container format (`MHY\0`), the embedded layout tables in `GameAssembly.dll`, dynamic semantic XOR key derivation, and non-linear mathematical scrambling algorithms used in *Honkai: Star Rail*.
---
## 1. Executive Summary & Architectural Paradigm
### 1.1 The Challenge of Custom IL2CPP Obfuscation
Standard Unity IL2CPP uses known, public data structures:
-`global-metadata.dat` begins with magic `0xFAB11BAF` (version 29+).
- Metadata definitions (TypeDef, MethodDef, FieldDef) are stored sequentially in unencrypted flat tables.
In *Honkai: Star Rail* and similar protected titles:
1.**Container Replaced**: `global-metadata.dat` begins with custom magic `MHY\0` (`0x0059484D`).
2.**Split Metadata**: Metadata ranges and image mappings are split between `global-metadata.dat` and `startup-metadata.dat`.
3.**Embedded PE Headers**: The true table offsets, sizes, and field layout descriptors are embedded inside `GameAssembly.dll` and encrypted with arithmetic displacements and bitwise XOR masks.
4.**Scrambled Field/Method Entries**: Entries are not sequential; attributes, indices, and names are encrypted with non-linear hash/PRNG functions unique to each table.
5.**Seeded Stream Cipher on Strings**: Type names and string literals are packed into bitfields and encrypted with a QWORD running stream cipher.
The project is structured in Rust (2024 Edition) with a modular pipeline separating PE analysis, metadata loading, mathematical key derivation, and AST emission.
Extracts `payload_offset` (typically `0x00` or file header length).
### 3.2 Decryption of Embedded Header Offsets
The table offsets in the embedded header are obfuscated using combinations of 32-bit XOR keys, bitwise arithmetic shifts (`sar_u32`), and wrapping modular additions.
```rust
// Discovered from embedded_header_rva in GameAssembly.dll
let descriptor_count_80 = image.read_u32_rva(descriptor_rva + 0x80)? ^ 0x69BD_97F1;
let header_size_1a8 = image.read_u32_rva(header + 0x1A8)? ^ 0x729B_1A9E;
let header_size_1f8 = image.read_u32_rva(header + 0x1F8)? ^ 0x1608_C2C8;
let header_size_74 = image.read_u32_rva(header + 0x74)? ^ 0x080E_F250;
let header_count_134 = (image.read_u32_rva(header + 0x134)? ^ 0x1021_0728) / 40;
let header_count_178 = sar_u32(image.read_u32_rva(header + 0x178)?, 4) ^ 0x05CC_1AE1;
let header_count_bc = sar_u32(image.read_u32_rva(header + 0xBC)?, 3) ^ 0x079F_C2EC;
```
#### Complete Table Offsets Mapping:
| Offset In Header | Operation | Key / Operand | Output Field in `StaticLayout` |
A major breakthrough in `Firefly-Static-Parser` is how it discovers runtime XOR keys and type sentinels **without hardcoding version-specific constants**.
### 4.1 The Semantic Invariant Technique
In every valid .NET/IL2CPP metadata image, standard CLI core types always exhibit known semantic invariants:
1. **TypeDef 0 is `<Module>`**:
- Has no base type $\rightarrow$ raw base value gives `type_base_none`.
- Has known attribute flags $\rightarrow$ `raw_flags ^ 0x700` reveals `type_attribute_key`.
2. **`System.ValueType`**:
- Inherits directly from `System.Object`. Therefore, the raw base type of `System.ValueType` reveals `type_base_object`.
3. **`System.Enum`**:
- Inherits directly from `System.ValueType`. Its raw base type reveals `type_base_value_type`.
4. **`System.AttributeTargets`**:
- Is an Enum. Its raw base type reveals `type_base_enum`.
$$K_{\text{gen\_container}}(i) = v_2 \text{ as u32}$$
---
## 6. Type System Reconstruction & Output Generation
### 6.1 Dynamic Table Resolution in `GameAssembly.dll`
In addition to metadata parsing, method RVAs require locating the compiled function pointers. In `src/layout_model/parser/loader.rs`:
- **`il2cpp_type_table`**: Scans `GameAssembly.dll` for continuous 16-byte descriptors where `kind` $\in (0, 0x50)$ and `byref` $\in \{0, 1, 0x80, 0x81\}$.
- **`method_pointer_table`**: Scans for continuous runs of 64-bit pointers residing within the `.text` segment ($ImageBase + 0x1000 \le VA < ImageBase + Size$).
- **`generic_inst_table`**: Scans for runs of `argc` ($0 < argc < 30$) with 32-bit zero padding and valid pointer prefixes (`0x01`, `0x00`, `0x7F`).
### 6.2 Output Formats
#### 1. Reconstructed C# Source (`dump.cs`)
Outputs complete class declarations with namespaces, type index comments, attributes, and field offsets:
1. `Firefly-Static-Parser` extracts the exact class structures and obfuscated field names (e.g., `KOIAJFFGPGF` $\rightarrow$ Wire tag `1` at offset `0x180`).
2. Engineers cross-reference these offsets with network serialization routines.
3. The resulting proto definitions with wire masks (`[get: (id ^ 1) + 2]`) and metadata (`meta uint32 cmd_id = 143;`) are compiled using **`FireflyProtoc`**.
### 8.2 Compliance with Repository Rules (`AGENTS.md`)
- `Firefly-Static-Parser` operates purely as an offline analysis tool.
- It contains no hardcoded user paths, machine IP addresses, or environment-dependent paths.
- It eliminates the need for prohibited live heartbeat scanning scripts in game client directories (`scripts/`), providing a 100% compliant and safe research workflow.
