dart-torchat/README.md

# TorChat Dart SDK (Full Node)

<p align="center">
<a href="https://haveno.com"><img src="https://foss.haveno.com/tor-project/torchat/raw/branch/main/assets/images/torchat-compressed-rounded.png" width=275 /></a>
</p>

----

A full, cross-platform **Tor/Arti-powered** TorChat written 100% in Dart.  
Spin it up on Windows, macOS, Linux—even mobile or Raspberry Pi—no C tool-chain, no hassle, and most importantly, run a full node on your phone, without too much strain.

> **TL;DR**  
> `dart pub global activate torchat`  
> `torchat run`  
> Voilà: a fully-functional relay + client with gRPC endpoints and a sweet high-level SDK.

---

## 🌐 What Is It?

TorChat-Dart is the **reference implementation** of the TorChat protocol in pure Dart.  
It exposes:

| Layer | Purpose |
|-------|---------|
| **gRPC API** | Full power, language-agnostic. Auto-generated protobuf docs & stubs. |
| **Dart SDK** | High-level classes (`TorChatClient`, `TorChatRelay`, `GroupChat`, …). |
| **Tor/Arti wrapper** | Boots a hidden service automatically; no Tor install required. |

Perfect for bots, CLIs, desktop apps, or embedding in Flutter.

---

## 🚀 Features

* **Multi-platform** – runs anywhere Dart VM runs ✔  
* **Automatic Tor/Arti** – `dart run torchat:tor` launches a hidden service for you ✔  
* **gRPC over onion** – multiplexed, binary, schema-safe ✔  
* **Envelope store-and-forward** – offline delivery with spam-PoW ✔  
* **Group chat** – federated membership & signed admin events ✔  
* **Identity graph** – user profiles + attestations ✔  
* **Pluggable back-end** – swap LMDB ⇄ Hive ⇄ SQLite with one flag ✔  

---

## 📦 Installation

```bash
# 1. Install Dart ≥ 3.4
# 2. Install TorChat globally
dart pub global activate torchat
# 3. Run a node
torchat run
```

First launch will:

1. Generate an Ed25519 keypair.  
2. Start Arti & publish `xxxxxx.onion`.  
3. Sync seed-peers and begin relaying.

---

## 🔧 Configuration

`torchat.yaml` (auto-created in `$HOME/.torchat/`):

```yaml
listen_port: 20900
data_dir: ~/.torchat/data
tor:
  enabled: true
  socks_port: 9050          # 0 = random
storage:
  backend: hive             # hive | sqlite | lmdb
pow:
  difficulty: 20            # leading zero bits
```

Change, save, restart — settings hot-reload.

---

## 📚 gRPC & Protobuf Docs

- **Protos** live in [`/proto`](proto/) and are versioned in this repo.  
- `make protodocs` autogenerates HTML docs for every RPC & message.  
- Language stubs: `dart run build_runner` (Dart) or `buf generate` (all major languages).

### Quick test with `grpcurl`

```bash
grpcurl -plaintext -protoset out/descriptor.pb \
  -d '{"value":"<your pubkey hex>"}' \
  127.0.0.1:20900 torchat.Relay/GetEnvelopes
```

---

## 🛠️ Dart SDK snippet

```dart
import 'package:torchat/torchat.dart';

void main() async {
  final node = await TorChat.bootstrap();       // starts Tor + gRPC
  final client = node.client;

  await client.sendMessage(
    recipientPk: '<hex>',
    text: 'Hello, dark net!',
  );

  client.onMessage.listen((msg) {
    print('${msg.senderShort}: ${msg.text}');
  });
}
```

---

## 🗺 Roadmap

| Phase | Goal | ETA |
|-------|------|-----|
| **v0.1** | MVP relay + direct messages | ✅ now |
| **v0.2** | Group chats + signed admin events | Jun 2025 |
| **v0.3** | Mobile Flutter wrapper | Q3 2025 |
| **v1.0** | Plugin marketplace, file transfer, sticker packs | Q1 2026 |

---

## 🤝 Contributing

1. `git clone https://foss.haveno.com/haveno-network/dart-torchat`
2. `dart pub get`
3. `dart test`
4. PRs welcome — keep commits sign-off (`-s`) for DCO.

---

## 🛡 License

Apache-2.0