Skip to content

Credits

Home · Top · Table of Contents

Table of Contents

TrustLedger is a full-stack decentralized escrow, arbitration, and reputation system. It was originally built on Ethereum and now supports Solana and USDC, with commit-reveal arbitration, Chainlink VRF juror selection, and on-chain reputation on Sepolia.

This file acknowledges the people, technologies, and resources that make the project possible. AI agents and automation pipelines should read AGENT-CONTEXT.md before beginning any work to understand the role-specific constraints, commands, and quality gates that govern this codebase.

Authors and Contributors

Home · Top · Table of Contents

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

    Kevin co-founded TrustLedger alongside Kellen Snider and has led engineering from the project's inception through every phase of development since. As a Software Engineer at the Oregon Blockchain Group at the University of Oregon, he has driven TrustLedger beyond its Ethereum foundation — expanding the system to Solana and USDC support, building commit-reveal arbitration, Chainlink VRF juror selection, and on-chain reputation, and maintaining the full-stack platform to production as its sole contributor past the founding phase.

  • Kellen Snider — Founder and Founding Engineer (LinkedIn)

    Kellen co-founded TrustLedger and served as Founding Engineer during the project's Ethereum development phase. As a Software Engineer at the Oregon Blockchain Group at the University of Oregon, his architectural thinking, relentless attention to detail, and dedication to building trustworthy smart-contract infrastructure were instrumental in establishing the foundation this project stands on. TrustLedger would not exist in its current form without him.

Automated dependency maintenance is handled by Dependabot.

Core Technologies

Home · Top · Table of Contents

  • Next.js 16 (App Router) — React meta-framework providing file-based routing, React Server Components, API route handlers, image optimisation, and the Vercel deployment integration. All pages use the App Router; no Pages Router code exists.
  • React 19 — UI runtime. Uses the latest concurrent features, use hooks, and server-component patterns.
  • TypeScript 6 — strict, type-safe language for all frontend, Hardhat, and tooling code. Configured via @tsconfig/strictest with no any escape hatches.
  • Tailwind CSS v4 — utility-first CSS framework used as the single source of design tokens (colour, spacing, typography). Processed via @tailwindcss/postcss.
  • Sass — supplementary SCSS for global styles and animations not expressible in Tailwind utilities.
  • Solidity 0.8.24 — smart-contract language. Compiled with via_ir = true, optimizer_runs = 200, and deny = "warnings".
  • Foundry — primary smart-contract toolchain: forge build, forge test, forge script, forge lint, forge fmt. Fuzz suite runs 10 000 iterations with a fixed seed.
  • Hardhat v3 — secondary toolchain used for TypeScript deployment scripts, local Hardhat Network node, and Mocha integration tests via @nomicfoundation/hardhat-mocha.

Frontend Libraries

Home · Top · Table of Contents

Wallet and Chain

