Invoice Liquidity Network (ILN) is a two-sided protocol on Stellar/Soroban that lets invoice holders (freelancers, SMEs) get paid early by liquidity providers, who fund invoices at a discount and collect the face value at maturity.
This repository is the protocol monorepo: the Soroban smart contracts, the TypeScript SDK and CLI built on top of them, and the off-chain services (event indexer, notifications) that support them.
- Repository Layout
- Smart Contracts
- Architecture
- Getting Started
- Building & Testing
- Deploying to Testnet
- Documentation
- Contributing
- Security
- License
| Path | Type | What it is |
|---|---|---|
contracts/ |
Rust / Soroban | The on-chain protocol — see Smart Contracts below |
sdk/ |
TypeScript (@iln/sdk) |
Typed client library for calling the contracts from JS/TS |
cli/ |
TypeScript (@iln/cli) |
Terminal wallet and invoice-management tool built on the SDK |
indexer/ |
TypeScript (@iln/indexer) |
Streams Soroban/Horizon events into Postgres and exposes a REST API |
notifications/ |
TypeScript (@iln/notifications) |
Webhook, Slack, and email delivery service for invoice lifecycle events |
frontend/ |
TypeScript (@iln/frontend, Next.js) |
Component library / Storybook workspace for the ILN UI (the deployed web app lives in the separate ILN-Frontend repo) |
packages/ |
TypeScript | Shared workspace packages: types (domain types), test-utils, eslint-config |
scripts/ |
Bash / TypeScript | Deploy, seed, health-check, spec-generation, and release scripts used by make |
tests/e2e/ |
TypeScript | Cross-component end-to-end suite (SDK + live local Stellar node + indexer) |
docs/ |
Markdown | Protocol, architecture, security, and integration documentation |
The Rust crates are a Cargo workspace (see Cargo.toml); the TypeScript packages
are a pnpm workspace (see pnpm-workspace.yaml) orchestrated with Turborepo.
All contracts live under contracts/, compile to Soroban WASM
(wasm32v1-none), and are tested natively via soroban-sdk test utilities — cargo test
does not require a live network.
| Crate | Path | Responsibility |
|---|---|---|
invoice_liquidity |
contracts/invoice_liquidity/ |
Core escrow contract: submit, fund, settle, cancel, and default invoices; reputation scoring; multi-token support; optional payer oracle |
iln_governance |
contracts/iln_governance/ |
On-chain governance: proposals, voting, delegation, quorum, and timelocked admin actions |
iln_distribution |
contracts/iln_distribution/ |
Yield and incentive distribution for LPs, freelancers, and payers |
reputation_bonus |
contracts/reputation_bonus/ |
Reputation-based discount bonuses and related invoice hooks |
insurance_pool |
contracts/insurance_pool/ |
Default-protection insurance pool for liquidity providers |
iln_fuzz |
contracts/fuzz/ |
Property-based fuzz tests against the core invoice flows |
| (integration tests) | contracts/tests/ |
Cross-contract tests with mock tokens and oracles |
For function signatures, error codes, storage keys, and emitted events, see the Contract ABI, Error Codes, Storage Layout, and Events docs.
Frontend (web / mobile / dashboard)
│
┌───────▼────────┐
│ @iln/sdk │
│ TypeScript SDK │
└───────┬────────┘
┌───────────────────┼───────────────────┐
▼ ▼ ▼
┌──────────────┐ ┌────────────────┐ ┌─────────────────┐
│ @iln/cli │ │ Soroban Smart │ │ @iln/indexer │
│ Terminal │◄─►│ Contracts │◄─►│ REST API / │
│ Interface │ │ (WASM) │ │ event indexer │
└──────────────┘ └───────┬────────┘ └────────┬────────┘
│ │
┌────────▼────────┐ ┌────────▼─────────┐
│ Stellar Network │ │ @iln/notifications│
│ (Horizon + RPC) │ │ Webhook / email │
└─────────────────┘ └────────────────────┘
The SDK talks directly to the contracts over Soroban RPC; the indexer independently streams contract events from Horizon into Postgres so the CLI, frontend, and integrators can query history and aggregates without re-simulating transactions. The notifications service consumes the same event stream to fan out webhooks, Slack messages, and email.
Full write-up, including the on-chain state machine and money flow: docs/Architecture.md.
- Rust (stable) with the
wasm32v1-nonetarget:rustup target add wasm32v1-none - Stellar CLI for building, testing, and deploying contracts
- Node.js 22+ and pnpm 9 for the TypeScript packages
- Docker (optional) for running a local Stellar node and the indexer/notifications databases
git clone https://github.com/Invoice-Liquidity-Network/ILN-Smart-Contract.git
cd ILN-Smart-Contract
make install # installs deps for sdk, indexer, notifications, tests/e2eA step-by-step walkthrough (toolchain setup through your first testnet deploy) is in the Developer Quickstart. To run the full local stack (contracts, Docker services, SDK, CLI, indexer, notifications) see the Local Development Guide.
Everything is driven through the root Makefile (make help lists all targets):
| Command | Description |
|---|---|
make build |
Build contract WASM + the @iln/sdk package |
make build-rust |
Build optimized contract WASM only (wasm32v1-none, release) |
make test |
Run the full Rust workspace test suite |
make test-invoice / test-governance / test-distribution / test-insurance |
Run tests for a single contract |
make fuzz |
Run the property/fuzz test suite (iln_fuzz) |
make test-e2e |
Run the cross-component end-to-end suite in tests/e2e/ |
make lint |
cargo fmt --check + cargo clippy -D warnings |
make fmt |
Format all Rust code in place |
make coverage |
Generate an HTML coverage report with cargo-tarpaulin |
make spec |
Regenerate the contract ABI/spec JSON (docs/contract-spec.json) |
make docs |
Regenerate the SDK's TypeDoc API docs |
make health |
Run the deployment health check against a live deployment |
For the TypeScript packages individually, use the package manager inside each directory
(sdk/, cli/, indexer/, notifications/) — each has its own README with local dev
instructions — or run pnpm turbo build / pnpm turbo test from the repo root to fan the
same scripts out across the whole workspace.
export STELLAR_ACCOUNT=your-account-alias
make build
make deploy-testnetmake deploy-testnet builds all contracts and deploys them to Stellar testnet via
scripts/deploy-testnet.sh. Use make seed to populate a fresh
deployment with sample invoices, and make reset-testnet to reset local/testnet state.
This README covers the repository as a whole. Deeper documentation lives in docs/ —
start at the Documentation Index, or jump to:
| Topic | Doc |
|---|---|
| Contract functions & error codes | Contract ABI, Error Codes |
| Events | Events |
| Governance | Governance |
| Storage layout | Storage Layout |
| Security model & risks | Threat Model, Access Control |
| Upgrades | Upgrade Guide |
| SDK usage | SDK Integration Guide, sdk/README.md |
| CLI usage | cli/README.md |
| Indexer REST API | Indexer API Reference, indexer/README.md |
| Notifications (webhooks, HMAC, email) | notifications/README.md |
| End-to-end test suite | tests/e2e/README.md |
| Design decisions | Architecture Decision Records |
| Terminology | Glossary |
See CONTRIBUTING.md for commit conventions, changesets, PR size guidelines, code style, and the review process.
Do not open a public issue for vulnerabilities. See SECURITY.md and docs/security.md for the reporting process, severity classification, and safe harbor terms.