Decentralized Buy Now Pay Later (BNPL) smart contracts on Stellar Network

Features • Tech Stack • Quick Start • Documentation • Contributing

---

📖 About

TrustUp Contracts is a suite of production-ready smart contracts powering decentralized Buy Now Pay Later (BNPL) on Stellar blockchain. Built with Rust and Soroban, it provides on-chain reputation, credit line management, merchant validation, and liquidity pool functionality.

Key Features

• ⭐ On-chain Reputation - Immutable credit scores (0-100) with admin controls
• 💰 Credit Line Management - Loan creation, repayment, and default handling
• 🏪 Merchant Registry - Whitelist of authorized merchants
• 💧 Liquidity Pool - LP deposits, withdrawals, and interest distribution
• 🔐 Access Control - Role-based permissions (admin, updaters)
• 📊 Event Emission - Complete audit trail on-chain
• 🧪 Battle-tested - Comprehensive test coverage (37+ tests)
• 🔒 Security First - Safe arithmetic, input validation, OpenZeppelin patterns

🛠 Tech Stack

RS1.75 · SSDK22 · WASM · OZ · CARGO

Core Technologies

Category	Technology	Version
Language	Rust	1.75+
SDK	Soroban SDK	22.0.0
Platform	Stellar Soroban	Mainnet
Build	Cargo	Latest
Target	wasm32-unknown-unknown	-
Security	OpenZeppelin Stellar	Main
Testing	Soroban Testutils	22.0.0

Smart Contracts

• 🌟 Stellar Network - Layer 1 blockchain
• 🔷 Soroban - WASM smart contract platform
• 🦀 Rust - Memory-safe systems language
• 📦 WASM - Portable bytecode format

📁 Project Structure

