blue-js-sdk 2.0.0

package/ai-path/DEPENDENCIES.md

@@ -0,0 +1,459 @@
+# Sentinel SDK Dependencies
+
+> Complete dependency reference for the Sentinel dVPN SDK.
+> Every dependency listed with: what it is, why it's needed, exact version, what breaks if wrong, how to install, how to verify.
+
+---
+
+## Runtime Environment
+
+### Node.js
+
+| Property | Value |
+|----------|-------|
+| **What** | JavaScript runtime |
+| **Why** | The JS SDK is ES Module-based; requires Node.js 20+ for native fetch, AbortController, and stable ES module support |
+| **Exact version** | `>=20.0.0` (specified in `package.json` `engines`) |
+| **What breaks if wrong** | Node 18: `fetch` adapter issues with axios on self-signed certs. Node 16: no top-level await, no AbortController, ES module bugs. |
+| **Install** | https://nodejs.org/ -- download LTS (20.x or 22.x) |
+| **Verify** | `node --version` -- must show v20.x.x or higher |
+
+### .NET 8.0 SDK (C# only)
+
+| Property | Value |
+|----------|-------|
+| **What** | .NET runtime and build tools |
+| **Why** | The C# SDK targets .NET 8.0 for WPF desktop apps |
+| **Exact version** | .NET 8.0 SDK |
+| **What breaks if wrong** | .NET 6/7: Missing APIs used by the SDK. .NET 9: untested, may have breaking changes. |
+| **Install** | https://dotnet.microsoft.com/download/dotnet/8.0 |
+| **Verify** | `dotnet --version` -- must show 8.0.x |
+
+---
+
+## npm Packages (JS SDK)
+
+### @cosmjs/stargate
+
+| Property | Value |
+|----------|-------|
+| **What** | Cosmos SDK client library for signing and broadcasting transactions |
+| **Why** | Core chain interaction: wallet creation, message signing, transaction broadcast, RPC queries |
+| **Exact version** | `^0.32.2` |
+| **What breaks if wrong** | 0.31.x: Different `SigningStargateClient` API, missing gas estimation features. 0.33+: untested, may have breaking changes to registry or signing. |
+| **Install** | `npm install @cosmjs/stargate@^0.32.2` |
+| **Verify** | `node -e "import('@cosmjs/stargate').then(m => console.log('OK:', Object.keys(m).length, 'exports'))"` |
+
+### @cosmjs/amino
+
+| Property | Value |
+|----------|-------|
+| **What** | Cosmos Amino encoding for legacy message signing |
+| **Why** | Some Sentinel message types use Amino encoding; required by `@cosmjs/stargate` |
+| **Exact version** | `^0.32.2` (must match stargate version) |
+| **What breaks if wrong** | Version mismatch with stargate causes cryptic encoding errors on TX broadcast |
+| **Install** | `npm install @cosmjs/amino@^0.32.2` |
+| **Verify** | Installed automatically with stargate; verify same version in `package-lock.json` |
+
+### @cosmjs/crypto
+
+| Property | Value |
+|----------|-------|
+| **What** | Cryptographic primitives (SHA256, secp256k1, Ripemd160) |
+| **Why** | Wallet key derivation (BIP39/BIP44), handshake signature (secp256k1 sign of session ID), address generation |
+| **Exact version** | `^0.32.2` (must match stargate version) |
+| **What breaks if wrong** | Signature format changes break handshake; key derivation changes break wallet address |
+| **Install** | `npm install @cosmjs/crypto@^0.32.2` |
+| **Verify** | `node -e "import('@cosmjs/crypto').then(m => console.log('Secp256k1:', typeof m.Secp256k1))"` |
+
+### @cosmjs/encoding
+
+| Property | Value |
+|----------|-------|
+| **What** | Encoding utilities (Bech32, Base64, hex) |
+| **Why** | Bech32 address encoding (`sent1...`, `sentnode1...`), Base64 for handshake signatures and keys |
+| **Exact version** | `^0.32.2` (must match stargate version) |
+| **What breaks if wrong** | Address encoding changes break all chain queries |
+| **Install** | `npm install @cosmjs/encoding@^0.32.2` |
+| **Verify** | `node -e "import('@cosmjs/encoding').then(m => console.log('Bech32:', typeof m.Bech32))"` |
+
+### @cosmjs/proto-signing
+
+| Property | Value |
+|----------|-------|
+| **What** | Protobuf message signing and registry |
+| **Why** | Registering Sentinel-specific message types (MsgStartSession, MsgEndSession, etc.) in the CosmJS Registry |
+| **Exact version** | `^0.32.2` (must match stargate version) |
+| **What breaks if wrong** | Unregistered message types silently fail on broadcast; sessions never start or end |
+| **Install** | `npm install @cosmjs/proto-signing@^0.32.2` |
+| **Verify** | `node -e "import('@cosmjs/proto-signing').then(m => console.log('Registry:', typeof m.Registry))"` |
+
+**CRITICAL:** All 5 `@cosmjs/*` packages must be the SAME version. Mixed versions cause encoding mismatches and cryptic failures.
+
+### @noble/curves
+
+| Property | Value |
+|----------|-------|
+| **What** | Elliptic curve cryptography (secp256k1, x25519) |
+| **Why** | X25519 key generation for WireGuard handshake; secp256k1 for handshake signature computation |
+| **Exact version** | `^2.0.1` |
+| **What breaks if wrong** | 1.x: Different API (no `x25519.utils`). Key generation fails silently or produces wrong keys. |
+| **Install** | `npm install @noble/curves@^2.0.1` |
+| **Verify** | `node -e "import('@noble/curves/ed25519').then(m => console.log('x25519:', typeof m.x25519))"` |
+
+### axios
+
+| Property | Value |
+|----------|-------|
+| **What** | HTTP client library |
+| **Why** | All HTTP requests to Sentinel nodes (handshake, status), LCD queries, speed tests. SOCKS5 proxy support via agents. |
+| **Exact version** | `^1.6.8` |
+| **What breaks if wrong** | <1.0: Missing `adapter` config. Node.js 18+ uses fetch adapter by default; self-signed certs fail without `adapter: 'http'`. |
+| **Install** | `npm install axios@^1.6.8` |
+| **Verify** | `node -e "import('axios').then(m => console.log('axios:', m.default.VERSION))"` |
+
+**CRITICAL:** Must set `axios.defaults.adapter = 'http'` at startup. Node.js 18+ defaults to `fetch` adapter which cannot handle self-signed certificates used by Sentinel nodes. Without this, every node HTTPS request fails with opaque "fetch failed" error.
+
+### dotenv
+
+| Property | Value |
+|----------|-------|
+| **What** | Environment variable loader from `.env` files |
+| **Why** | Loading mnemonic, RPC/LCD URLs, and configuration from `.env` without hardcoding secrets |
+| **Exact version** | `^16.6.1` |
+| **What breaks if wrong** | Older versions: Missing `dotenv/config` import path. Not critical -- any v16+ works. |
+| **Install** | `npm install dotenv@^16.6.1` |
+| **Verify** | Create `.env` with `TEST=hello`, run `node -e "import('dotenv/config'); console.log(process.env.TEST)"` |
+
+### socks-proxy-agent
+
+| Property | Value |
+|----------|-------|
+| **What** | SOCKS5 proxy agent for HTTP clients |
+| **Why** | Speed testing through V2Ray SOCKS5 tunnel; verifying tunnel connectivity |
+| **Exact version** | `^8.0.4` |
+| **What breaks if wrong** | <8.0: Different API; `new SocksProxyAgent()` constructor changes. Native `fetch` silently ignores this agent -- must use axios. |
+| **Install** | `npm install socks-proxy-agent@^8.0.4` |
+| **Verify** | `node -e "import('socks-proxy-agent').then(m => console.log('SocksProxyAgent:', typeof m.SocksProxyAgent))"` |
+
+**CRITICAL:** JavaScript native `fetch()` silently ignores SOCKS proxy agents. All SOCKS5 speed tests MUST use axios with `adapter: 'http'`. Using `fetch` through a SOCKS5 proxy appears to work but bypasses the proxy entirely.
+
+---
+
+## External Binaries
+
+### WireGuard
+
+| Property | Value |
+|----------|-------|
+| **What** | VPN tunnel implementation using Noise protocol |
+| **Why** | Primary tunnel type for Sentinel dVPN; ~380 nodes are WireGuard, 100% success rate when reachable |
+| **Exact version** | Any recent version; tested with v0.5.3 (Windows Dec 2021) |
+| **What breaks if wrong** | WireGuard is backwards-compatible; version rarely matters. The SDK uses `/installtunnelservice` and `/uninstalltunnelservice` CLI commands which are stable. |
+| **Install (Windows)** | Download from https://www.wireguard.com/install/ -- MSI installer |
+| **Install (macOS)** | `brew install wireguard-tools` or App Store |
+| **Install (Linux)** | `sudo apt install wireguard-tools` or `yum install wireguard-tools` |
+| **Verify** | `"C:\Program Files\WireGuard\wireguard.exe" /help` (Windows) or `wg --version` (macOS/Linux) |
+| **Default path (Windows)** | `C:\Program Files\WireGuard\wireguard.exe` |
+| **Default path (macOS/Linux)** | `/usr/bin/wg-quick` or `/usr/local/bin/wg-quick` |
+
+**CRITICAL REQUIREMENTS:**
+- **Windows: Administrator privileges REQUIRED.** WireGuard installs a Windows service (`WireGuardTunnel$wgsent0`) which requires SYSTEM-level access. Without admin, tunnel install silently fails. Check admin BEFORE paying for a session.
+- **Never call `/installmanagerservice`** -- this launches the WireGuard GUI and takes over all tunnel management. Only use `/installtunnelservice` and `/uninstalltunnelservice`.
+- **Use `execFileSync`, never `execSync` with string interpolation** -- prevents command injection and Git Bash path mangling.
+- **Config file must remain on disk while service exists** -- the Windows service reads `wgsent0.conf` at startup; deleting it causes "file not found" crash.
+
+### V2Ray
+
+| Property | Value |
+|----------|-------|
+| **What** | Multi-protocol proxy platform (VMess, VLess, gRPC, WebSocket, etc.) |
+| **Why** | Secondary tunnel type for Sentinel dVPN; ~407 nodes are V2Ray. Supports multiple transport protocols. |
+| **Exact version** | **v5.2.1 ONLY** |
+| **What breaks if wrong** | v5.44.1+: Observatory module has bugs that mark working outbounds as dead; connection success rate drops drastically. v4.x: Different config format entirely. v5.3-5.43: untested, may or may not work. **The SDK will silently use a wrong version if it finds one on PATH.** |
+| **Install** | SDK's `setup.js` auto-downloads v5.2.1 to `~/.sentinel-sdk/bin/v2ray.exe`. Run `npm run setup` or `node setup.js`. |
+| **Verify** | `~/.sentinel-sdk/bin/v2ray.exe version` -- must show `V2Ray 5.2.1` |
+| **Binary location** | `~/.sentinel-sdk/bin/v2ray.exe` (Windows), `~/.sentinel-sdk/bin/v2ray` (macOS/Linux) |
+
+**CRITICAL REQUIREMENTS:**
+- **Exactly v5.2.1.** No newer, no older. The observatory module in 5.44.1+ has confirmed bugs.
+- **Do not rely on system-wide V2Ray.** The SDK should use its own copy at `~/.sentinel-sdk/bin/`.
+- **Two companion data files required:** `geoip.dat` and `geosite.dat` must be in the same directory as the binary.
+- **SOCKS5 inbound configuration:** When using `systemProxy: true`, SOCKS5 auth must be set to `noauth` because Windows system proxy cannot pass credentials.
+- **Port selection:** Use `10800 + Math.floor(Math.random() * 1000)` for SOCKS5 port. Increment for fallback outbounds to avoid TIME_WAIT conflicts.
+
+### GeoIP and GeoSite Data
+
+| Property | Value |
+|----------|-------|
+| **What** | IP geolocation and domain categorization databases for V2Ray routing |
+| **Why** | V2Ray uses these for routing decisions; required at startup |
+| **Exact version** | Any recent version; bundled with V2Ray download |
+| **What breaks if wrong** | V2Ray fails to start with "geoip.dat not found" error |
+| **Install** | Automatically downloaded by `setup.js` alongside V2Ray binary |
+| **Verify** | Check files exist in V2Ray binary directory |
+
+---
+
+## OS Requirements
+
+### Windows
+
+| Requirement | Details |
+|-------------|---------|
+| **Windows 10/11** | WireGuard requires Windows 10 1607+ for Wintun driver support |
+| **Administrator privileges** | Required for WireGuard service install, kill switch firewall rules, DNS leak prevention |
+| **PowerShell** | Required for VPN conflict detection, adapter cleanup, diagnostic commands |
+| **Windows Firewall** | Must be running for kill switch functionality (`netsh advfirewall`) |
+| **.NET 8.0 Runtime** | Required for C# SDK only; installed with SDK or separately |
+
+### macOS
+
+| Requirement | Details |
+|-------------|---------|
+| **macOS 12+** | Required for modern WireGuard kernel extension support |
+| **Root access** | Required for `wg-quick up/down` and `networksetup` proxy configuration |
+| **wireguard-tools** | Install via `brew install wireguard-tools` |
+
+### Linux
+
+| Requirement | Details |
+|-------------|---------|
+| **Kernel 5.6+** | WireGuard built into kernel since 5.6; older kernels need `wireguard-dkms` |
+| **Root access** | Required for `wg-quick` and `gsettings` proxy configuration |
+| **wireguard-tools** | Install via package manager |
+
+---
+
+## Sentinel Chain Infrastructure
+
+### LCD (Light Client Daemon) Endpoints
+
+| Property | Value |
+|----------|-------|
+| **What** | REST API for querying chain state (nodes, subscriptions, sessions, balances) |
+| **Why** | All chain queries: node discovery, subscription lookup, session status, balance check |
+| **Primary** | `https://lcd.sentinel.co` |
+| **Failover 1** | `https://api.sentinel.quokkastake.io` |
+| **Failover 2** | `https://sentinel-api.polkachu.com` |
+| **Failover 3** | `https://sentinel.api.trivium.network:1317` |
+| **What breaks** | All LCD endpoints down = no node queries, no subscriptions, no chain interaction |
+| **Verify** | `curl https://lcd.sentinel.co/sentinel/node/v3/nodes?status=1&pagination.limit=1` |
+
+**CRITICAL:** All paths must use v3 format EXCEPT provider which is v2:
+- Nodes: `/sentinel/node/v3/nodes?status=1`
+- Sessions: `/sentinel/session/v3/accounts/{addr}/sessions`
+- Subscriptions: `/sentinel/subscription/v3/accounts/{addr}/subscriptions`
+- Plans: `/sentinel/node/v3/plans/{id}/nodes`
+- Provider: `/sentinel/provider/v2/providers/{addr}` (v2 only!)
+
+### RPC Endpoints
+
+| Property | Value |
+|----------|-------|
+| **What** | Tendermint RPC for transaction broadcast and block queries |
+| **Why** | Signing and broadcasting transactions (session creation, subscription, etc.) |
+| **Primary** | `https://rpc.sentinel.co` |
+| **Failover 1** | `https://rpc.sentinel.quokkastake.io` |
+| **Failover 2** | `https://sentinel-rpc.polkachu.com` |
+| **What breaks** | All RPC endpoints down = no transactions, no connections |
+| **Verify** | `curl https://rpc.sentinel.co/status` |
+
+### Chain Parameters
+
+| Parameter | Value |
+|-----------|-------|
+| **Chain ID** | `sentinelhub-2` |
+| **Denom** | `udvpn` (micro-DVPN; 1 P2P = 1,000,000 udvpn) |
+| **Display token** | P2P (not DVPN, not dvpn) |
+| **Gas price** | `0.2udvpn` |
+| **Address prefix** | `sent1...` (wallet), `sentnode1...` (node), `sentprov1...` (provider) |
+| **Key algorithm** | secp256k1 (same as Cosmos Hub, Ethereum) |
+| **HD path** | `m/44'/118'/0'/0/0` (Cosmos standard) |
+
+---
+
+## Protocol Specifications
+
+### V3 Handshake
+
+| Property | Value |
+|----------|-------|
+| **Method** | `POST /` to node's remote URL |
+| **Content-Type** | `application/json` |
+| **TLS** | Self-signed certificates; use TOFU model |
+| **Timeout** | 90 seconds (increased from 30s through testing) |
+
+**Request body:**
+```json
+{
+  "session_id": 12345678,
+  "key": "<base64-encoded-key>",
+  "signature": "<base64-encoded-signature>"
+}
+```
+
+**Signature computation:**
+1. Convert session_id to 8-byte big-endian uint64
+2. Sign raw bytes with secp256k1 private key (same key that created session)
+3. Base64-encode the signature
+
+**Key field:**
+- WireGuard: X25519 public key (32 bytes, base64)
+- V2Ray: UUID as 16-byte array (base64)
+
+### V2Ray Transport Map
+
+| Sentinel Enum | Transport | V2Ray Network | Success Rate |
+|---------------|-----------|---------------|-------------|
+| 1 | domainsocket | N/A (unusable remotely) | 0% |
+| 2 | gun | `grpc` | 100% (same config as grpc) |
+| 3 | grpc | `grpc` | 87% (none), 0% (tls) |
+| 4 | http | `http` | 100% |
+| 5 | mkcp | `kcp` | 100% |
+| 6 | quic | `quic` | 0% (with 5.2.1 fix: untested post-fix) |
+| 7 | tcp | `tcp` | 100% |
+| 8 | websocket | `ws` | 100% |
+
+### V2Ray Proxy Protocol Map
+
+| Sentinel Enum | Protocol | V2Ray Protocol |
+|---------------|----------|---------------|
+| 1 | VLess | `vless` (encryption=none, NO flow) |
+| 2 | VMess | `vmess` (alterId=0, NO security in user) |
+
+### WireGuard Config Template
+
+```ini
+[Interface]
+PrivateKey = <client-x25519-private-key>
+Address = <assigned-address-from-handshake>/32
+MTU = 1280
+DNS = 10.8.0.1
+
+[Peer]
+PublicKey = <server-public-key-from-handshake>
+Endpoint = <server-endpoint-from-handshake>
+AllowedIPs = 0.0.0.0/0, ::/0
+PersistentKeepalive = 15
+```
+
+**Non-negotiable values:**
+- MTU = 1280 (NOT 1420)
+- DNS = 10.8.0.1 (NOT external DNS)
+- PersistentKeepalive = 15 (NOT 30)
+
+---
+
+## NuGet Packages (C# SDK)
+
+### CosmosSharp / Cosmos SDK bindings
+
+| Property | Value |
+|----------|-------|
+| **What** | Cosmos chain interaction for .NET |
+| **Why** | Transaction signing, broadcasting, and chain queries in C# |
+| **Note** | The C# SDK has its own `TransactionBuilder` and `ChainClient` that use raw HTTP -- not a third-party Cosmos SDK package |
+
+### System.Security.Cryptography
+
+| Property | Value |
+|----------|-------|
+| **What** | .NET built-in cryptography |
+| **Why** | secp256k1 signing, SHA256, X25519 key generation |
+| **Note** | Built into .NET 8.0; no separate package needed |
+
+### System.Text.Json
+
+| Property | Value |
+|----------|-------|
+| **What** | .NET built-in JSON serializer |
+| **Why** | Parsing LCD responses, handshake payloads, config files |
+| **CRITICAL** | String-number round-trip bug: `"5500000"` (string) serializes as `5500000` (number), deserializes back as `null`. Test all data models with round-trip serialization. |
+
+---
+
+## Development Dependencies
+
+### For testing the SDK itself
+
+| Tool | Purpose | Version |
+|------|---------|---------|
+| `node test/smoke.js` | SDK smoke tests (661 assertions) | Built-in |
+| Live Sentinel mainnet | Integration testing | N/A |
+| Funded wallet | Real chain transactions | Need `udvpn` tokens |
+
+### For building consumer apps
+
+| Tool | Purpose | Notes |
+|------|---------|-------|
+| `npm` or `yarn` | Package management | npm 10+ recommended |
+| Git | Version control | Any recent version |
+| VS Code / IDE | Development | Recommended: ESLint with single-quote, semicolons |
+
+---
+
+## Version Compatibility Matrix
+
+| Component | Minimum | Recommended | Maximum Tested |
+|-----------|---------|-------------|---------------|
+| Node.js | 20.0.0 | 22.x LTS | 22.x |
+| .NET SDK | 8.0.0 | 8.0.x latest | 8.0.x |
+| @cosmjs/* | 0.32.2 | 0.32.4 | 0.32.x |
+| @noble/curves | 2.0.1 | 2.x latest | 2.x |
+| axios | 1.6.8 | 1.7.x | 1.x |
+| V2Ray | 5.2.1 | **5.2.1 only** | 5.2.1 |
+| WireGuard | 0.5.3 | Latest | Latest |
+| Windows | 10 1607 | 11 | 11 |
+| macOS | 12 | 14+ | 15 |
+| Linux kernel | 5.6 | 6.x | 6.x |
+
+---
+
+## Dependency Installation Checklist
+
+For a fresh development machine:
+
+```bash
+# 1. Install Node.js 22 LTS
+# Download from https://nodejs.org/
+
+# 2. Install WireGuard
+# Windows: https://www.wireguard.com/install/ (MSI)
+# macOS: brew install wireguard-tools
+# Linux: sudo apt install wireguard-tools
+
+# 3. Clone/create project and install SDK
+npm init -y
+npm install sentinel-dvpn-sdk
+
+# 4. Download V2Ray 5.2.1 (automatic)
+npx sentinel-setup
+# OR: node node_modules/sentinel-dvpn-sdk/setup.js
+
+# 5. Create .env file
+echo "MNEMONIC=your twelve word mnemonic phrase goes here" > .env
+
+# 6. Verify everything
+node -e "
+import sdk from 'sentinel-dvpn-sdk';
+console.log('SDK exports:', Object.keys(sdk).length);
+"
+
+# 7. Run smoke tests
+node node_modules/sentinel-dvpn-sdk/test/smoke.js
+```
+
+**For C# projects:**
+
+```bash
+# 1. Install .NET 8.0 SDK
+# Download from https://dotnet.microsoft.com/download/dotnet/8.0
+
+# 2. Add SDK NuGet package (when published)
+dotnet add package Sentinel.SDK
+
+# 3. Build and run tests
+dotnet build
+dotnet test
+```