Home · Top · Table of Contents

  • wagmi v2 — React hooks for EVM wallet connection, contract reads/writes, and chain switching. The primary interface between the UI and on-chain state.
  • viem v2 — low-level, type-safe Ethereum client. Handles ABI encoding, RPC calls, and signature verification. Used both client-side (with wagmi) and server-side (in API route handlers).
  • Reown AppKit (@reown/appkit, @reown/appkit-adapter-wagmi) — wallet connection modal (successor to WalletConnect's Web3Modal). Supports MetaMask, WalletConnect, Coinbase Wallet, and others.
  • @solana/web3.js v1 — JavaScript SDK for Solana RPC interaction and transaction construction, used by the Solana escrow integration.

Data Fetching and State

Home · Top · Table of Contents

  • @tanstack/react-query v5 — server-state caching, background refetching, and optimistic updates. All on-chain data queries flow through React Query.

UI and Visualisation

Home · Top · Table of Contents

  • recharts v3 — composable charting library built on D3. Used in the analytics dashboard. Code-split via Next.js dynamic() to keep the main bundle lean.

Internationalisation

Home · Top · Table of Contents

  • next-intl v4 — locale routing, message formatting, and server-component i18n for the App Router. All user-facing strings live in messages/.

Theming

Home · Top · Table of Contents

  • next-themes v0.4 — flicker-free dark/light theme switching with system preference detection.

Email

Home · Top · Table of Contents

  • Resend v6 — transactional email API. Used by the magic-link and notification API routes.

Storage

Home · Top · Table of Contents

  • Arweave — permanent, decentralised document storage. Contract documents can optionally be archived to Arweave after on-chain creation.

Smart-Contract Libraries

Home · Top · Table of Contents

  • OpenZeppelin Contracts v5 — industry-standard audited base contracts. TrustLedger uses Ownable, Pausable, ReentrancyGuard, IERC20, and IERC20Metadata. Vendored under contracts/lib/openzeppelin-contracts/ via Foundry and installed as an npm package (@openzeppelin/contracts) for Hardhat.
  • forge-std — Foundry's standard testing library. Provides Test, Vm, console, script base contracts, and common assertion helpers. Vendored under contracts/lib/forge-std/.
  • Chainlink VRF — verifiable random function used for provably fair juror selection. The VRFConsumerBaseV2 interface is vendored directly in contracts/src/interfaces/ to avoid an npm dependency on the full Chainlink suite.
  • AggregatorV3Interface (Chainlink Data Feeds) — price-feed interface vendored in contracts/src/interfaces/AggregatorV3Interface.sol. Used by the oracle layer to read ETH/USD prices on Sepolia.

Rust and Solana Program

Home · Top · Table of Contents

The Solana escrow program lives in programs/solana-escrow/ and is compiled with cargo build-sbf. All unsafe code is forbidden at the crate level.

  • solana-program v4 — core Solana on-chain program SDK: account info, instruction handling, and system program cross-program invocations.
  • solana-sdk-ids v3 — canonical program ID constants (system program, token program, etc.).
  • solana-system-interface v3 — typed bindings for the Solana System Program instructions (create account, transfer lamports) with the bincode feature enabled.

Rust toolchain constraints:

  • Minimum Rust version: 1.89 (declared in Cargo.toml).
  • All Clippy lints are denied at pedantic level. unwrap_used, expect_used, and panic are individually denied. Write explicit error handling with ?.
  • missing_docs is denied — all public items must have doc comments.

Python Utilities and AI

Home · Top · Table of Contents

Python is used for three purposes: contract PDF generation, GitHub Models AI integration, and analytics generation.

Contract PDF Generation (utils/)

Home · Top · Table of Contents

  • ReportLab 4.4.10 — PDF layout and rendering engine. Used by utils/generate_contract.py to produce sample-contract.pdf, a dummy freelance service agreement used in TrustLedger demos. The PDF is uploaded to IPFS and its keccak256 hash is stored on-chain as contractHash.
  • types-reportlab — PEP 561 type stubs for ReportLab, enabling mypy and Pylance to resolve types.

GitHub Models AI Integration (scripts/models/)

Home · Top · Table of Contents

  • azure-ai-inference — Azure AI Inference SDK. Provides ChatCompletionsClient and message types for calling the GitHub Models inference endpoint (https://models.github.ai/inference).
  • azure-core — Azure SDK core utilities: AzureKeyCredential and HttpResponseError.
  • Requires GITHUB_TOKEN with models access. Run via npm run models:run or the github-models.yml workflow.

Analytics Generation (scripts/analytics/)

Home · Top · Table of Contents

  • NumPy 2.4 — numerical array operations.
  • pandas 2.3 — tabular data manipulation and aggregation for wallet analytics.
  • Matplotlib 3.10 — static chart generation.
  • Seaborn 0.13 — statistical visualisation built on Matplotlib.
  • Plotly 6.5 — interactive HTML charts.
  • Bokeh 3.8 — interactive web-based visualisations.
  • SciPy 1.16 — scientific computing (statistical distributions, signal processing).
  • SymPy 1.14 — symbolic mathematics.

Type Checking

Home · Top · Table of Contents

  • mypy — strict static type checker for all Python scripts (utils/generate_contract.py, scripts/models/github_models.py, scripts/analytics/generate_wallet_analytics.py). Run via npm run lint:py.

Documentation Build

Home · Top · Table of Contents

  • MkDocs ≥1.6, <2 — static site generator that transforms docs/*.md into the GitHub Pages site at https://kevinle3212.github.io/TrustLedger.
  • Material for MkDocs ≥9.6, <9.7 — Material Design theme with search, navigation tabs, code annotations, and dark mode. Run npm run docs:build (enforces --strict).

Tooling and Quality

Home · Top · Table of Contents

Linting and Formatting

Home · Top · Table of Contents

  • ESLint v9/v10 — JavaScript and TypeScript linting. The root workspace uses flat config (eslint.config.mjs) at v10; the frontend uses v9 with eslint-config-next. Both run at zero-warning tolerance.
  • typescript-eslint v8 — TypeScript-aware ESLint rules. Enables type-informed linting across all TS files.
  • Prettier v3 — opinionated code formatter. Covers TypeScript, JavaScript, JSON, YAML, Markdown, and SCSS. Run with npm run lint:prettier or npm run fix:prettier.
  • eslint-config-prettier — disables ESLint rules that conflict with Prettier formatting.
  • Solhint v6 — Solidity linter. Runs with --max-warnings 0 on all .sol files.
  • Stylelint v17 with stylelint-config-standard-scss — CSS/SCSS linter for src/app/**/*.{css,scss}.
  • markdownlint-cli2 — Markdown linter applied to all *.md files. Prose line limit: 80 characters. Configuration in .markdownlint.json. Run with npm run lint:md.
  • Knip v6 — dead-code and unused-dependency detector. Covers both the root workspace and src/. Run with npm run lint:knip.

Testing

Home · Top · Table of Contents

  • Jest v30 with jest-environment-jsdom — unit test runner for the frontend. Run with npm run test:unit. Coverage report via npm run test:coverage.
  • @testing-library/react v16 — component testing utilities that query the DOM the way a user would.
  • @testing-library/jest-dom v6 — custom Jest matchers for DOM state assertions (.toBeInTheDocument(), etc.).
  • Playwright v1.60 — end-to-end browser automation and testing. Headless Chromium is the primary target. Run with npm run test:e2e.
  • @axe-core/playwright — automated accessibility assertions integrated into every Playwright test. Catches WCAG violations at test time.
  • Mocha (via @nomicfoundation/hardhat-mocha) — test runner for Hardhat TypeScript tests. Run with npm run hardhat:test.

React Health

Home · Top · Table of Contents

  • React Doctor v0.5 — React codebase health analyser. Checks for anti-patterns, accessibility issues, and bundle quality. Score must stay at 100/100. Run with npm run doctor.
  • React Scan v0.5 — runtime performance profiler. Highlights unnecessary re-renders in the browser. Active automatically in NODE_ENV=development.

Smart-Contract Quality

Home · Top · Table of Contents

  • Foundry forge fmt — canonical Solidity formatter (configuration in foundry.toml [fmt] section). Run with npm run lint:forge.
  • Foundry forge lint — Solidity static analyser built into Foundry. Runs at all severity levels with zero exclusions.
  • Foundry fuzzing — property-based testing baked into forge test. 10 000 fuzz runs per test with a fixed seed (0x1).
  • Slither — Trail of Bits static analyser for Solidity. Catches reentrancy, integer overflow, and common vulnerability patterns. Run separately before contract PRs.

Security Scanning

Home · Top · Table of Contents

  • Semgrep — multi-language static analysis. Runs in CI via .github/workflows/security.yml on every PR. False positives require a # nosemgrep: <rule-id> comment with justification.
  • Gitleaks — secret scanner. Checks the full git history and staged changes. Configuration in .gitleaks.toml. Run via npm run secrets:check or the pre-push hook.
  • CodeRabbit — AI-powered automated code review on every PR. Configuration in .coderabbit.yaml.

Commit and Release Hygiene

Home · Top · Table of Contents

  • Husky v9 — Git hooks manager. The pre-commit hook runs React Doctor --staged and the full lint suite. Never bypass with --no-verify.
  • commitlint (@commitlint/cli, @commitlint/config-conventional) — enforces Conventional Commits format (feat:, fix:, chore:, etc.) on every commit message.

Type Generation

Home · Top · Table of Contents

  • TypeChain (via @nomicfoundation/hardhat-typechain) — generates TypeScript typings from compiled Solidity ABI artefacts. Output lives in typechain-types/.

Dependency Management

Home · Top · Table of Contents

  • Dependabot — automated pull requests for npm and GitHub Actions dependency updates. Configuration in .github/dependabot.yml.

Environment and Secrets

Home · Top · Table of Contents

  • dotenv — loads .env into process.env for Hardhat scripts and tooling.
  • tools/sync-env-defaults.mjs — syncs .env values to .env.example (safe defaults only, no secrets). Run with npm run env:sync.
  • tools/sync-vercel-env.mjs — pushes local environment to Vercel project settings. Run with npm run env:sync:vercel.

Code Intelligence

Home · Top · Table of Contents

  • @costline/nexus-graph — symbol-level dependency graph and MCP server for code navigation. Index with npm run nexus:index; serve with npm run nexus:server.

DevOps and Infrastructure

Home · Top · Table of Contents

  • Vercel — frontend hosting, preview deployments, and production promotion. The src/ directory is the Vercel project root. Deployments are triggered by .github/workflows/deploy.yml.
  • Docker — containerisation for the frontend runtime and local service dependencies. docker/ contains the Dockerfile; docker-compose.yml wires up the local service stack.
  • Kubernetes — container orchestration for production deployments. Manifests live in k8s/ and are managed with Kustomize. Validated with npm run lint:k8s.
  • GitHub Actions — CI/CD automation. Workflows in .github/workflows/:
    • ci.yml — lint, type-check, test, and build on every PR.
    • security.yml — Semgrep, CodeQL, and dependency audit.
    • deploy.yml — Vercel production promotion on merge to main.
    • docs.yml — MkDocs build and GitHub Pages publish.
    • github-models.yml — scheduled AI integration scenario runs.
    • react-doctor.yml — React Doctor health check on frontend changes.
    • dependabot-automerge.yml — auto-merge safe Dependabot patches.
    • wiki-sync.yml — syncs docs/ to the GitHub Wiki.
    • log-hygiene.yml — enforces logs/ retention policy.

License

Home · Top · Table of Contents

TrustLedger is released under the Apache License 2.0. See LICENSE for the full text. Third-party dependencies remain under their respective licenses.

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.