Yield-Bearing, Fiat-Native Digital Inheritance Infrastructure on Stellar
XourceX is a programmable, cross-border digital inheritance protocol built on the Stellar network with Soroban smart contracts. Individuals can secure their digital assets and automatically distribute them to multiple heirs when predefined inactivity conditions are met — settling directly to local fiat bank accounts or mobile money wallets via Stellar anchors.
Traditional inheritance is slow, paper-heavy, and unavailable to most of the world's unbanked population. XourceX makes estate planning programmable:
- Self-custody until activation — assets remain under the owner's control and earn yield while dormant.
- No crypto literacy required for heirs — beneficiaries are paid in local fiat.
- Global, by default — built on the Stellar network, settlements work across borders.
Assets locked in an inheritance vault never sit idle. Plan owners can opt to supply their capital into yield-generating Soroban lending or liquidity vaults. Yield accumulates continuously and increases the principal ultimately distributed to heirs.
Distributions to multiple heirs happen in a single transaction. Owners define custom
allocation splits in basis points (e.g. 5000 bps = 50%) for any number of
beneficiaries. The contract automatically divides principal and accrued yield on payout.
Heirs do not need crypto wallets or blockchain literacy. Payouts can be off-ramped
into local fiat currencies (NGN, KES, BRL, PHP, EUR, USD, …) and deposited
directly into bank accounts or mobile money wallets using Stellar Anchors.
Activities ("pings") keep plans active; defined inactivity conditions trigger activation. Escalation and dispute flows are handled on-chain.
┌──────────────────────────────────────────────┐
│ Frontend │
│ Next.js landing DApp + simulator │
└───────────────┬──────────────────┬────────────┘
│ HTTP / WebSocket │
▼ ▼
┌──────────────────────────┐ ┌──────────────────────────────┐
│ Soroban Contracts │ │ Backend │
│ inheritance-contract │◄►│ Axum (Rust) — planning API, │
│ plan-vault │ │ inactivity watchdog, KYC │
│ lending-contract │ │ webhooks, PDF reports, fiat │
│ loan-nft · mock-token │ │ (SEP-31) anchor client │
│ access-control │ └──────────────┬───────────────┘
└──────────────────────────┘ │
┌──────────────▼────────────────┐
│ Stellar Network + Anchors │
│ (SEP-31 off-ramp to local fiat)│
└───────────────────────────────┘
| Directory | Purpose |
|---|---|
contracts/ |
Soroban smart contracts (workspace) |
contracts/inheritance-contract |
Vault state, pings, yield accounting, payouts, disputes |
contracts/plan-vault |
Plan creation and asset custody |
contracts/lending-contract |
Yield-generating lending vault interactions |
contracts/loan-nft |
Non-transferable loan-position NFTs |
contracts/access-control |
Shared roles/authority library across contracts |
backend/ |
Axum (Rust) API service (planning, watchdog, KYC, fiat anchor client) |
frontend/ |
Next.js DApp (landing, plan configuration, claim simulator) |
scripts/ |
Deployment and environment setup scripts |
- Rust (
1.75+) with thewasm32-unknown-unknowntarget - Node.js
18+and pnpm - Optional: PostgreSQL 14+, Redis 7+, Docker
rustup target add wasm32-unknown-unknownEach layer is independently runnable:
# Frontend — dev server only
cd frontend && pnpm install && pnpm run dev # http://localhost:3000
# Backend — minimal build (no Redis / Prometheus / PDF)
cd backend && cargo run --no-default-features
# Smart contracts — build only
cd contracts && cargo build --target wasm32-unknown-unknown --releaseTip:
pnpm install --optionalinfrontend/additionally restores@playwright/test(e2e),@ducanh2912/next-pwa(PWA),sharp(image optimiser), and@allbridge/bridge-core-sdk(cross-chain bridge).
cd contracts
cargo build --target wasm32-unknown-unknown --release
cargo test # run the contract test suites (incl. reentrancy, yield math)Full build (Redis cache + Prometheus metrics + PDF reports):
cd backend && cargo runMinimal build (no optional dependencies):
cd backend && cargo run --no-default-featuresSelective features:
cargo run -F redis-cache # add Redis cache only
cargo run -F redis-cache,metrics # add Redis + PrometheusConfiguration is via environment variables — see backend/.env.example
and docs/security.md. Notable variables:
DATABASE_URL=postgres://postgres:postgres@localhost:5432/xourcex
LOG_FORMAT=json # json | pretty | compact
KYC_WEBHOOK_SECRET=<hmac-secret> # required to accept KYC webhooks
ANCHOR_API_URL=http://localhost:8081cd frontend
pnpm install
pnpm run dev # http://localhost:3000
# e2e tests (requires optional deps)
pnpm install --optional
pnpm run test:e2eUnit tests: pnpm run test · Coverage: pnpm run test:coverage
| Layer | Command | Notes |
|---|---|---|
| Contracts | cargo test |
Unit + integration, reentrancy guards, snapshot tests |
| Backend | cargo test |
API, KYC webhooks, inactivity watchdog, DB query guards |
| Frontend unit | pnpm test |
Vitest component suites |
| Frontend e2e | pnpm test:e2e |
Playwright flows |
XourceX is transitioning from development to testnet. The codebase intentionally contains placeholders, stubs, and interfaces open for implementation.
Please read CONTRIBUTING.md and our Code of Conduct. In short:
- Fork the repository and create a feature branch.
- Follow the existing code style (
rustfmt/clippyfor Rust, ESLint/Prettier for the frontend). - Add tests for new behaviour.
- Open a Pull Request referencing the relevant issue.
Security findings should follow the guidance in SECURITY.md.
- Core inheritance vault & payout logic
- Yield accrual via Soroban lending vaults
- Loan-position NFT surface for lending flows
- Testnet deployment & stress testing
- Mainnet anchor integrations and local-fiat settlements
Released under the terms described in LICENSE.