Skip to content

Analytics And Native Kernels

Home · Top · Table of Contents

Table of Contents

Kevin K. Le (LinkedIn) — Founder, Founding Engineer, and Current Lead Engineer; Software Engineer at the Oregon Blockchain Group, University of Oregon.

Kellen Snider — Founding Engineer; Software Engineer at the Oregon Blockchain Group, University of Oregon. His vision, ideas, and dedication during TrustLedger's Ethereum development were invaluable to the codebase we build on today.

See CREDITS.md.

TrustLedger analytics are intentionally privacy-safe. The app surfaces useful wallet-specific metrics without scraping sensitive wallet or browser data.

User-Facing Analytics

Home · Top · Table of Contents

The wallet analytics page lives at /[locale]/analytics. Connected users can open it from the wallet address hover menu in the navigation bar or from the footer Guide. The page shows a public-state badge, interactive Recharts visuals (a contract-state trend line and a client/freelancer role-mix donut), and locale diagnostics as a readable language name plus code such as English (en).

The charts are reusable, client-only wrappers in src/components/charts/ (TrendLineChart, BreakdownDonut) built on recharts. Each takes its accessible name via an ariaLabel prop (localized strings stay in the page) and is loaded with next/dynamic (ssr: false) so Recharts is excluded from the initial bundle. See CORE.md for the shared core layer the analytics event client (@/core → analytics.track) is built on.

The page reads:

  • Public TrustLedger contract state for contracts where the connected wallet is the client or freelancer.
  • Public reputation registry score and rating count.
  • Connected chain deployment metadata.
  • Safe local app preferences, such as the last connector label and dashboard guide state.

The page does not read:

  • Private keys or seed phrases.
  • Raw user documents or encrypted draft contents.
  • Emails, session keys, or magic-link tokens.
  • Hidden wallet metadata outside what wagmi/Reown exposes for the connected session.

API Endpoint

Home · Top · Table of Contents

GET /api/analytics/wallet/[address] validates the wallet address and returns privacy-boundary metadata for integrations or smoke tests.

The endpoint intentionally does not fetch third-party wallet data. It returns a deterministic public fingerprint and lists which public/local signal categories the frontend is allowed to use.

GET /api/analytics/scientific returns the generated scientific analytics manifest. It exposes the available visualization artifacts, derived public demo metrics, library coverage, and privacy boundary. It does not track real traffic or visitor behavior by itself; real traffic analytics would need explicit instrumentation, retention rules, user notice, and privacy review before deployment.

POST /api/analytics/events is the explicit privacy-respecting traffic instrumentation endpoint. It records only sanitized aggregate event names, locale, path without query strings, and timestamp when TRUSTLEDGER_ANALYTICS_ENABLED=true. It returns 204 and stores nothing when disabled or when Do Not Track / Global Privacy Control is present. GET /api/analytics/events is admin-health-gated and returns aggregate counts for operator monitoring.

The frontend beacon lives in src/components/PrivacyAnalytics.tsx and is disabled unless NEXT_PUBLIC_PRIVACY_ANALYTICS_ENABLED=true.

Python Visualizations

Home · Top · Table of Contents

Phase 6 analytics visual support lives in scripts/analytics/.

npm run analytics:generate
npm run analytics:check

The committed artifacts live under assets/analytics/:

  • wallet-analytics-preview.svg
  • wallet-analytics-report.json
  • wallet-analytics-plotly.json
  • wallet-analytics-bokeh.json

The generator uses NumPy for vectorized metrics, Pandas for tabular status data, SymPy for exact completion-rate arithmetic, SciPy for entropy, z-score, and trend statistics, Seaborn for the statistical color palette, Matplotlib for SVG rendering, Plotly for an interactive chart spec, and Bokeh for a dashboard-ready data-source spec. Matplotlib writes cache files under project-local tmp/matplotlib/ so commands do not write into the user's home directory.

Install the analytics Python dependencies with:

python3 -m pip install -r scripts/analytics/requirements.txt

Do not commit generated visuals that include private keys, seed phrases, emails, raw documents, encrypted draft bodies, or session keys.

Dune Dashboard Plan

Home · Top · Table of Contents

The roadmap now tracks a dedicated Dune dashboard integration for public on-chain metrics. Target charts include contracts created over time, total value locked, dispute rate, juror participation, appeal activity, token mix, average time to approval, warranty hold-back claims, and reputation score distributions.

Dune keys and private workspace credentials must stay out of the repository. When dashboards are published, document the dashboard URL, network, contract addresses, query date, and SQL references so whitepaper figures and public metrics are reproducible.

Native Kernels

Home · Top · Table of Contents

Optional C, C++, and assembly kernels live under native/. TrustLedger still prefers Rust for production services where memory safety matters. The native files are kept for measured bottlenecks, whitepaper analysis, and future WebAssembly or N-API experiments.

npm run native:check

The checker compiles representative C, C++, and host-architecture assembly files with clang and clang++, then writes object files to project-local tmp/native-check/. These object files are ignored and are not used by the Next.js runtime.

CI And Hooks

Home · Top · Table of Contents

The following gates keep analytics artifacts and native kernels healthy:

  • Pre-commit: duplicate scan, native:check, and analytics:check.
  • Pre-push: duplicate scan, native:check, and analytics:check.
  • GitHub Actions: dedicated Native job plus analytics asset checking in the Python job.

Authors and Contributors

Home · Top · Table of Contents

  • Kevin K. Le — Founder, Founding Engineer, and Current Lead Engineer (LinkedIn)
  • Kellen Snider — Founding Engineer (LinkedIn)

See CREDITS.md for the complete acknowledgement list.

Home · Top · Table of Contents

This document is part of TrustLedger, an open-source decentralized escrow and arbitration protocol. Use of this software and documentation is subject to the Terms and Conditions, Privacy Policy, and Risk Disclosure. See LEGAL.md for the full compliance and licensing overview.