Skip to content

Contributing

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.

This document explains how to set up the repository, make changes, and pass the required checks. Read it before opening a pull request.

Setup

Home · Top · Table of Contents

Use the bootstrapper for a guided setup with selectable install groups:

bash tools/setup.sh --help
bash tools/setup.sh

For manual setup, install root dependencies:

npm install

npm install runs a postinstall step (patch-package) that reapplies the tracked patches under patches/. These patch local-only fixes into dependencies — currently @costline/nexus-graph, whose code-graph indexer is adjusted to skip generated output (site/, .next/). Do not run installs with --ignore-scripts, or the patches will not apply.

Root package.json includes @openzeppelin/contracts because Hardhat, TypeScript scripts, and npm-based tooling resolve OpenZeppelin through Node. Foundry test helpers are different: forge-std is vendored under contracts/lib/forge-std and is intentionally not an npm package. Keep that split unless the contract import strategy is deliberately changed.

Install frontend dependencies:

cd src
npm install
cd ..

Create local environment files only when you need deployment, fork tests, wallet connection, email, notifications, or IPFS:

cp .env.example .env

Read Environment before filling secrets.

Serena Dashboard

Home · Top · Table of Contents

Serena's dashboard remains enabled for local code navigation logs, but it should not open automatically on startup. Configure this globally in ~/.serena/serena_config.yml:

web_dashboard: true
web_dashboard_open_on_launch: false

Open the dashboard manually at http://localhost:24282/dashboard/. If that port is already in use, Serena may choose the next available port, such as 24283 or 24284.

Development Workflow

Home · Top · Table of Contents

Use small branches and keep generated build output out of commits. The repository ignores normal build artifacts such as artifacts/, contracts/out/, contracts/cache/, src/.next/, and src/node_modules/. The root site/ directory is MkDocs generated output and remains ignored; edit source pages in docs/ instead.

Before opening a PR, run the relevant checks:

npm run secrets:check
npm run docs:nav:check
npm run logs:check
npm run lint
npm run foundry:test
npm run hardhat:test
cd src
npm run build:frontend
npm run test:e2e

Run narrower checks while iterating. Read Testing for the full command list.

npm run secrets:check requires gitleaks on PATH and scans git history with redacted output. Install it with brew install gitleaks on macOS or from the Gitleaks releases on Linux. Use npm run secrets:gitleaks:staged to reproduce the pre-commit staged-diff scan. Prefer exact .gitleaks.toml allowlists for stable public constants, scoped to the value, rule, and file. Keep .gitleaksignore limited to historical findings that cannot be safely represented in config; do not add broad allowlists for source paths or secret-like values.

Solidity Style

Home · Top · Table of Contents

Solidity is checked by both Solhint and Foundry:

npm run lint:sol
npm run lint:forge

contracts/foundry.toml uses Solidity 0.8.24, optimizer runs 200, via_ir = true, and deny = "warnings". Keep contract comments useful and avoid changing logic when a task is only about documentation or NatSpec.

TypeScript Style

Home · Top · Table of Contents

Root TypeScript covers Hardhat config, scripts, and tests:

npm run lint:ts

Frontend TypeScript and formatting run from src/:

cd src
npm run lint:frontend

Markdown Style

Home · Top · Table of Contents

Run:

npm run lint:md
npm run docs:nav:check

Use one H1 at the top of each file, ATX headings, fenced code blocks with language tags, no bare URLs, and prose lines around 100 characters where practical.

Every Markdown file under docs/ has generated GitHub navigation with links back to Home, page top, and the page table of contents. Run npm run docs:nav after changing headings, then verify with npm run docs:nav:check.

Ignored files under logs/ should still be readable Markdown summaries, but commit and push hooks do not markdownlint ignored log files. Use:

npm run logs:check
npm run tmp:check

Run npm run logs:prune when local logs exceed retention limits. Run npm run tmp:prune when project-local scratch files exceed retention limits. Pre-push also runs npm run docker:storage:prune, which prunes unused Docker images, volumes, networks, and build cache only when Docker reports storage above the configured threshold.

Documentation Ownership

Home · Top · Table of Contents

Prefer these canonical docs:

When a fact belongs in a canonical doc, link to that doc instead of copying the same explanation into another page.

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.