QuorumCredit — Proof of Trust (PoT) Microlending

Trustless microlending powered by your social trust graph — built on Stellar Soroban.

Platform: Stellar Soroban | Language: Rust | License: MIT

---

About

QuorumCredit is a decentralized microlending platform that replaces asset collateral with social collateral. Inspired by Stellar's Federated Byzantine Agreement (FBA), it lets communities vouch for borrowers using staked XLM — no over-collateralization required.

Traditional DeFi lending demands $100 locked up to borrow $50. QuorumCredit flips this: your trust network is your collateral. Vouchers stake XLM to back a borrower. If the loan is repaid, vouchers earn yield. If the borrower defaults, vouchers are slashed.

This platform is designed for developers building on Stellar, fintech teams targeting underserved communities, and anyone exploring social-trust-based credit systems.

---

Table of Contents

• Quick Start
• How It Works
• Project Structure
• Setup Instructions
• Testing
• Deployment
• Architecture
• Contributing

---

Quick Start

# Clone the repository
git clone https://github.com/your-org/QuorumCredit.git
cd QuorumCredit

# Build the contract
cd QuorumCredit
cargo build --target wasm32-unknown-unknown --release

# Run tests
cargo test

---

How It Works

1. Vouching

Users stake XLM to vouch for a borrower in their network. This stake is transferred into the contract and held as social collateral.

2. Loan Eligibility

A borrower becomes eligible once their total vouched stake meets the minimum threshold — no personal collateral needed.

3. Repayment & Default

Outcome	Borrower	Vouchers
Loan repaid ✅	Debt cleared, credit history improves	Earn 2% yield on staked XLM
Default ❌	Flagged, future borrowing restricted	50% of stake slashed

Minimum stake for yield: A vouch must be at least 50 stroops to earn non-zero yield. At the default 2% rate (200 bps), stake * 200 / 10_000 truncates to zero for any stake under 50 stroops. The contract enforces this minimum in vouch() and rejects smaller stakes with a clear error rather than silently paying no yield.

The FBA Inspiration

Stellar nodes select their own Quorum Slice — a trusted subset of peers. QuorumCredit mirrors this: each borrower's eligibility is determined by their personal trust graph, not a central credit bureau. You aren't trusting a bank; you're trusting a specific slice of your social network.

---

Project Structure

QuorumCredit/
├── QuorumCredit/
│   ├── Cargo.toml          # Contract crate (Soroban SDK)
│   └── src/
│       └── lib.rs          # Contract: initialize, vouch, request_loan, repay, slash
├── Cargo.toml              # Workspace root
└── README.md               # This file

Key contract entry points:

Function	Description
initialize(deployer, admin, token)	One-time setup — deployer must sign; sets admin and XLM token address
vouch(voucher, borrower, stake)	Stake XLM to back a borrower
request_loan(borrower, amount, threshold)	Disburse loan if stake threshold is met
repay(borrower)	Repay loan; vouchers receive 2% yield
slash(borrower)	Admin marks default; 50% of voucher stakes burned
get_loan(borrower)	Read a borrower's active loan record
get_vouches(borrower)	Read all vouches for a borrower

---

🛡️ Access Control Matrix

Function	Role Required	Description	Impact
initialize	Deployer	One-time setup of Admin and Token addresses.	Sets security foundation.
vouch	Voucher	Stake XLM to back a borrower.	Increases borrower trust score.
request_loan	Borrower	Withdraw loan funds to borrower wallet.	Disburses capital.
repay	Borrower	Clear debt and distribute yield to vouchers.	Restores trust and rewards vouchers.
slash	Admin	Signal default and burn 50% of voucher stakes.	Penalizes default; enforces risk.
get_loan	Anyone	Read active loan records.	Transparency.
get_vouches	Anyone	Read voucher lists for a borrower.	Transparency.

---

Setup Instructions

Requirements

• Rust (latest stable)
• Stellar CLI (stellar-cli)
• A Stellar account (for deployment)

1. Install Rust

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
rustup target add wasm32-unknown-unknown

2. Install Stellar CLI

cargo install --locked stellar-cli
stellar --version

