sdk-relay-leaf

KO | EN

gitlite — search

#javascript #python #hacktoberfest #react #ai #typescript #llm #go #golang #android #machine-learning #rust #deep-learning #linux

★ 12 Open GitHub ↗

Multi-platform, multi-language SDK for P2P Relay Network Client — supporting Windows, Linux, macOS, and Android with bindings for Python, Go, C#, Node.js, Rust, C/C++, Ruby, Java, Kotlin, and Flutter.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# 🍃 Relay Leaf SDK

> **Multi-platform, multi-language SDK for P2P Relay Network Client.**
>
> Connect to the decentralized relay network with native performance across **9 platforms** and **10 programming languages**.

---

## 📋 Table of Contents

- [Overview](#-overview)
- [Features](#-features)
- [Supported Platforms](#-supported-platforms)
- [Supported Languages](#-supported-languages)
- [Quick Start](#-quick-start)
- [Directory Structure](#-directory-structure)
- [API Reference](#-api-reference)
- [Code Examples](#-code-examples)
- [Library Download & Verification](#-library-download--verification)
- [Building from Source](#-building-from-source)
- [Memory Management](#-memory-management)
- [Troubleshooting](#-troubleshooting)
- [License](#-license)

---

## 🔍 Overview

Relay Leaf SDK provides native bindings for connecting to the **P2P relay network**. Built with Go and compiled as shared libraries (`.dll`, `.so`, `.dylib`), it offers high performance and cross-platform compatibility.

The SDK wraps a single native library into idiomatic bindings for each supported language, so you can integrate relay networking into your project using the language you already know.

## ✨ Features

| Feature | Description |
|---------|-------------|
| 🌐 **Auto Discovery** | Automatically connects to relay nodes via discovery service |
| 🔀 **Stream Multiplexing** | Efficient multiplexing over relay connections |
| 🛡️ **Proxy Support** | SOCKS5 and HTTP proxy support |
| 🔄 **Auto Reconnect** | Exponential backoff reconnection strategy |
| 📊 **Real-time Stats** | Live connection statistics and monitoring |
| 🔑 **Partner Auth** | Partner ID-based authentication |
| 📦 **Auto Download** | Built-in library downloader with SHA256 verification |
| 🧹 **Auto Cleanup** | Context managers / RAII for automatic resource management |

---

## 💻 Supported Platforms

| Platform | Architecture | Native Library | Status |
|:---------|:-------------|:---------------|:------:|
| 🪟 Windows | x64 | `relay_leaf-windows-x64.dll` | ✅ Ready |
| 🪟 Windows | x86 | `relay_leaf-windows-x86.dll` | ✅ Ready |
| 🐧 Linux | x64 | `librelay_leaf-linux-x64.so` | ✅ Ready |
| 🐧 Linux | ARM64 | `librelay_leaf-linux-arm64.so` | ✅ Ready |
| 🍎 macOS | ARM64 (Apple Silicon) | `librelay_leaf-darwin-arm64.dylib` | ✅ Ready |
| 🍎 macOS | x64 (Intel) | `librelay_leaf-darwin-amd64.dylib` | ✅ Ready |
| 🤖 Android | ARM64-v8a | `librelay_leaf.so` | ✅ Ready |
| 🤖 Android | ARMv7a | `librelay_leaf.so` | ✅ Ready |
| 🤖 Android | x86_64 | `librelay_leaf.so` | ✅ Ready |

## 🌍 Supported Languages

| Language | 🪟 Win x64 | 🪟 Win x86 | 🐧 Linux | 🍎 macOS | 🤖 Android |
|:---------|:----------:|:----------:|:--------:|:--------:|:----------:|
| 🐍 Python | ✅ | ✅ | ✅ | ✅ | — |
| 🔵 Go | ✅ | ✅ | ✅ | ✅ | — |
| 💜 C# | ✅ | ✅ | ✅ | ✅ | — |
| 🟢 Node.js | ✅ | — | ✅ | ✅ | — |
| 🦀 Rust | ✅ | ✅ | ✅ | ✅ | — |
| ⚙️ C/C++ | ✅ | ✅ | ✅ | ✅ | — |
| 💎 Ruby | ✅ | — | — | — | — |
| ☕ Java | — | — | — | — | ✅ |
| 🟣 Kotlin | — | — | — | — | ✅ |
| 🔷 Flutter/Dart | — | — | — | — | ✅ |

---

## 🚀 Quick Start

### 1️⃣ Auto-Download Native Library

All SDKs include a **LibraryDownloader** that automatically downloads and verifies native libraries:

<details>
<summary>🐍 Python</summary>

```python
from lib.relay_leaf import ensure_library, RelayLeaf

# Auto-download and verify native library
if ensure_library():
    print("Library ready!")

with RelayLeaf(verbose=True) as client:
        client.set_partner_id("your-partner-id")
        client.start()
```

</details>

```go
import relayleaf "./lib"

// Auto-download and verify native library
if relayleaf.EnsureLibrary("") {
    fmt.Println("Library ready!")
}

client, _ := relayleaf.NewClient(true)
defer client.Close()
client.Start()
```

</details>

```csharp
using RelayLeafSDK;

// Auto-download and verify native library
if (LibraryDownloader.EnsureLibrary()) {
    Console.WriteLine("Library ready!");
}

using var client = new RelayLeaf(verbose: true);
client.SetPartnerId("your-partner-id");
client.Start();
```

</details>

```javascript
const { ensureLibrary, RelayLeaf } = require('./lib/relay_leaf');

// Auto-download and verify native library
await ensureLibrary();

const client = new RelayLeaf(true);
client.create();
client.setPartnerId('your-partner-id');
client.start();
```

</details>

```rust
use relay_leaf_sdk::{RelayLeaf, ensure_library};

// Auto-download and verify native library
ensure_library(None);

let client = RelayLeaf::new(true)?;
client.set_partner_id("your-partner-id")?;
client.start()?;
```

</details>

```c
#include "relay_leaf.h"

// Create client
RelayLeafHandle handle;
relay_leaf_create(true, &handle);

// Configure & start
relay_leaf_set_partner_id(handle, "your-partner-id");
relay_leaf_start(handle);
```

</details>

### 2️⃣ Run Examples

| Platform | Language | Command |
|:---------|:---------|:--------|
| 🪟 Windows x64 | 🐍 Python | `cd windows/python/example && python main.py` |
| 🪟 Windows x64 | 🔵 Go | `cd windows/go/example && go run main.go` |
| 🪟 Windows x64 | 💜 C# | `cd windows/csharp/example && dotnet run` |
| 🪟 Windows x64 | 🟢 Node.js | `cd windows/nodejs/example && npm install && npm start` |
| 🪟 Windows x64 | 🦀 Rust | `cd windows/rust/example && cargo run` |
| 🪟 Windows x64 | ⚙️ C | `cd windows/c/example && make run` |
| 🪟 Windows x64 | 💎 Ruby | `cd windows/ruby/example && ruby main.rb` |
| 🐧 Linux x64 | 🐍 Python | `cd linux/python/example && python3 main.py` |
| 🐧 Linux x64 | 🔵 Go | `cd linux/go/example && go run main.go` |
| 🐧 Linux x64 | 💜 C# | `cd linux/csharp/example && dotnet run` |
| 🐧 Linux x64 | 🟢 Node.js | `cd linux/nodejs/example && npm install && npm start` |
| 🐧 Linux x64 | 🦀 Rust | `cd linux/rust/example && cargo run` |
| 🐧 Linux x64 | ⚙️ C | `cd linux/c/example && make run` |
| 🤖 Android | ☕ Java/Kotlin | Open in Android Studio and run |

---

## 📁 Directory Structure

```
sdk-relay-leaf/
│
├── 🪟 windows/                     # Windows x64 SDKs
│   ├── python/
│   │   ├── lib/
│   │   │   ├── relay_leaf.py       # Python wrapper + LibraryDownloader
│   │   │   └── relay_leaf.dll      # Native library
│   │   └── example/
│   │       └── main.py
│   ├── go/
│   ├── csharp/
│   ├── nodejs/
│   ├── rust/
│   ├── c/
│   └── ruby/
│
├── 🪟 windows-x86/                 # Windows x86 (32-bit) SDKs
│   ├── python/
│   ├── go/
│   ├── csharp/
│   ├── rust/
│   └── c/
│
├── 🐧 linux/                       # Linux x64 SDKs
│   ├── python/
│   ├── go/
│   ├── csharp/
│   ├── nodejs/
│   ├── rust/
│   └── c/
│
├── 🍎 macos/                       # macOS SDKs
│   ├── python/
│   ├── go/
│   ├── csharp/
│   ├── nodejs/
│   ├── rust/
│   └── c/
│
└── 🤖 android/                     # Android SDKs
    ├── java/
    ├── kotlin/
    └── flutter/
```

---

## 📖 API Reference

### Core Functions

| Function | Description |
|:---------|:------------|
| `create(verbose)` | 🔧 Create a new client instance with optional verbose logging |
| `destroy()` | 🗑️ Destroy the client and free all resources |
| `set_discovery_url(url)` | 🌐 Set custom discovery service URL (optional) |
| `set_partner_id(id)` | 🔑 Set partner ID for authentication |
| `add_proxy(url)` | 🛡️ Add proxy server (`socks5://` or `http://`) |
| `start()` | ▶️ Start the relay client (non-blocking) |
| `stop()` | ⏹️ Stop the relay client gracefully |
| `get_device_id()` | 🆔 Get unique device identifier |
| `get_stats()` | 📊 Get current connection statistics |
| `is_connected()` | 🔗 Check if connected to relay network |
| `version()` | ℹ️ Get library version string |

### Statistics Structure

```
Stats {
    uptime_seconds       // ⏱️ Connection uptime in seconds
    total_streams        // 🔢 Total streams processed
    bytes_sent           // 📤 Total bytes sent
    bytes_received       // 📥 Total bytes received
    reconnect_count      // 🔄 Number of reconnection attempts
    active_streams       // ⚡ Currently active streams
    connected_nodes      // 🌐 Number of connected relay nodes
    connected            // ✅ Connection status (bool)
    last_error           // ❌ Last error message
    exit_points_json     // 🚪 JSON array of exit points
    node_addresses_json  // 📡 JSON array of connected node IPs
}
```

### Error Codes

| Code | Name | Description |
|:----:|:-----|:------------|
| `0` | ✅ `OK` | Success |
| `1` | ⚠️ `NULL_PARAM` | Null parameter provided |
| `2` | ⚠️ `INVALID_HANDLE` | Invalid client handle |
| `3` | ❌ `CREATE_FAILED` | Failed to create client |
| `4` | ❌ `START_FAILED` | Failed to start client |
| `5` | ⚠️ `ALREADY_STARTED` | Client already started |
| `6` | ⚠️ `NOT_STARTED` | Client not started |
| `7` | ❌ `INVALID_PROXY` | Invalid proxy URL format |
| `99` | 💥 `INTERNAL` | Internal error |

---

## 📝 Code Examples

<details>
<summary>🐍 Python — Full Example</summary>

```python
from lib.relay_leaf import RelayLeaf, ensure_library
import time

# Ensure library is downloaded and verified
ensure_library()

# Create client with context manager (auto cleanup)
with RelayLeaf(verbose=True) as client:
    # Configure
    client.set_partner_id("your-partner-id")
    # client.set_discovery_url("https://custom-discovery.example.com")
    # client.add_proxy("socks5://127.0.0.1:1080")

# Start
    client.start()
    print(f"Device ID: {client.get_device_id()}")

# Monitor
    while client.is_connected():
        stats = client.get_stats()
        print(f"Uptime: {stats['uptime_seconds']}s, Nodes: {stats['connected_nodes']}")
        time.sleep(5)
```

</details>

<details>
<summary>🔵 Go — Full Example</summary>

```go
package main

import (
    "fmt"
    "time"
    relayleaf "./lib"
)

func main() {
    // Ensure library is downloaded
    relayleaf.EnsureLibrary("")

// Create client
    client, err := relayleaf.NewClient(true)
    if err != nil {
        panic(err)
    }
    defer client.Close()

// Configure & Start
    client.SetPartnerID("your-partner-id")
    client.Start()
    fmt.Printf("Device ID: %s\n", client.GetDeviceID())

// Monitor
    for client.IsConnected() {
        stats, _ := client.GetStats()
        fmt.Printf("Uptime: %ds, Nodes: %d\n", stats.UptimeSeconds, stats.ConnectedNodes)
        time.Sleep(5 * time.Second)
    }
}
```

</details>

<details>
<summary>💜 C# — Full Example</summary>

```csharp
using RelayLeafSDK;

// Ensure library is downloaded
LibraryDownloader.EnsureLibrary();

// Create client with using statement (auto dispose)
using var client = new RelayLeaf(verbose: true);

// Configure & Start
client.SetPartnerId("your-partner-id");
client.Start();
Console.WriteLine($"Device ID: {client.GetDeviceId()}");

// Monitor
while (client.IsConnected)
{
    var stats = client.GetStats();
    Console.WriteLine($"Uptime: {stats.UptimeSeconds}s, Nodes: {stats.ConnectedNodes}");
    Thread.Sleep(5000);
}
```

</details>

<details>
<summary>🟢 Node.js — Full Example</summary>

```javascript
const { RelayLeaf, ensureLibrary } = require('./lib/relay_leaf');

async function main() {
    // Ensure library is downloaded
    await ensureLibrary();

// Create client
    const client = new RelayLeaf(true);
    client.create();

try {
        // Configure & Start
        client.setPartnerId('your-partner-id');
        client.start();
        console.log(`Device ID: ${client.getDeviceId()}`);

// Monitor
        const interval = setInterval(() => {
            if (client.isConnected()) {
                const stats = client.getStats();
                console.log(`Uptime: ${stats.uptimeSeconds}s, Nodes: ${stats.connectedNodes}`);
            }
        }, 5000);
    } finally {
        client.stop();
        client.destroy();
    }
}

main();
```

</details>

<details>
<summary>🦀 Rust — Full Example</summary>

```rust
use relay_leaf_sdk::{RelayLeaf, ensure_library};

fn main() -> Result<(), Box<dyn std::error::Error>> {
 // Ensure library is downloaded
 ensure_library(None);

// Create client (auto cleanup via Drop)
    let client = RelayLeaf::new(true)?;

// Configure & Start
    client.set_partner_id("your-partner-id")?;
    client.start()?;
    println!("Device ID: {}", client.get_device_id());

// Monitor
    while client.is_connected() {
        if let Some(stats) = client.get_stats() {
            println!("Uptime: {}s, Nodes: {}", stats.uptime_seconds, stats.connected_nodes);
        }
        std::thread::sleep(std::time::Duration::from_secs(5));
    }

Ok(())
}
```

</details>

<details>
<summary>⚙️ C/C++ — Full Example</summary>

```c
#include "relay_leaf.h"
#include <stdio.h>
#include <unistd.h>

int main() {
    // Create client
    RelayLeafHandle handle;
    if (relay_leaf_create(true, &handle) != RELAY_LEAF_OK) {
        printf("Failed to create client\n");
        return 1;
    }

// Configure & Start
    relay_leaf_set_partner_id(handle, "your-partner-id");
    relay_leaf_start(handle);

char* device_id = relay_leaf_get_device_id(handle);
    printf("Device ID: %s\n", device_id);
    relay_leaf_free_string(device_id);

// Monitor
    RelayLeafStats stats;
    while (1) {
        if (relay_leaf_get_stats(handle, &stats) == RELAY_LEAF_OK) {
            printf("Uptime: %llds, Nodes: %d, Connected: %d\n",
                   stats.uptime_seconds, stats.connected_nodes, stats.connected);
            relay_leaf_free_stats(&stats);
            if (!stats.connected) break;
        }
        sleep(5);
    }

// Cleanup
    relay_leaf_stop(handle);
    relay_leaf_destroy(handle);
    return 0;
}
```

</details>

---

## 📦 Library Download & Verification

### Download Server

SDKs automatically download native libraries from:

| Server | URL | Purpose |
|:-------|:----|:--------|
| 🌐 Primary CDN | `https://release.prx.network` | Main download server |

### How It Works

```
1. 📥 Fetch checksums.json from server
2. 🔍 Compare local file hash with expected hash
3. ⬇️ Download library if missing or hash mismatch
4. ✅ Verify SHA256 after download
5. 🚀 Library ready to use!
```

Libraries are verified using **SHA256 checksums** from `checksums.json` to ensure integrity.

---

## 🔨 Building from Source

<details>
<summary>🪟 Windows (x64)</summary>

```bash
export PATH=/c/ProgramData/mingw64/mingw64/bin:$PATH
CGO_ENABLED=1 GOOS=windows GOARCH=amd64 \
  go build -buildmode=c-shared -o relay_leaf-windows-x64.dll ./clib/
```

</details>

<details>
<summary>🪟 Windows (x86)</summary>

```bash
export PATH=/c/ProgramData/mingw32/mingw32/bin:$PATH
CGO_ENABLED=1 GOOS=windows GOARCH=386 \
  go build -buildmode=c-shared -o relay_leaf-windows-x86.dll ./clib/
```

</details>

<details>
<summary>🐧 Linux (x64)</summary>

```bash
CGO_ENABLED=1 GOOS=linux GOARCH=amd64 \
  go build -buildmode=c-shared -o librelay_leaf-linux-x64.so ./clib/
```

</details>

<details>
<summary>🐧 Linux (ARM64)</summary>

```bash
CGO_ENABLED=1 GOOS=linux GOARCH=arm64 CC=aarch64-linux-gnu-gcc \
  go build -buildmode=c-shared -o librelay_leaf-linux-arm64.so ./clib/
```

</details>

<details>
<summary>🍎 macOS (Apple Silicon)</summary>

```bash
CGO_ENABLED=1 GOOS=darwin GOARCH=arm64 \
  go build -buildmode=c-shared -o librelay_leaf-darwin-arm64.dylib ./clib/
```

</details>

<details>
<summary>🍎 macOS (Intel)</summary>

```bash
CGO_ENABLED=1 GOOS=darwin GOARCH=amd64 \
  go build -buildmode=c-shared -o librelay_leaf-darwin-amd64.dylib ./clib/
```

</details>

<details>
<summary>🤖 Android (ARM64)</summary>

```bash
export ANDROID_NDK_HOME=/path/to/android-ndk
export CC=$ANDROID_NDK_HOME/toolchains/llvm/prebuilt/linux-x86_64/bin/aarch64-linux-android21-clang

CGO_ENABLED=1 GOOS=android GOARCH=arm64 \
  go build -buildmode=c-shared -o librelay_leaf.so ./clib/
```

</details>

---

## 🧠 Memory Management

> **Important:** The native library allocates memory that must be properly freed to avoid leaks.

### 📌 Rules

| Rule | Details |
|:-----|:--------|
| 🔤 **Free returned strings** | `relay_leaf_get_device_id()`, `relay_leaf_version()`, `relay_leaf_error_message()` → free with `relay_leaf_free_string()` |
| 📊 **Free stats structure** | Always call `relay_leaf_free_stats()` after using stats. Frees: `last_error`, `exit_points_json`, `node_addresses_json` |
| 🔄 **Client lifecycle** | Create → Configure → Start → Stop → Destroy. `relay_leaf_destroy()` auto-calls `relay_leaf_stop()` |

> **Note:** High-level SDK wrappers (Python, Go, C#, Node.js, Rust, Ruby) handle memory management automatically via context managers, defer statements, or RAII patterns.

---

## 🔧 Troubleshooting

<details>
<summary>❌ Library not found</summary>

```
Error: Library not found: relay_leaf-windows-x64.dll
```

**Solution:** Run `ensure_library()` first to auto-download, or manually download from the release server.

</details>

<details>
<summary>⚠️ Hash mismatch</summary>

```
[LibraryDownloader] Hash mismatch! Local: ABC..., Expected: XYZ...
```

**Solution:** Delete the local library file and re-run `ensure_library()` to download a fresh copy.

</details>

<details>
<summary>🔌 Connection failed</summary>

```
Error: start: connection failed
```

**Solutions:**
1. Check internet connectivity
2. Verify partner ID is valid
3. Check proxy settings (if using proxy)
4. Enable verbose mode (`verbose=True`) for detailed logs

</details>

<details>
<summary>🔒 Proxy errors</summary>

```
Error: add_proxy: Invalid proxy URL
```

**Solutions:**
- Use correct format: `socks5://host:port` or `http://host:port`
- Ensure proxy server is running and accessible
- Check for typos in the URL

</details>

---

## 📄 License

This project is licensed under the **MIT License** — see the [LICENSE](LICENSE) file for details.

---

## 💬 Support

| Channel | Link |
|:--------|:-----|
| 🐛 Bug Reports | [GitHub Issues](https://github.com/lebachhiep/sdk-relay-leaf/issues) |
| 📖 Documentation | See individual SDK `README.md` files for language-specific details |
| 📦 Releases | [GitHub Releases](https://github.com/lebachhiep/sdk-relay-leaf/releases) |

---

Built with ❤️ for the decentralized web

sdk-relay-leaf

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README