tiptool 1.0.1

tiptool: ^1.0.1 copied to clipboard

TipTool — Decentralized Data Mesh Layer for FBBL-integrated apps

🚀 What is TipTool? TipTool is a decentralized, peer-capable database layer written in Dart. It draws from the dbgun lineage to provide a CRDT-based graph store that synchronizes Flutter clients, persists encrypted state locally, and bridges securely into the FinBberLink (FBBL) protocol without exposing FBBL internals. TipTool exists to give FinBo and other finance products an offline-first, verifiable data mesh that can speak to Rust-backed intelligence through a narrow, versioned interface.

✨ Key Features • 🔁 Offline-first graph store with diff-based CRDT merges (diffTTCRDT) and per-field vector clocks. • 🌐 Real-time replication via pluggable connectors (WebSocket, custom wires) and peer discovery hooks. • 🧩 Modular storage: encrypted Hive box (secure-vaultBox) with secure key escrow in FlutterSecureStorage. • 🛠️ Extensible auth: SEA/SEAR utilities for keypairs, signatures, and user-scoped graph access. • 🧮 Vector adapters that encode market data for FBBL (blind scaling, secure numeric hashing). • 🛡️ Hardened boundary to FBBL through FlutterRustBridge-generated interfaces; no direct imports across repos.

🏛️ Architecture Overview +----------------+ +----------------------+ +------------------+ +----------------------+ | TipTool Peers | <--> | Ports & Factories | <--> | TipTool Core | <--> | FBBL Bridge Adapter | | (Flutter/Dart) | | (Transport/HTTP/DI) | | (CRDT Graph + | | (FRB/FFI v1 surface) | | | | | | Storage stack) | | | +----------------+ +----------------------+ +------------------+ +----------------------+

Core modules and responsibilities: Modules • Core runtime (lib/src) is Flutter-agnostic: data, CRDT, storage, networking, and FBBL bridge. • UI adapters and app-facing glue live in host apps; TipTool exposes pure Dart APIs for integration. • Generated bindings (bridge_generated.dart, ffi_bindings.dart) stay version-locked to the Rust crate.

•	`lib/src/client`: client façade (`TTClient`, `TTLink`) orchestrating graphs via injected ports/factories.
•	`lib/src/crdt`: conflict resolution (per-attribute timestamp, lexical tie-breakers, `mergeTTNodes`).
•	`lib/src/storage`: encrypted Hive persistence (`initializeTTStore`, `getStoreData`, `setStoreData`) and DTO helpers.
•	`lib/src/sea` & `lib/src/sear`: SEA-compatible auth, key generation, signing, verification, and payload unpacking.
•	`lib/src/fbbl_vector_data.dart`: candle vector builders, blind scaling, numeric hashing for FBBL payloads.
•	`lib/src/ports`: abstract contracts for transport, HTTP, logger, clock, storage, crypto, serialization, graph store/replication/merge/transport.
•	`lib/src/adapters`: production adapters (`transport/web_socket_transport_adapter.dart`, `http/dio_http_client.dart`) implementing those ports.
•	`bridge_generated.dart` & `ffi_bindings.dart`: FlutterRustBridge surface to the protected FBBL library; only place TipTool touches Rust.

🗄️ Data Model & On-Disk Layout TipTool uses an encrypted Hive box named secure-vaultBox. Records are keyed by TT “souls” (legacy GUN-style identifiers; opaque strings, e.g., asset~PETR3.SA). Each value is stored as a JSON-encoded TTNode:

{
  "_": {
    "#": "asset~PETR3.SA",
    ">": {
      "price": 1718200400123,
      "currency": 1718200400110,
      "vector": 1718200399988
    }
  },
  "price": 37.12,
  "currency": "BRL",
  "vector": [1697704800, 36.85, 37.12, 36.40, 37.50, 92837465],
  "source": "itva"
}
## ReadMe Delta (Phase 0)
- **What changed:** Introduced foundational ports (transport, storage, clock, logger, crypto, serialization) and companion factories to prepare TipTool for SOLID remediation.
- **Why safe:** Defaults delegate to existing implementations; no runtime wiring changed, storage schemas and wire formats untouched.
- **How to adopt:** Continue importing `package:tiptool/tt.dart`; optional consumers may experiment with the new ports/factories for testing without impacting production behaviour.

## ReadMe Delta (Phase 1)
- **What changed:** Core runtime now receives transports/HTTP/logging dependencies via ports and factories; WebSocket and Dio adapters ship under `lib/src/adapters`.
- **Why safe:** Defaults mirror previous behaviour (same timeouts, WebSocket wiring) while allowing downstreams to swap implementations without touching runtime code.
- **How to adopt:** Instantiate `TTClient` via `DefaultTTClientFactory` or supply custom `TTConnectorFactory`/`TTLogger`; pass `TTHttpClient` instance into `DataCollector.fetchStockData` for deterministic testing.

## ReadMe Delta (Phase 2)
- **What changed:** Split legacy `TTGraphAdapter` into focused graph ports (store, replication, merge) and slimmed `TTLink` public API while adding composer-friendly helpers.
- **Why safe:** Compatibility wrappers remain for existing adapters; default merge logic still delegates to the CRDT implementation. TTGraph transport decoupled via `GraphTransportPort`.
- **How to adopt:** Implement the new graph ports or continue using the deprecated `TTGraphAdapter` bridge; prefer `publish()/subscribe()/snapshot()` on `TTLink` going forward.

## ReadMe Delta (Phase 3)
- **What changed:** Added abstract contract tests for all ports and wired them to adapters (including Flutter-only coverage for the Hive store). Fixed an internal recursion path in `TTLink.snapshot` by routing `TTClient.getValue` through the graph layer. No public API change.
- **Why safe:** Behaviour remains identical; the fix only removes a recursion that could cause timeouts in tests. Contracts increase substitution safety without runtime changes.
- **How to adopt:** Run `dart test` for VM suites and `flutter test --tags flutter_only` for Hive adapter tests. CI merges both coverages for Phase 3 deltas.