3. Configure Networks

# Testnet (recommended for development)
stellar network add testnet \
  --rpc-url https://soroban-testnet.stellar.org:443 \
  --network-passphrase "Test SDF Network ; September 2015"

# Mainnet
stellar network add mainnet \
  --rpc-url https://rpc.mainnet.stellar.org:443 \
  --network-passphrase "Public Global Stellar Network ; September 2015"

4. Environment Variables

Create a .env file (never commit this):

NETWORK=testnet
DEPLOYER_SECRET_KEY="SB..."   # Your deployer secret key
ADMIN_ADDRESS="GB..."         # Admin account address
TOKEN_CONTRACT="..."          # XLM token contract address

⚠️ Add .env to your .gitignore. Never commit secret keys.

---

Testing

# Run all tests
cd QuorumCredit
cargo test

# Run with output
cargo test -- --nocapture

# Run a specific test
cargo test test_repay_gives_voucher_yield

Test coverage:

Test	Verifies
test_vouch_and_loan_disbursed	Loan record created, funds transferred to borrower
test_repay_gives_voucher_yield	Voucher receives original stake + 2% yield
test_slash_burns_half_stake	Voucher loses 50% of stake on default
test_unauthorized_initialize_rejected	initialize panics when called without deployer's signature

---

Deployment

Security: Deployer-Gated Initialization

initialize requires the deployer address to sign the transaction (deployer.require_auth()). This closes the front-running window that exists between contract deployment and initialization:

1. An attacker observing the deployment transaction on-chain cannot call initialize first — they cannot forge the deployer's signature.
2. The deployer address is stored in contract storage (DataKey::Deployer) for auditability.

Required deployment sequence — do not deviate:

Step 1: Build the WASM
Step 2: Deploy the contract  ← deployer keypair signs this tx
Step 3: Initialize the contract ← SAME deployer keypair must sign this tx

If steps 2 and 3 are not signed by the same keypair, initialize will panic and the contract remains uninitialized.

Deploy to Testnet

# Build
cargo build --target wasm32-unknown-unknown --release

# Step 1 — Deploy (note the returned CONTRACT_ID)
stellar contract deploy \
  --wasm target/wasm32-unknown-unknown/release/quorum_credit.wasm \
  --network testnet \
  --source $DEPLOYER_SECRET_KEY

# Step 2 — Initialize immediately after deploy, using the SAME source key
# deployer = the account that signed the deploy tx above
stellar contract invoke \
  --id $CONTRACT_ID \
  --fn initialize \
  --network testnet \
  --source $DEPLOYER_SECRET_KEY \
  -- \
  --deployer $DEPLOYER_ADDRESS \
  --admin $ADMIN_ADDRESS \
  --token $TOKEN_CONTRACT

The --source key for invoke must match --deployer. Using any other key will cause require_auth() to reject the call.

Deploy to Mainnet

⚠️ Production checklist before deploying:

• All tests passing
• Security audit completed
• Testnet deployment verified
• Admin keys secured (multisig recommended)
• Token contract address confirmed

stellar contract deploy \
  --wasm target/wasm32-unknown-unknown/release/quorum_credit.wasm \
  --network mainnet \
  --source $DEPLOYER_SECRET_KEY

Upgrading the Contract

The upgrade function allows the admin (or multisig quorum) to replace the contract WASM after deployment. This is the only path to patching a live vulnerability.

Upgrade process:

Step 1: Build the new WASM
Step 2: (Recommended) Pause the contract to halt user activity
Step 3: Upload the new WASM and obtain its hash
Step 4: Call upgrade() — requires admin_threshold signatures
Step 5: Unpause the contract

# Step 1 — Build
cargo build --target wasm32-unknown-unknown --release

# Step 2 — Pause (recommended)
stellar contract invoke \
  --id $CONTRACT_ID --fn pause --network testnet --source $ADMIN_SECRET_KEY \
  -- --admin_signers '["'$ADMIN_ADDRESS'"]'

# Step 3 — Upload new WASM, capture the returned hash
NEW_WASM_HASH=$(stellar contract install \
  --wasm target/wasm32-unknown-unknown/release/quorum_credit.wasm \
  --network testnet \
  --source $ADMIN_SECRET_KEY)

