Skip to content

Invoice-Liquidity-Network/ILN-Smart-Contract

BranchesTags

Repository files navigation

ILN Smart Contract

License: MIT

Soroban smart contracts for the Invoice Liquidity Network (ILN) — a two-sided protocol on Stellar that connects invoice holders (freelancers, SMEs) with liquidity providers (LPs). Contracts act as trustless escrow: funds are held on-chain, payment terms are enforced by code, and settlement follows a strict state machine.

New here? Start with the Developer Quickstart, then read Architecture for the full money flow.

Table of Contents

How it works

Actor Role
Freelancer Submits unpaid invoices and receives early liquidity
Payer The client who owes the invoice; settles on-chain
Liquidity provider (LP) Funds invoices at a discount; earns yield when the payer pays
ILN contracts Hold escrow, enforce rules, emit events, and route token transfers

Typical lifecycle:

  1. Freelancer calls submit_invoice → invoice is Pending.
  2. LP calls fund_invoice → freelancer receives (amount − discount); invoice is Funded.
  3. Payer calls mark_paid → LP receives principal + yield; invoice is Paid (terminal).

Alternative paths include partial funding, defaults, disputes, appeals, and governance-controlled parameter updates. See Architecture for diagrams and edge cases.

Contracts

Crate Path Responsibility
invoice_liquidity contracts/invoice_liquidity/ Core escrow: submit, fund, settle, cancel, and default invoices; reputation scores; multi-token support; optional payer oracle
iln_governance contracts/iln_governance/ On-chain governance: proposals, voting, delegation, quorum, and admin veto
iln_distribution contracts/iln_distribution/ Yield and incentive distribution for LPs, freelancers, and payers (linked to governance token)
reputation_bonus contracts/reputation_bonus/ Reputation-based discount bonuses and related invoice hooks
iln_fuzz contracts/fuzz/ Property-based fuzz tests against core invoice flows
Integration tests contracts/tests/ Cross-contract tests with mock tokens and oracles

All contracts compile to Soroban WASM (wasm32v1-none) and are tested natively via soroban-sdk test utilities (no live network required for cargo test).

Doc Description
First Invoice Tutorial Hands-on walkthrough: submit, fund, settle, and query an invoice on testnet
Local Development Guide Docker setup, local Stellar node, deploying contracts locally, running tests
Developer Quickstart Rust toolchain setup, building, testing, and deploying to testnet
SDK Integration Guide TypeScript examples for every contract interaction
Architecture System design, money flow, and security model
Contract ABI Function signatures and error codes
Events All emitted events and their payloads
Governance Proposal lifecycle and voting mechanics
Storage Layout On-chain storage key reference
Threat Model Security assumptions and known risks

Architecture

High-level component view (one deployment per network; invoice_liquidity is the primary integration surface):

                         ┌─────────────────────────────────────────┐
                         │           Stellar / Soroban             │
                         └─────────────────────────────────────────┘
    Freelancer                    Payer                      LP
        │                          │                          │
        │ submit_invoice           │ mark_paid                │ fund_invoice
        ▼                          ▼                          ▼
┌───────────────────────────────────────────────────────────────────────┐
│                     invoice_liquidity (escrow)                        │
│  Pending → PartiallyFunded → Funded → Paid / Defaulted / Disputed   │
│  + reputation scores · multi-token · optional price oracle            │
└───────────────┬───────────────────────────────┬───────────────────────┘
                │                               │
        ┌───────▼────────┐              ┌───────▼────────┐
        │ iln_governance │              │reputation_bonus│
        │ proposals/votes│              │ discount rules │
        └───────┬────────┘              └────────────────┘
                │
        ┌───────▼────────┐
        │iln_distribution│
        │ yield / claims │
        └────────────────┘
                │
        ┌───────▼────────┐
        │  USDC / XLM    │  Stellar Asset Contracts (SAC)
        │  (test tokens) │
        └────────────────┘

Design notes

  • No backend server; state transitions are driven by signed on-chain invocations.
  • Persistent storage uses Soroban StorageKey patterns (see Storage Layout).
  • Major design decisions are recorded as ADRs.

Repository layout

