Skip to content

docs: rewrite README and refresh contributor documentation #315

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
thisisouvik merged 1 commit into from
Sep 12, 2026
Merged

docs: rewrite README and refresh contributor documentation #315

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
63 changes: 34 additions & 29 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,39 +8,44 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
## [Unreleased]

### Added
- Collateral price oracle (#267): XLM and BTC prices polled every 5 seconds from
CoinGecko, Binance and the Stellar DEX, aggregated by median with outlier
rejection, and pushed on-chain. Fallback chain is live → cached → on-chain
TWAP → refuse to publish. The liquidation keeper now values positions with the
live price instead of a hardcoded constant. See
- Token-based design system (`app/theme.css`, `components/ui/`) with light,
dark and system themes, shared framer-motion presets and animated stat
components; landing, auth and dashboard shell rebuilt on it (#314).
- Neon Postgres + Drizzle ORM data layer with versioned migrations in
`drizzle/`, `npm run db:*` scripts and a CI migration step on `main` (#313).
- Sign-In with Stellar (SEP-10) sessions issued as signed HttpOnly cookies;
private KYC document storage on Vercel Blob (#313).
- GitHub Actions keeper workflow that triggers the liquidation keeper and price
oracle every 5 minutes, working around Vercel's daily-cron limit (#312).
- SEP-24 fiat on/off ramp integration with Stellar anchors (#309).
- Grace period before liquidations can be triggered (#308).
- Collateral price oracle (#267): XLM and BTC prices from CoinGecko, Binance
and the Stellar DEX, aggregated by median with outlier rejection and pushed
on-chain; the liquidation keeper values positions with the live price. See
[docs/oracle-price-feeds.md](docs/oracle-price-feeds.md).
- Referral programme (#266): every user gets a unique invite link, and when an
invited friend's first loan is funded the referrer's bonus is transferred
automatically by the new `referral_rewards` Soroban contract during
`activate_loan`. Includes a referral dashboard, attribution APIs, and
`sql/09_referral_program.sql`. See [docs/referral-program.md](docs/referral-program.md).
- Borrowing user guide and FAQ at `/docs/borrowing`, covering the step-by-step
borrowing process, how the liquidation threshold is calculated, Health Factor
bands, and 15 frequently asked questions. Linked from the borrower dashboard
nav and the landing footer (#265).
- Keyboard-accessible glossary tooltips for financial acronyms (APR, APY, LTV,
Trust Score, Health Factor, basis points) across the borrower, lender and
admin dashboards, backed by a shared `lib/glossary` definition list (#264).
- Initial open-source release setup.
- Basic repository files: README, LICENSE, CONTRIBUTING, CODE_OF_CONDUCT, SECURITY.
- GitHub issue and pull request templates.
- Referral programme (#266): unique invite links with the referrer's bonus paid
by the `referral_rewards` contract during `activate_loan`. See
[docs/referral-program.md](docs/referral-program.md).
- Borrowing user guide and FAQ at `/docs/borrowing` (#265) and keyboard
accessible glossary tooltips for financial terms (#264).
- Initial open-source release setup: README, LICENSE, CONTRIBUTING,
CODE_OF_CONDUCT, SECURITY, issue and pull request templates.

### Changed
- None yet.

### Deprecated
- None yet.
- README rewritten for open-source readers; rate-limiting and payment-due
scheduler details moved to `docs/rate-limiting.md` and
`docs/payment-due-scheduler.md`; roadmap and contributing guide refreshed.
- Vercel cron jobs reduced to daily schedules (Hobby plan limit) (#312).
- Hard-coded colours across dashboards replaced with theme tokens so every
screen renders in both themes (#314).

### Removed
- None yet.
- Supabase client, auth, RLS policies and SQL scripts, replaced by Neon +
Drizzle (#313).
- Dead code, the indexer stack, stale documentation and unused assets (#311).

### Fixed
- None yet.

### Security
- None yet.
- Chart area fills rendered black because a CSS variable was used as an SVG
gradient id (#314).
- Contract CI job: `usdc_lending_pool` arithmetic widths, token transfer
calls and clippy warnings (#312).
146 changes: 97 additions & 49 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,71 +1,119 @@
# Contributing to TrustLend

First off, thank you for considering contributing to TrustLend! It's people like you that make TrustLend such a great tool.
Thanks for your interest in TrustLend! This guide covers how to set up a
development environment, the conventions we follow, and how to get a change
merged. For the full local-setup walkthrough (Rust/Soroban toolchain, database,
tests) see [docs/getting-started.md](docs/getting-started.md).

## Ways to contribute

- **Report bugs** or **request features** through
[GitHub Issues](https://github.com/thisisouvik/trustlend-stellar/issues) using
the provided templates. For anything security-related, follow
[SECURITY.md](SECURITY.md) instead of opening a public issue.
- **Improve documentation** — everything under [`docs/`](docs/) and the README.
- **Write code** — frontend (Next.js / React), backend routes, or Soroban
contracts in [`contracts/`](contracts/). Issues labelled `good first issue`
are a good starting point, and the "contract only" crates listed in the README
still need frontend wiring.

Before starting on a larger change, open an issue (or comment on an existing
one) so we can agree on the approach first.

## Development setup

```bash
git clone https://github.com/<your-username>/trustlend-stellar.git
cd trustlend-stellar
git remote add upstream https://github.com/thisisouvik/trustlend-stellar.git

npm install # also installs the Husky commit hook
cp .env.example .env.local # set DATABASE_URL, SESSION_SECRET, SIWS_SERVER_SECRET
npm run db:migrate # apply Drizzle migrations to your Neon database
npm run dev # http://localhost:3000
```

## Where do I go from here?
Contract work additionally needs a Rust toolchain with the
`wasm32-unknown-unknown` target and the `stellar` CLI — see
[docs/getting-started.md](docs/getting-started.md#4-smart-contract-setup-soroban--rust).

If you've noticed a bug or have a feature request, make one! It's generally best if you get confirmation of your bug or approval for your feature request this way before starting to code.
## Branches

## Fork & create a branch
Work on a branch created from an up-to-date `main`:

If this is something you think you can fix, then fork TrustLend and create a branch with a descriptive name.
```bash
git checkout main
git pull upstream main
git checkout -b feat/short-description # or fix/…, docs/…, chore/…
```

A good branch name would be (where issue #325 is the ticket you're working on):
Rebase onto `main` (rather than merging) when you need to pick up changes.

```sh
git checkout -b 325-add-stellar-wallet-support
```
## Commit messages

## Setup Local Development
Commits must follow [Conventional Commits](https://www.conventionalcommits.org/);
a `commit-msg` hook runs commitlint and rejects anything that doesn't match.

**Option 1: Node.js (Standard)**
Make sure you have Node.js and npm installed.
```sh
npm install
npm run dev
```
<type>(<scope>): <short summary>

**Option 2: Docker Compose (Easier)**
If you prefer not to install dependencies locally, just use Docker:
```sh
docker-compose up
<optional body explaining what and why>
```

Ensure everything works correctly on your local machine at `http://localhost:3000`.

## Implement your fix or feature

At this point, you're ready to make your changes. Feel free to ask for help; everyone is a beginner at first.

## Make a Pull Request

At this point, you should switch back to your master branch and make sure it's up to date with TrustLend's master branch:

```sh
git remote add upstream git@github.com:thisisouvik/trustlend-stellar.git
git checkout master
git pull upstream master
- **Types:** `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`,
`build`, `ci`, `chore`, `revert`, plus project-specific `contract`,
`stellar` and `security`.
- **Scopes** (required): `lending`, `escrow`, `governance`,
`default-management`, `multisig-admin`, `borrower-reputation`,
`auto-compound-vault`, `treasury`, `contracts`, `frontend`, `dashboard`,
`auth`, `kyc`, `api`, `ci`, `db`, `neon`, `drizzle`, `stellar`, `soroban`,
`docs`, `deps`, `config`, `landing`, `hooks`.

Examples: `feat(lending): add early-repayment discount`,
`fix(auth): reject expired SEP-10 challenges`, `docs(contracts): document escrow revocation window`.
The complete rule set lives in [`commitlint.config.ts`](commitlint.config.ts).

## Before opening a pull request

Run the same checks CI runs:

```bash
npx tsc --noEmit # type check
npm run lint # ESLint
npm test # Vitest unit tests
npm run build # Next.js production build

# if you touched contracts/
cd contracts
cargo test
cargo clippy --all-targets -- -D warnings -A clippy::inconsistent_digit_grouping
cargo build --target wasm32-unknown-unknown --release
```

Then update your feature branch from your local copy of master, and push it!

```sh
git checkout 325-add-stellar-wallet-support
git rebase master
git push --set-upstream origin 325-add-stellar-wallet-support
```
A few conventions to keep in mind:

Finally, go to GitHub and make a Pull Request.
- Add or update tests for behaviour you change (`__tests__/` for the app,
`#[cfg(test)]` modules for contracts).
- Schema changes go through Drizzle: edit `lib/db/schema.ts`, run
`npm run db:generate`, and commit the generated migration in `drizzle/`.
- Use the design tokens in `app/theme.css` and the primitives in
`components/ui/` for UI work so both light and dark themes keep working.
- Never commit secrets. `.env.local` is git-ignored; `.env.example` documents
every variable.

## Keeping your Pull Request updated
## Pull requests

If a maintainer asks you to "rebase" your PR, they're saying that a lot of code has changed, and that you need to update your branch so it's easier to merge.
1. Push your branch to your fork and open a PR against `main`.
2. Fill in the PR template: what changed, why, how it was tested, and
screenshots for UI changes.
3. Keep PRs focused. Unrelated refactors are easier to review as separate PRs.
4. CI must pass. A maintainer will review; please respond to feedback in the
same PR rather than opening a new one.

## Merging A PR (maintainers only)
Maintainers merge a PR once it passes CI, has at least one approval, has no
outstanding change requests, and is up to date with `main`.

A PR can only be merged into master by a maintainer if:
## Code of conduct

* It is passing CI.
* It has been approved by at least one maintainer.
* It has no requested changes.
* It is up to date with current master.
This project follows the [Contributor Covenant](CODE_OF_CONDUCT.md). By
participating you agree to uphold it.
Loading
Loading