Skip to content

README.md

Latest commit

 

History

History
298 lines (221 loc) · 9.33 KB

README.md

File metadata and controls

298 lines (221 loc) · 9.33 KB

Kora Protocol

On-chain Invoice Financing for African Trade Finance

License: MIT Built on Stellar Rust

Tokenize unpaid invoices. Unlock instant liquidity. Power African trade.

Overview

Kora is a decentralized invoice financing protocol built on Stellar Soroban. It enables small and medium enterprises (SMEs) — particularly across African markets — to tokenize their unpaid invoices as NFTs and sell them at a discount to liquidity providers, receiving immediate working capital without waiting 30–90 days for invoice settlement.

The protocol is designed for:

  • African trade finance infrastructure — addressing the $81B+ SME financing gap on the continent
  • Institutional DeFi — production-grade contract architecture with formal access control and risk scoring
  • Real-world asset (RWA) tokenization — invoices as on-chain NFTs with IPFS-backed metadata
  • Scalable fintech rails — modular contracts that can be extended for factoring, supply chain finance, and trade credit

How It Works

SME                    Marketplace              Investors
 │                         │                       │
 │── mint_invoice() ──────►│                       │
 │                         │── list_invoice() ────►│
 │                         │                       │── fund_invoice()
 │                         │◄──────────────────────│
 │◄── funds released ──────│                       │
 │                         │                       │
 │── repay() ─────────────►│                       │
 │                         │── distribute yield ──►│
  1. SME mints an invoice NFT — invoice metadata (amount, debtor, due date, IPFS CID) is stored on-chain. Sensitive debtor PII is hashed; full details live on IPFS.
  2. Invoice is listed on the marketplace — SME sets an asking price (discounted from face value) and a funding deadline.
  3. Investors fund the invoice — partial funding is supported. The marketplace collects a protocol fee on each contribution.
  4. Funds are released to the SME — once fully funded, the financing pool releases net proceeds to the SME.
  5. SME repays the face value — on or before the due date.
  6. Investors receive principal + yield — the spread between the discounted price paid and the face value repaid is the investor's return.
  7. Defaults are handled on-chain — if the SME fails to repay, the admin can mark the invoice as defaulted and distribute any partial recovery to investors.

Contract Architecture

Contract Responsibility
invoice_nft Mints and manages invoice NFTs. Owns the canonical invoice state machine.
marketplace Lists invoices, accepts investor funding, collects fees, triggers pool release.
financing_pool Holds investor funds, tracks positions, distributes repayments and yield.
treasury Accumulates protocol fees. Admin-controlled withdrawal.
risk_registry Verifier-managed SME and debtor risk scoring.
access_control Protocol-wide pause/unpause, role management, admin transfer.
shared Common types, errors, events, and validation utilities.

See ARCHITECTURE.md for a detailed breakdown.

Project Structure

Kora-Contract/
├── Cargo.toml                    # Workspace root
├── Makefile                      # Build, test, deploy targets
├── contracts/
│   ├── shared/                   # Shared types, errors, events, validation
│   ├── invoice_nft/              # Invoice NFT contract
│   ├── marketplace/              # Marketplace contract
│   ├── financing_pool/           # Financing pool contract
│   ├── treasury/                 # Treasury/fee contract
│   ├── risk_registry/            # Risk registry contract
│   ├── access_control/           # Access control contract
│   └── tests/                    # Integration test suite
├── scripts/
│   ├── deploy.sh                 # Full deployment script
│   └── interact.sh               # Shell helpers for contract interaction
├── deployments/                  # Generated deployment manifests (gitignored)
└── docs/
    ├── ARCHITECTURE.md
    ├── CONTRACTS.md
    └── SECURITY.md

Getting Started

Prerequisites

# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

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

# Install stellar CLI
cargo install stellar-cli --locked

Build

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

# Build all contracts
make build

# Build and optimize WASM binaries
make build-optimized

Test

# Run all unit and integration tests
make test

# Run with output
make test-verbose

Lint

make fmt    # Format code
make lint   # Run clippy (warnings as errors)
make check  # Type-check without building

Deployment

Testnet

export DEPLOYER_SECRET="your-stellar-secret-key"
make deploy-testnet

This will:

  1. Build and optimize all WASM binaries
  2. Deploy each contract to Stellar testnet
  3. Initialize all contracts with correct cross-contract references
  4. Write a deployment manifest to deployments/testnet.json

Mainnet

export DEPLOYER_SECRET="your-stellar-secret-key"
make deploy-mainnet

Mainnet deployment requires manual confirmation at the prompt.

Example Interactions

After deployment, load the interaction helpers:

source scripts/interact.sh testnet

Register a verifier and SME:

kora_add_verifier "$ADMIN_ADDRESS" "$VERIFIER_ADDRESS"
kora_register_sme "$VERIFIER_ADDRESS" "$SME_ADDRESS" 35

Mint an invoice:

kora_mint_invoice \
  "$SME_ADDRESS" \
  "abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890" \
  10000000000 \
  "USDC" \
  1780000000 \
  "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi" \
  30

List the invoice:

kora_list_invoice "$SME_ADDRESS" 1 9500000000 10000000000 "$USDC_TOKEN" 1750000000

Fund the invoice (investor):

kora_fund_invoice "$INVESTOR_ADDRESS" 1 4750000000

Repay:

kora_repay "$SME_ADDRESS" 1 "$USDC_TOKEN" 10000000000

Query state:

kora_get_invoice 1
kora_get_pool 1
kora_get_sme_profile "$SME_ADDRESS"

Invoice NFT Data Model

pub struct Invoice {
    pub id: u64,
    pub sme: Address,
    pub debtor_hash: Bytes,    // SHA-256 of debtor info — PII stays off-chain
    pub amount: i128,          // Face value in stroops (7 decimal places)
    pub currency: Symbol,      // e.g. USDC, EURC
    pub due_date: u64,         // Unix timestamp
    pub ipfs_cid: String,      // IPFS CID of full invoice metadata
    pub risk_score: u32,       // 0–100 (assigned by verifier)
    pub risk_tier: RiskTier,   // AAA / AA / A / B / C
    pub status: InvoiceStatus, // Created → Listed → Funded → Repaid | Defaulted
    pub created_at: u64,
    pub funded_at: Option<u64>,
    pub repaid_at: Option<u64>,
}

Risk Tiers

Tier Score Range Description
AAA 0–20 Lowest risk. Blue-chip debtors, strong SME history.
AA 21–40 Low risk. Established SME, reliable debtor.
A 41–60 Moderate risk. Standard trade finance profile.
B 61–80 Elevated risk. Newer SME or less-known debtor.
C 81–100 High risk. Requires higher yield to attract investors.

Protocol Fees

Fee Default Description
Marketplace fee 0.5% (50 bps) Charged on each investor contribution
Late penalty 2% (200 bps) Applied to late repayments

All fees are configurable by the admin within safe bounds (0–100%).

Security

  • All state-mutating functions require require_auth() on the relevant signer
  • Input validation on all public entry points (amounts, timestamps, scores, strings)
  • Safe arithmetic via checked_mul / checked_div — no silent overflows
  • Protocol-wide pause mechanism via access_control
  • Role-based access: Admin, Operator, Verifier
  • Debtor PII never stored on-chain — only a SHA-256 hash
  • See docs/SECURITY.md for the full security model

Contributing

We welcome contributions from the community. Please read CONTRIBUTING.md before opening a pull request.

License

MIT — see LICENSE.

Acknowledgements

Built with Stellar Soroban. Inspired by the real-world invoice financing gap facing African SMEs and the potential of blockchain infrastructure to close it.