# Step 4 — Upgrade (admin_threshold admins must sign)
stellar contract invoke \
  --id $CONTRACT_ID --fn upgrade --network testnet --source $ADMIN_SECRET_KEY \
  -- \
  --admin_signers '["'$ADMIN_ADDRESS'"]' \
  --new_wasm_hash $NEW_WASM_HASH

# Step 5 — Unpause
stellar contract invoke \
  --id $CONTRACT_ID --fn unpause --network testnet --source $ADMIN_SECRET_KEY \
  -- --admin_signers '["'$ADMIN_ADDRESS'"]'

⚠️ The upgrade call requires admin_threshold distinct admin signatures — the same multisig quorum used for all other admin operations. A single compromised key cannot unilaterally upgrade the contract.

---

Architecture

Borrower
   └── requests loan
         └── Trust Circle (Quorum Slice)
               ├── Voucher A — stakes XLM
               ├── Voucher B — stakes XLM
               └── Voucher C — stakes XLM
                     └── Threshold met → Loan disbursed
                           ├── Repaid → Vouchers earn 2% yield
                           └── Default → 50% of stakes slashed

Key concepts:

• Proof of Trust (PoT): Social collateral replaces asset collateral
• Quorum Slice: Your personal set of trusted vouchers, mirroring FBA logic
• Slash Mechanism: Vouchers lose 50% of stake on borrower default — aligning incentives
• Yield on Trust: Vouchers earn 2% yield for backing reliable borrowers

Why Stellar?

• Near-zero transaction fees — critical for microlending viability
• Fast finality (~5s) — practical for real-world loan cycles
• Soroban smart contracts — expressive enough for trust graph logic
• Native XLM — no bridging complexity for staking and disbursement

---

💰 Yield Accounting & Solvency

QuorumCredit uses a Sustainable Pre-funding Model for yield distribution. Unlike many DeFi protocols, yield is not "minted" into existence, ensuring no inflationary pressure on the underlying XLM asset.

Funding Source

Yield is sourced from a dedicated Yield Reserve within the contract. For vouchers to earn their 2% yield (YIELD_BPS = 200), the contract must be pre-funded by the protocol admin or through external revenue streams (e.g., protocol fees).

Important

The contract must hold sufficient XLM to cover both the principal repayment and the 2% yield. If the reserve is empty, the protocol cannot disburse rewards.

Solvency & "Hard-Cap" Logic

To ensure the protocol never owes more than it holds, a Hard-Cap Solvency model is enforced:

1. Reserve Check: The protocol only allows loan disbursement if the contract has sufficient liquidity to cover the loan amount.
2. Yield Protection: If the Yield Reserve is depleted, the $2.0%$ yield accrual effectively halts. In the current implementation, any attempt to pay out yield without sufficient funds will trigger a Soroban InsufficientFunds panic, protecting the protocol's integrity.

Yield Flow Diagram

graph LR
    A[Admin/Revenue Source] -->|Pre-funds| B(Yield Reserve)
    B -->|Allocates| C{Yield Accrual}
    C -->|Repayment Event| D[Voucher Stake + 2% Yield]
    D -->|Withdrawal| E(User Wallet)

Loading

Contributing

Contributions are what make the open-source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

Please refer to CONTRIBUTING.md for our full guidelines on:

• Branch naming conventions
• Commit message formats (Conventional Commits)
• Pull Request workflow
• Testing and Style guides

---

Roadmap

• Core vouching & slashing contract (Soroban)
• Real XLM token transfers via Soroban token interface
• Yield distribution on repayment
• Admin-gated slash with auth enforcement
• Borrower credit scoring based on repayment history
• Trust graph visualization (frontend)
• Multi-asset loan support (USDC on Stellar)
• Mobile-first UI for underserved communities

---

Security

• Never commit .env files or secret keys
• Use hardware wallets or multisig for admin keys
• Report vulnerabilities privately — do not open public issues

---

License

MIT

---

Resources

• Stellar Documentation
• Soroban Docs
• Stellar Developer Discord