TrustUp-Contracts/
├── contracts/
│   ├── reputation-contract/     # ✅ User credit scores (0-100)
│   ├── creditline-contract/     # ⏳ Loan management
│   ├── merchant-registry-contract/ # ⏳ Merchant whitelist
│   └── liquidity-pool-contract/ # ⏳ LP management
├── docs/
│   ├── architecture/            # System architecture
│   │   ├── overview.md          # Tech stack and design
│   │   ├── contracts.md         # Contract details
│   │   └── storage-patterns.md  # Storage strategies
│   ├── standards/               # Code standards
│   │   ├── error-handling.md    # Error patterns
│   │   ├── file-organization.md # Project structure
│   │   └── code-style.md        # Rust style guide
│   ├── development/             # Dev workflows
│   │   └── README.md            # Setup and tools
│   └── resources/               # External resources
│       ├── openzeppelin.md      # OpenZeppelin tools
│       ├── stellar-soroban.md   # Stellar docs
│       └── ai-assistants.md     # MCP servers
├── target/
│   └── wasm32-unknown-unknown/
│       └── release/*.wasm       # Deployable contracts
├── Cargo.toml                   # Workspace config
├── CONTRIBUTING.md              # Contribution guide
├── PROJECT_CONTEXT.md           # Project vision
└── README.md                    # This file

🚀 Quick Start

Prerequisites

• Rust 1.75 or higher
• Cargo (included with Rust)
• wasm32-unknown-unknown target
• Stellar CLI (for deployment)

Installation

# Clone the repository
git clone https://github.com/TrustUp-app/TrustUp-Contracts.git
cd TrustUp-Contracts

# Install Rust (if not already installed)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Add WASM target
rustup target add wasm32-unknown-unknown

# Install Stellar CLI (optional, for deployment)
cargo install stellar-cli --locked

Configuration

No configuration needed for development. Contracts are stateless and configured at deployment time.

For deployment configuration, see Deployment Guide.

Running the Application

# Check compilation
cargo check

# Run tests
cargo test

# Build all contracts (native)
cargo build --release

# Build WASM for deployment
cargo build -p reputation-contract --target wasm32-unknown-unknown --release

# Output: target/wasm32-unknown-unknown/release/reputation_contract.wasm

Contract Deployment

# Deploy to testnet
stellar contract deploy \
  --wasm target/wasm32-unknown-unknown/release/reputation_contract.wasm \
  --source alice \
  --network testnet

# Initialize contract
stellar contract invoke \
  --id <CONTRACT_ID> \
  --source alice \
  --network testnet \
  -- \
  initialize --admin <ADMIN_ADDRESS>

🧪 Testing

# Run all tests
cargo test

# Run tests for specific contract
cargo test -p reputation-contract

# Run specific test
cargo test test_increase_score

# Run with output
cargo test -- --nocapture

# Check code coverage
cargo tarpaulin

📚 Documentation

Comprehensive documentation is available in the docs/ folder:

• Architecture Overview - System design and tech stack
• Contract Details - Individual contract specs
• Storage Patterns - Data management
• Error Handling - Error codes and patterns
• Code Style Guide - Rust conventions
• File Organization - Project structure
• OpenZeppelin Tools - Security libraries
• Stellar & Soroban - Platform docs
• AI Assistants & MCP - Development tools
• Contributing Guide - Development workflow
• Project Context - Vision and use cases

Contract Documentation

Each contract includes inline documentation:

# Generate and view docs
cargo doc --open

# View specific contract docs
cargo doc -p reputation-contract --open

🏗 Architecture Principles

• 🔒 Security First - Safe arithmetic, input validation, comprehensive tests
• 📊 Event-driven - All state changes emit events for indexing
• 🧩 Modular - Independent contracts with clear interfaces
• ⚡ Gas Optimized - WASM size <64KB, minimal storage operations
• ✅ Battle-tested - Extensive test coverage, OpenZeppelin patterns
• 🔗 Composable - Contracts designed for integration

🔐 Security

• Safe Arithmetic - checked_add/sub/mul/div to prevent overflow
• Input Validation - All inputs validated before processing
• Access Control - Role-based permissions (admin, updaters)
• Event Emission - Complete audit trail
• OpenZeppelin - Industry-standard security patterns
• Comprehensive Testing - 37+ tests covering edge cases

Security Checklist

• ✅ Authorization checks before state changes
• ✅ Safe arithmetic operations
• ✅ Input validation and range checks
• ✅ Event emission for all mutations
• ✅ Fail securely (panic on unexpected conditions)
• ⏳ External security audit (planned)

📦 Contracts Overview

✅ Reputation Contract (Complete)

Manages user credit scores (0-100) with role-based access control.

Status: Deployed to testnet Tests: 37 passing Functions: get_score, increase_score, decrease_score, set_admin, set_updater

⏳ CreditLine Contract (In Progress)

Handles loan creation, repayment, and default management.

Status: Partial implementation Progress: 67% complete (2/3 issues) Remaining: Loan repayment functionality

⏳ Merchant Registry (Planned)

Whitelist of authorized merchants.

Status: Not started Purpose: Validate merchants before loan creation

⏳ Liquidity Pool (Planned)

Manages LP deposits, withdrawals, and interest distribution.

Status: Not started Purpose: Fund loans and reward liquidity providers

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for:

• Development setup
• Code style guidelines
• Testing requirements
• Pull request process

Quick Contribution Guide

1. Pick an issue from Issues
2. Create branch: git checkout -b feat/SC-XX-description
3. Follow standards: Code Style
4. Write tests: Coverage goal >90%
5. Run checks: cargo fmt && cargo clippy && cargo test
6. Submit PR: Use the PR template

📊 Development Status

Current Progress: 11/20 Issues Complete (55%)

Phase	Status	Progress
Phase 1: Access Control	✅ Complete	100%
Phase 2: Reputation	✅ Complete	100%
Phase 3: CreditLine Core	⏳ Partial	67%
Phase 4: Integration	⏳ Partial	0%
Phase 5: Merchant Registry	⏳ Pending	0%
Phase 6: Liquidity Pool	⏳ Pending	0%
Phase 7: Testing	⏳ Partial	33%

See ROADMAP.md for detailed breakdown.

🙏 Acknowledgments

• Stellar Development Foundation - For the Soroban platform
• OpenZeppelin - For security standards and tools
• Rust Community - For the amazing language

📞 Support

• 📖 Documentation
• 🐛 Issue Tracker
• 💬 Discussions
• 💻 Smart Contracts
• 🌐 API Backend

---

🏆 Top 3 Contributors

🥇 @KevinMB0220 9 contributions

🥈 @Bosun-Josh121 8 contributions

🥉 @ryzen-xp 6 contributions

---

Built with ❤️ for the Stellar ecosystem