bitchat/localPackages/Tor/Frameworks/BITCHAT_TOR.md

**BitChat Tor Build Notes**

- Date: See repo history for the commit you pulled
- Output: `tor-nolzma.xcframework` (static, C-only)
- Platforms: iOS device (arm64), iOS simulator (arm64), macOS (arm64)
- Goal: Minimize binary size while retaining client functionality

**Overview**
- We built a minimal Tor static xcframework with LZMA disabled to reduce size and complexity.
- The artifact contains only the C libraries (Tor + libevent + OpenSSL) and their headers. Objective‑C wrappers (`TORThread`, `TORController`, etc.) are not compiled into this minimal artifact to keep size down.
- This xcframework is suitable for iOS and macOS targets that link the Objective‑C wrappers as source (or use CocoaPods to bring them in).

**Component Versions**
- Tor: 0.4.8.21
- libevent: 2.1.12
- OpenSSL: 3.6.0
- liblzma: not linked (intentionally disabled)

**Build Environment**
- Xcode with iOS and macOS SDKs
- Homebrew tools: `autoconf`, `automake`, `libtool`, `gettext`
- Install prerequisites from repo root: `brew bundle`

**Command Used**
- Minimal build (nolzma), size-optimized: `./build-minimal.sh`
  - Build script located at: `~/Documents/vibe/Tor.framework-build/build-minimal.sh`
  - Uses iCepa/Tor.framework as base, with custom size optimizations
  - Outputs to: `~/Documents/vibe/Tor.framework-build/tor-nolzma.xcframework`

**What Minimal Mode Does**
- Targets: `iphoneos/arm64`, `iphonesimulator/arm64`, `macosx/arm64`.
- Disables LZMA in Tor (`--enable-lzma=no`) and removes zstd.
- Aggressive OpenSSL trimming (removes ~3MB per slice):
  - Protocol: `no-ssl3 no-tls1 no-tls1_1 no-dtls`
  - Legacy ciphers: `no-des no-rc2 no-rc4 no-rc5 no-idea no-seed no-camellia no-aria no-bf no-cast`
  - Unused hashes: `no-md4 no-mdc2 no-whirlpool no-rmd160`
  - Post-quantum: `no-ml-dsa no-ml-kem no-slh-dsa no-lms`
  - Chinese standards: `no-sm2 no-sm3 no-sm4`
  - Certificate features: `no-cms no-ts no-cmp no-ct no-rfc3779`
  - Other: `no-gost no-ec2m no-siphash no-scrypt no-legacy no-dso no-dgram no-http`
  - See build script for full list
- Tor client-only: `--disable-module-relay --disable-module-dirauth --disable-module-pow`
- Compiles with size-first flags: `-Os -ffunction-sections -fdata-sections`; bitcode is not embedded.
- Statically links Tor, libevent, and OpenSSL into a single library per slice inside the framework.
- Copies public headers from Tor/libevent/OpenSSL into the framework `Headers` directory.

**Resulting Slices (approx sizes)**
- Folder size: ~67 MB (`tor-nolzma.xcframework`)
- Binaries (non-fat, measured on this build):
  - iOS arm64 (device): ~14 MB
  - iOS arm64 (simulator): ~13.8 MB
  - macOS arm64: ~13.8 MB

Note: Sizes vary slightly by Xcode/SDK versions and environment.

**Integrating in BitChat**
- Add `tor-nolzma.xcframework` to your app target(s). Xcode will select the correct slice for device/simulator/macOS.
- Link `libz.tbd` (Tor depends on zlib).
- Keep app link-time stripping enabled for best results:
  - Other Linker Flags: add `-dead_strip`
  - Avoid `-ObjC` if possible (prevents dead stripping)
  - Consider enabling ThinLTO/LTO in the app for further size gains
- Objective‑C API (wrappers):
  - Not included in this minimal xcframework. Use one of:
    - CocoaPods: `Tor/CTor-NoLZMA` subspec (brings `TORThread`, `TORController` sources + links the xcframework), or
    - Vendor the ObjC sources from `Tor/Classes/CTor` and `Tor/Classes/Core` directly into your project.

**Rebuilding**
- Ensure prerequisites: `brew install automake autoconf libtool gettext`
- Clone iCepa/Tor.framework to `~/Documents/vibe/Tor.framework-build/`
- Run: `cd ~/Documents/vibe/Tor.framework-build && ./build-minimal.sh`
- Logs: `build/*.log` and per-component logs like `build/libtor-nolzma-<sdk>-<arch>.log`
- Copy output to project: `cp -R tor-nolzma.xcframework /path/to/bitchat/localPackages/Tor/Frameworks/`

**LZMA Trade‑off (for reference)**
- We measured that enabling LZMA adds roughly ~0.25 MB per slice to the binary on this setup. For a 3‑slice xcframework, expect ~0.7–0.8 MB more overall.
- If you want the LZMA variant with the same minimal trimming: `./build-xcframework.sh -Md` (outputs `tor.xcframework`).

**Key Flags (for auditing)**
- OpenSSL `./Configure` (aggressive trimming):
  - `no-shared no-zlib no-comp no-ssl3 no-tls1 no-tls1_1 no-dtls`
  - `no-srp no-psk no-weak-ssl-ciphers no-engine no-ocsp no-cms no-ts`
  - `no-idea no-seed no-camellia no-aria no-bf no-cast no-des no-rc2 no-rc4`
  - `no-md4 no-mdc2 no-whirlpool no-rmd160 no-sm2 no-sm3 no-sm4`
  - `no-siphash no-scrypt no-legacy no-dso no-dgram no-http`
- libevent `./configure`: `--disable-openssl --disable-samples --disable-libevent-regress --enable-static --disable-shared`
- Tor `./configure` (highlights):
  - `--enable-pic --disable-module-relay --disable-module-dirauth --disable-module-pow --disable-unittests`
  - `--enable-static-openssl --enable-static-libevent`
  - `--disable-asciidoc --disable-manpage --disable-html-manual --disable-zstd`
  - `--enable-lzma=no` (in this build)
- Compiler flags: `-Os -ffunction-sections -fdata-sections`; no bitcode
- Linker flags: `-Wl,-dead_strip`
- Minimum OS: iOS 12.0, macOS 10.13

**Verification Tips**
- Check slices: `lipo -info tor-nolzma.xcframework/*/tor-nolzma.framework/tor-nolzma`
- Ensure headers present: `ls tor-nolzma.xcframework/*/tor-nolzma.framework/Headers`
- Link test: build a small app and add `-dead_strip`; confirm successful run and circuit establishment via control port.

**Notes**
- This minimal build avoids bundling large GeoIP resources. If you need GeoIP, embed the GeoIP bundle (or use the `Tor/GeoIP-NoLZMA` subspec) and set `TORConfiguration.geoipFile`/`geoip6File`.
- Static linking maximizes the app’s ability to dead‑strip unused code across the boundary.