Transparent, programmable rental payments on the Stellar blockchain.
trustRent connects landlords, agents, and tenants through verifiable on-chain agreements, low-cost stablecoin payments, and escrow-protected deposits — built for emerging markets where trust is scarce and fees are high.
Overview · Architecture · How It Works · Getting Started · Smart Contracts · API Reference · Contributing
Rental markets in emerging economies face a common set of problems:
- Disputes over deposit returns with no verifiable payment history
- High fees from bank transfers, agents, and currency conversion
- Slow settlement — cross-border rent payments can take days
- No transparency — tenants have no on-chain proof of payment; landlords have no automated enforcement
trustRent solves these by doing what blockchains do best: moving money cheaply, creating verifiable records, and enforcing agreements without intermediaries — while keeping complex business logic off-chain for usability.
Built on Stellar, trustRent inherits:
| Property | Value |
|---|---|
| Settlement time | ~5 seconds |
| Average transaction fee | < $0.01 USD |
| Native stablecoin support | USDC, EURC, and custom anchored assets |
| Built-in DEX | Instant on-chain currency swaps |
| Decentralized | No single point of failure or control |
trustRent follows a deliberate on-chain / off-chain split. Not everything belongs on a blockchain.
┌─────────────────────────────────────────────────────────────┐
│ OFF-CHAIN │
│ │
│ ┌─────────────┐ ┌──────────────┐ ┌───────────────┐ │
│ │ Lease PDF │ │ e-Signature │ │ Property DB │ │
│ │ Agreement │ │ Service │ │ & Listings │ │
│ └──────┬──────┘ └──────┬───────┘ └───────┬───────┘ │
│ └─────────────────┴───────────────────┘ │
│ │ │
│ Agreement Hash (SHA-256) │
└────────────────────────────┼────────────────────────────────┘
│ anchored
▼
┌─────────────────────────────────────────────────────────────┐
│ ON-CHAIN (Stellar) │
│ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ Escrow Account │ │
│ │ - Deposit held in USDC │ │
│ │ - Multi-sig: tenant + landlord + arbitrator │ │
│ │ - Clawback on verified damage claim │ │
│ └──────────────────────────────────────────────────────┘ │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Monthly │ │ Agent Fee │ │ Payment │ │
│ │ Rent (USDC) │──▶│ Auto-split │──▶│ Receipt │ │
│ │ │ │ │ │ on Ledger │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘
1. Money on-chain. Logic off-chain. Stellar handles what it's best at: value transfer, escrow, and immutable records. Business logic (listing management, KYC, notifications, dispute UI) stays in off-chain services for scale and flexibility.
2. Trust minimization. No party needs to trust another — the escrow contract enforces deposit rules, payment receipts are verifiable by anyone, and agreement hashes are immutable.
3. Emerging market first. Designed for USDC-denominated payments that protect against local currency volatility. Low fees ($0.01/tx) make micro-payments and weekly rent schedules viable.
4. Open and extensible. The Stellar SDK is available in JavaScript, Python, Go, Java, and Rust. Any developer can build tooling, integrations, or alternative frontends on the same protocol.
| Role | Responsibilities | On-chain actions |
|---|---|---|
| Landlord | Lists property, sets rent amount and terms | Creates escrow account, receives rent, initiates deposit release |
| Agent (optional) | Manages listing, coordinates viewings | Receives auto-split commission on each rent payment |
| Tenant | Pays rent, locks deposit | Sends monthly payment, recovers deposit on lease-end |
Tenant and landlord agree on terms via the trustRent app or any off-chain channel. The final lease document is hashed (SHA-256) and the hash is written to the Stellar ledger via a MANAGE_DATA operation. Neither party can later dispute the agreed terms — the hash is permanent and timestamped.
# Example: anchoring a lease hash to Stellar
stellar tx submit --operation manage_data \
--name "trustrent:lease:2026-05" \
--value "sha256:4f2a9c...c891"Tenant sends the deposit to a Stellar escrow account controlled by a 3-of-3 multi-signature: tenant, landlord, and a neutral arbitrator (initially trustRent; roadmap includes decentralized arbitration).
// trustRent SDK — lock deposit
const escrow = await trustRent.createEscrow({
tenant: "GDKX...T7N2",
landlord: "GBML...R4KP",
arbitrator: "GCTR...W9QA",
amount: "1800",
asset: Asset.USDC,
leaseHash: "4f2a9c...c891",
leaseDurationMonths: 12,
});The deposit cannot be moved without 2-of-3 signatures. Landlords cannot abscond; tenants cannot skip out without consequence.
On (or before) the rent due date, the tenant sends a Stellar payment. If an agent is registered on the lease, the trustRent backend submits a batched transaction that splits the payment automatically using Stellar's native multi-payment operations.
Tenant sends 500 USDC
├── 465 USDC → Landlord (93%)
└── 35 USDC → Agent (7%)
Both parties receive a Stellar transaction hash as cryptographic proof of payment — no more "the bank says it went through" ambiguity.
Every payment is permanently recorded on the Stellar ledger. trustRent indexes these events and presents them as a human-readable payment history. This receipt trail is accessible to:
- Tenants (proof of payment, rental history for credit applications)
- Landlords (income verification)
- Third parties with tenant consent (lenders, future landlords)
On lease-end, one of three outcomes:
┌─────────────────────────────────────────────────────────────┐
│ OUTCOME A — Clean exit (default) │
│ Landlord + tenant both sign → deposit returns to tenant │
├─────────────────────────────────────────────────────────────┤
│ OUTCOME B — Partial deduction (agreed) │
│ Both parties sign a split: e.g. 80% tenant / 20% landlord │
├─────────────────────────────────────────────────────────────┤
│ OUTCOME C — Dispute │
│ Arbitrator reviews evidence → co-signs release decision │
│ Clawback feature used if damage proven │
└─────────────────────────────────────────────────────────────┘
- Node.js >= 18
- A Stellar account (testnet or mainnet)
- USDC balance (testnet: use Stellar Laboratory faucet)
# Clone the repository
git clone https://github.com/your-org/trustrent.git
cd trustrent
# Install dependencies
npm install
# Copy environment config
cp .env.example .env# .env
# Stellar network — "testnet" or "mainnet"
STELLAR_NETWORK=testnet
STELLAR_HORIZON_URL=https://horizon-testnet.stellar.org
# trustRent arbitrator account (defaults to testnet arbitrator)
ARBITRATOR_PUBLIC_KEY=GCTR...W9QA
ARBITRATOR_SECRET_KEY=S...
# Backend database (PostgreSQL recommended)
DATABASE_URL=postgresql://user:pass@localhost:5432/trustrent
# Off-chain signing service
SIGNING_SERVICE_URL=http://localhost:3001
# Notification webhook (optional)
WEBHOOK_URL=https://your-app.com/webhooks/trustrent# Run database migrations
npm run migrate
# Start the API server
npm run dev
# Run the Stellar event indexer (watches on-chain payment events)
npm run indexer
# Run tests
npm test
# Run tests against testnet
npm run test:testnettrustRent uses Stellar's native primitives for the current production escrow, with Soroban smart contracts implemented and tested for the v0.4 migration.
The production escrow logic is enforced by multi-signature account configuration (src/stellar/escrow.js).
Escrow Account
├── Signers
│ ├── Tenant public key (weight: 1)
│ ├── Landlord public key (weight: 1)
│ └── Arbitrator public key (weight: 1)
├── Thresholds
│ ├── Low: 1 (balance check)
│ ├── Medium: 2 (payment)
│ └── High: 2 (account merge / full release)
└── Data Entries
├── trustrent:lease (lease SHA-256 hash)
├── trustrent:tenant (tenant public key)
├── trustrent:landlord (landlord public key)
└── trustrent:lease:expires (Unix timestamp)
| Operation | Purpose |
|---|---|
CREATE_ACCOUNT |
Provision new escrow account |
SET_OPTIONS |
Configure multi-sig weights and thresholds |
MANAGE_DATA |
Anchor lease hash, store metadata |
PAYMENT |
Send rent, split agent commissions |
ACCOUNT_MERGE |
Release escrow at lease-end |
CLAWBACK |
Landlord reclaims deposit on proven damage |
The contracts/ directory contains Soroban smart contract implementations for:
- Escrow deposit lifecycle (release, split, dispute, arbitrate, clawback) — ✅ implemented & tested
- Decentralized arbitration voting (panel quorum) — ✅ implemented & tested
- Automated late-fee calculation — planned
- Scheduled recurring payments — planned
See contracts/README.md for current status.
trustRent exposes a REST API for frontend applications and third-party integrations.
POST /api/v1/leases Create a new lease
GET /api/v1/leases/:id Get lease details
PATCH /api/v1/leases/:id Update lease status
DELETE /api/v1/leases/:id Cancel lease (pre-activation only)POST /api/v1/escrow Create escrow account for a lease
GET /api/v1/escrow/:leaseId Get escrow account status
POST /api/v1/escrow/:leaseId/release Initiate deposit release
POST /api/v1/escrow/:leaseId/dispute Open a disputePOST /api/v1/payments Submit a rent payment
GET /api/v1/payments/:leaseId Get full payment history for a lease
GET /api/v1/payments/receipt/:txHash Get a single payment receiptPOST /api/v1/payments
Content-Type: application/json
Authorization: Bearer <jwt>
{
"leaseId": "lease_8f2a...",
"amount": "500.00",
"asset": "USDC",
"memo": "Rent May 2026"
}// 201 Created
{
"id": "pay_4f2a9c891",
"status": "confirmed",
"txHash": "4f2a9c...c891",
"ledger": 50234891,
"settledAt": "2026-05-01T08:12:34Z",
"splits": [
{ "recipient": "landlord", "amount": "465.00", "asset": "USDC" },
{ "recipient": "agent", "amount": "35.00", "asset": "USDC" }
]
}Full API documentation: docs/api.md
trustrent/
├── src/
│ ├── api/ # Express REST API
│ │ ├── routes/ # leases, payments, escrow, users
│ │ └── middleware/ # auth, validation, rate-limiting
│ ├── stellar/ # Stellar SDK wrappers
│ │ ├── escrow.js # Escrow account creation & management
│ │ ├── payments.js # Payment submission & splitting
│ │ └── indexer.js # On-chain event listener
│ ├── services/ # Off-chain business logic
│ │ ├── lease.js
│ │ ├── dispute.js
│ │ └── notifications.js
│ └── db/ # PostgreSQL models & migrations
│ ├── models/
│ └── migrations/
├── contracts/ # Soroban smart contracts
│ ├── escrow/ # Deposit lifecycle contract (✅ implemented)
│ └── arbitration/ # Panel voting contract (✅ implemented)
├── docs/ # Extended documentation
│ ├── api.md
│ ├── architecture.md
│ └── emerging-markets.md
├── tests/
│ ├── unit/
│ └── integration/
├── CONTRIBUTING.md
├── CHANGELOG.md
└── SECURITY.md
trustRent handles real money. Security is non-negotiable.
| Threat | Mitigation |
|---|---|
| Landlord withholds deposit | Funds locked in multi-sig escrow; requires 2-of-3 to release |
| Tenant disputes all charges | Arbitrator co-signature required; evidence documented off-chain |
| Replay attacks | Stellar sequence numbers prevent replay by design |
| Secret key compromise | Escrow accounts use multi-sig; single key compromise is non-fatal |
| API key theft | JWT with short expiry + refresh tokens; signing keys never leave server |
Found a security vulnerability? Please do not open a public GitHub issue.
Email: security@trustrent.xyz
PGP Key: docs/security/pgp-key.asc
We aim to acknowledge reports within 24 hours and patch critical issues within 72 hours.
- Escrow account creation and management
- USDC rent payments with agent fee splitting
- Lease hash anchoring on Stellar
- Payment history indexer
- REST API (leases, payments, escrow)
- Tenant-initiated deposit recovery flow
- Landlord-initiated partial deduction
- Dispute opening and resolution UI
- Email and webhook notifications
- Multi-asset support (EURC, local anchored assets)
- On-chain DEX integration for currency conversion at payment time
- Tenant pays in local currency → landlord receives USDC
- Soroban escrow contract (release, split, dispute, arbitrate, clawback)
- Decentralized arbitration voting (panel quorum)
- Automated late-fee calculation
- Scheduled recurring payments
- Mobile SDK (React Native)
- WhatsApp / USSD payment interface for feature-phone access
- Formal security audit
- Mainnet launch
trustRent is open source and contributions are welcome. We especially welcome contributors with knowledge of:
- Stellar SDK and Soroban smart contracts
- Emerging market payment systems (M-Pesa, mobile money, local stablecoins)
- Frontend development (React, React Native)
- Security engineering
# Fork and clone
git clone https://github.com/your-username/trustrent.git
# Create a feature branch
git checkout -b feat/your-feature-name
# Make changes, add tests
npm test
# Push and open a pull request
git push origin feat/your-feature-namePlease read CONTRIBUTING.md for code style guidelines, commit conventions, and the pull request process.
- All monetary values stored and transmitted as strings (never floats)
- Every Stellar operation must be tested against testnet before merge
- No external dependencies with access to private keys
- All API endpoints must have integration tests
- Stellar Development Foundation — for building infrastructure that makes this possible
- Circle — for USDC on Stellar
- The emerging market fintech community whose users this is built for
trustRent is released under the MIT License.
MIT License
Copyright (c) 2026 trustRent Contributors
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.