ILN-Smart-Contract/
├── contracts/
│   ├── invoice_liquidity/   # Core escrow contract + unit/integration tests
│   ├── iln_governance/       # Governance contract
│   ├── iln_distribution/   # Distribution / rewards contract
│   ├── reputation_bonus/   # Reputation bonus contract
│   ├── fuzz/                 # Fuzz / property tests (iln_fuzz)
│   └── tests/                # Workspace-level integration tests & mocks
├── docs/                     # Technical documentation (see below)
├── scripts/
│   ├── deploy-local.sh       # Deploy all contracts (local or testnet)
│   ├── setup-local-env.sh    # Docker + Stellar CLI local setup
│   ├── local-test.sh         # Local integration test runner
│   └── gen-abi.ts            # ABI generation helper
├── .github/workflows/        # CI (build, test, benchmarks)
├── Cargo.toml                # Rust workspace manifest
├── Makefile                  # build · test · fuzz · changelog
├── docker-compose.yml        # Local Stellar node for development
├── CONTRIBUTING.md           # Contribution guide
└── README.md                 # This file

Quick start

Prerequisites

Tool Version
Rust ≥ 1.74
wasm32v1-none target rustup target add wasm32v1-none
Stellar CLI For deploy / invoke (optional for tests)

Clone, build, and test

git clone https://github.com/Invoice-Liquidity-Network/ILN-Smart-Contract.git
cd ILN-Smart-Contract

# Install WASM target (first time only)
rustup target add wasm32v1-none

# Build optimized WASM for all contracts
make build
# or: cargo build --target wasm32v1-none --release

# Run the full test suite
make test
# or: cargo test

# Run property-based fuzz tests
make fuzz
# or: cargo test -p iln_fuzz

Local network (optional)

For integration testing against a local Stellar node:

./scripts/setup-local-env.sh   # Docker + CLI config
./scripts/deploy-local.sh      # Build & deploy all contracts
./scripts/local-test.sh        # Smoke tests against local node

See Local Development Guide for troubleshooting and CI notes.

Deploy to testnet

Full step-by-step instructions (fund accounts, upload WASM, deploy, initialize) are in Developer Quickstart §7. Quick deploy of all workspace contracts:

cargo build --target wasm32v1-none --release
./scripts/deploy-local.sh testnet alice

Testnet deployment

Resource Contract ID Notes
invoice_liquidity CD3TE3IAHM737P236XZL2OYU275ZKD6MN7YH7PYYAXYIGEH55OPEWYJC Primary integration contract; used in SDK examples
iln_governance C2AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA Governance proposals and voting
iln_distribution C2AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAB Rewards distribution
reputation_bonus C2AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAC Reputation-based bonus rules
Testnet USDC (SAC) CBIELTK6YBZJU5UP2WWQEUCYKLPU6AUNZ2BQ4WWFEIE3USCIHMXQDAMA Referenced in SDK integration guide
Network RPC Passphrase
Testnet https://soroban-testnet.stellar.org Test SDF Network ; September 2015

iln_governance, iln_distribution, and reputation_bonus are deployed per environment via scripts/deploy-local.sh. Save the printed contract IDs after deploy for your integration config.

Explorer: Stellar Expert — search by contract ID.

Documentation

Getting started

Document Description
Developer Quickstart Toolchain, build, test, and testnet deploy
Local Development Guide Docker Stellar node, scripts, and workflow
SDK Integration Guide TypeScript / Stellar SDK examples (testnet)

Architecture & security

Document Description
Architecture Actors, money flow, state machine, deployment
Threat Model Security assumptions, risks, and mitigations
Access Control Roles, auth requirements, and admin functions
Storage Layout On-chain keys and data structures
Upgrade Guide Contract upgrade process and safeguards
Architecture Decision Records ADR index (Soroban choice, governance timelock, etc.)

Contract reference

Document Description
Contract ABI Public functions and error codes
Error Codes Numeric error reference with causes and remediation
Events Emitted events and payloads
Governance Proposals, voting, delegation, timelock
Multi-Token Support USDC, XLM, and token configuration
Reputation Reputation system overview
Reputation Model Scoring formulas and decay
Oracle Design Optional payer-verification oracle
Oracle Integration Deploy and register a compatible oracle
Benchmarks Gas / resource usage benchmarks

Contributing

We welcome contributions — bug fixes, tests, documentation, and new features.

  1. Read CONTRIBUTING.md for environment setup, testing expectations, and PR requirements.
  2. Use Conventional Commits (feat:, fix:, docs:, test:, etc.).
  3. Open a PR against main with a clear description and linked issue (e.g. Fixes #107).

For documentation-only changes:

git checkout -b docs/readme
# edit README.md
git commit -m "docs: write comprehensive README for ILN-Smart-Contract repo"

License

This project is licensed under the MIT License.

About

No description, website, or topics provided.

Resources

Readme

License

MIT license

Contributing

Contributing

Security policy

Security policy
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

57 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages