Custom compliance hooks, alternative payment rails, and on-chain conditional escrow for the Stellar Disbursement Platform (SDP) — letting NGOs, governments, and fintechs customize humanitarian aid and payroll delivery without forking the core platform.
Status: early-stage, single-repo monorepo · all Wave task-backlog items currently open for contribution
- Why Cascade Network
- Monorepo Layout
- Architecture
- Quick Start
- Frontend — Operator Portal
- Contracts — Conditional Payment Escrow
- SDK — SDP Extension Layer
- Docs — Deployment Playbook & Hook Guides
- Drips Wave — Contributing & Earning Points
- Project Status & Roadmap
- Community & Support
- License
The Stellar Disbursement Platform (SDP) gives NGOs, governments, and fintechs a solid core for moving aid and payroll on Stellar — but it's deliberately generic. Real-world disbursement programs need region-specific KYC/AML logic, local payment rails (mobile money, bank transfer) alongside Stellar-native payments, and proof-of-delivery before funds release for higher-value or compliance-sensitive transfers. Today that means forking SDP or bolting on brittle middleware.
Cascade Network is an extension layer, not a fork: a hook system that runs custom logic at key points in the disbursement lifecycle, a rails-adapter interface for non-Stellar payment methods, and Soroban escrow contracts that hold funds until a condition (delivery confirmation, oracle approval, or timeout) is met.
| Problem | Cascade Network's Approach |
|---|---|
| SDP is powerful but not customizable for specialized compliance | A plugin/hook system injected at key lifecycle points (onBeforeDisbursement, onAfterDisbursement, onFailure) |
| Aid organizations need local payment rail integrations | A RailsAdapter interface, with mobile money and bank transfer adapters as reference implementations |
| No conditional, auditable verification of aid delivery | Soroban escrow contracts (conditional_payment, escrow) with programmable release conditions |
| Analytics are limited to SDP's built-in views | An operator portal with disbursement-flow and volume/success-rate dashboards |
This is a Wave-5 Stellar ecosystem project: an early-stage scaffold with a defined architecture and an open task backlog (see Drips Wave below), not a deployed production system. Anything described below as a capability of the SDK, contracts, or portal reflects what's scaffolded and in progress, not a completed or field-tested product — see Project Status & Roadmap for the honest breakdown of what currently exists versus what's an open contribution task.
This repository was consolidated from four separate repos (cascade-network-portal, cascade-network-contracts, cascade-network-sdk, cascade-network-docs) into a single monorepo so the whole project can be tracked and funded as one unit:
cascade-network/
├── frontend/ # React + Vite operator portal (formerly cascade-network-portal)
├── contracts/ # Soroban escrow contracts, Rust (formerly cascade-network-contracts)
├── sdk/ # TypeScript SDP extension SDK (formerly cascade-network-sdk)
├── docs/ # Docusaurus documentation site (formerly cascade-network-docs)
├── WAVE_TASKS.md # Point-weighted task backlog for Drips Wave contributors
├── WAVE_ISSUES.md # Full issue specs, organized by component
└── .github/ # Issue templates, PR template, per-component CI workflows
Each component keeps its own package.json/Cargo.toml and can still be built and tested independently — only the repository-level packaging changed, not the internal structure of each piece. CI runs per-component, scoped by path, via the workflows in .github/workflows/.
graph TD
subgraph "Stellar Disbursement Platform Core"
SDP[SDP Core] -- "Webhook events" --> SDK[sdk/]
SDP -- "Payment execution" --> Stellar[Stellar Network]
end
subgraph "Extension Layer"
SDK -- "Lifecycle hooks" --> Hooks[Hook Registry]
Hooks -- "onBeforeDisbursement" --> KYC[KYC Provider]
Hooks -- "onAfterDisbursement" --> Analytics[Analytics]
SDK -- "Rail adapters" --> MoMo[Mobile Money]
SDK -- "Rail adapters" --> Bank[Bank Transfer]
end
subgraph "On-Chain Verification"
SDK -- "Conditional release" --> Escrow[conditional_payment contract]
Escrow -- "Proof-of-delivery" --> Soroban[Soroban Ledger]
Escrow -- "Multi-party approval" --> MultiEscrow[escrow contract]
end
subgraph "Operator Interface"
Portal[frontend/] -- "Configure flows" --> SDK
Portal -- "View analytics" --> Analytics
Portal -- "Monitor disbursements" --> SDP
end
subgraph "Documentation"
Docs[docs/] -- "Deployment playbooks" --> Portal
Docs -- "Compliance guides" --> Hooks
end
- Node.js 20+
- Rust 1.75+ with the
wasm32-unknown-unknowntarget (for contracts) - Stellar CLI 21+
- Freighter wallet browser extension (for the portal)
- Access to a Stellar Disbursement Platform instance (for SDK integration)
git clone https://github.com/cascade-network/cascade-network.git
cd cascade-networkcd sdk
npm install
npm run build && npm testcd frontend
npm install
cp .env.example .env
npm run dev
# open http://localhost:5173cd contracts
rustup target add wasm32-unknown-unknown
stellar contract build
cargo testcd docs
npm install
npm run dev
# open http://localhost:3000frontend/ — React 18 · TypeScript · Vite · Recharts · Tailwind
The operator dashboard for Cascade Network: configure batch disbursements, monitor payment status in real time, manage compliance hook plugins, and view volume/success-rate analytics.
Planned features (see WAVE_TASKS.md for current implementation status of each):
- Batch disbursement builder with per-recipient amount and memo
- Live payment status tracker (pending / completed / failed)
- Plugin manager — toggle compliance hooks without code changes
- Analytics dashboard — volume, success rate, failure breakdown, built on Recharts
- CSV export of disbursement history
contracts/ — Rust · Soroban SDK
On-chain escrow contracts that release funds only when a defined condition is met — an authorised oracle confirming delivery, multi-party approval, or a timeout — for higher-value or compliance-sensitive disbursements.
conditional_payment—deposit,confirm,timeout_refund,cancelescrow— multi-party approval with arbiter dispute resolution- Each contract compiles to an independent WASM module and is independently deployable
- All contracts emit structured Soroban events, designed to be consumed by indexers such as Lumina
Run cargo clippy -- -D warnings before opening a PR — CI enforces zero warnings. stellar contract build produces .wasm artifacts under target/wasm32-unknown-unknown/release/.
sdk/ — TypeScript · @stellar/stellar-sdk
The extension layer over SDP. Exposes:
HookRegistry— orderedonBeforeDisbursement/onAfterDisbursement/onFailurepluginsRailsAdapter— an interface for routing disbursements through mobile money or bank transfer instead of (or alongside) Stellar-native paymentsConditionalPaymentClient— a thin client wrapping the on-chain escrow contracts incontracts/DisburseSDK— the top-level entry point exported fromsdk/src/index.ts, tying the hook registry, rails adapters, and conditional payment client together
import { DisburseSDK } from '@cascade-network/sdk';
const sdk = new DisburseSDK({
sdpEndpoint: 'https://sdp.example.org',
apiKey: process.env.SDP_API_KEY,
});
sdk.hooks.onBeforeDisbursement(async (payload) => {
const result = await myKYCProvider.verify({
id: payload.recipientId,
amount: payload.amount,
country: payload.country,
});
if (!result.passed) {
throw new Error(`KYC check failed: ${result.reason}`);
}
});
sdk.hooks.onAfterDisbursement(async (payload) => {
await analytics.track('disbursement_completed', {
recipientId: payload.recipientId,
amount: payload.amount,
currency: payload.currency,
timestamp: new Date(),
});
});
await sdk.start({ port: 3000 });import { ConditionalPaymentClient } from '@cascade-network/sdk';
const payment = new ConditionalPaymentClient({
contractId: 'CDA...',
rpcUrl: 'https://soroban-testnet.stellar.org',
});
await payment.create({
donor: 'GDONOR...',
recipient: 'GRECIPIENT...',
amount: 1000n,
asset: 'USDC:ISSUER...',
condition: 'proof_of_delivery',
expiryLedger: currentLedger + 17280, // ~24 hours
});
await payment.submitProof({
paymentId: 'payment_123',
proofHash: '0x...', // e.g. an IPFS hash of a delivery photo
recipient: 'GRECIPIENT...',
});Both examples describe the intended SDK surface as scaffolded in sdk/src/; check WAVE_TASKS.md for which pieces are implemented versus open for contribution.
docs/ — Docusaurus 3 · Markdown
Documentation for self-hosting Cascade Network alongside SDP, writing custom compliance hooks, and implementing alternative payment-rail adapters, aimed at NGO and government operator teams. Planned content includes a full self-hosting deployment playbook, a hook-authoring guide with worked KYC/sanctions-screening examples, a custom rails-adapter guide (mobile money example), and a TypeDoc-generated SDK API reference.
Cascade Network participates in the Stellar Drips Wave program (drips.network/wave). Contributors pick up point-weighted tasks, submit a PR, and earn rewards once it's merged.
Point values:
- 🟢 Trivial — 100 points
- 🟡 Medium — 150 points
- 🔴 High — 200 points
The full, up-to-date backlog lives in two files:
WAVE_TASKS.md— task list with files to edit and acceptance criteriaWAVE_ISSUES.md— full issue specs, organized by component (contracts,sdk,frontend,docs)
How to contribute:
- Browse open tasks in
WAVE_TASKS.md/WAVE_ISSUES.md - Sign in at drips.network/wave with your GitHub account and apply to an issue
- Fork the repo, create a branch (
feat/your-feature), implement the task - Open a PR referencing the issue (
Closes #XX), with tests and docs updated - Earn points once merged and the Wave cycle closes
See CONTRIBUTING.md for code style, branching, and PR requirements, and CODE_OF_CONDUCT.md for community guidelines.
Honest current status: every task in WAVE_TASKS.md is currently marked Open — this is a scaffolded, early-stage project with a defined architecture, not a deployed or field-tested system. There are no production disbursements, pilot NGO partners, or live deployments to report yet.
Now (scaffolded, open for contribution):
- Hook registry, rails-adapter interface, and conditional-payment client interfaces defined in the SDK
conditional_paymentandescrowcontract skeletons incontracts/- Portal shell with routing in
frontend/ - Docs site scaffold in
docs/
Next:
- Implement and test the mobile money and bank transfer rail adapters
- Implement and test
conditional_paymentandescrowcontract logic, including timeout and dispute paths - Wire the portal's batch-submit flow to a live
DisburseSDKinstance - Write the self-hosting deployment playbook
Later / vision:
- Biometric or other proof-of-delivery verification integrations
- Offline-friendly payment flows for low-connectivity field conditions
- Fraud-detection heuristics over disbursement analytics
- Integration patterns for existing humanitarian-sector platforms
- Issues — GitHub Issues for bugs and feature requests
- Discussions — GitHub Discussions for questions and design conversations
- Contributing —
CONTRIBUTING.md - Code of Conduct —
CODE_OF_CONDUCT.md - Security —
SECURITY.mdfor responsible disclosure - Maintainer — @phantomcall
Distributed under the Apache License 2.0. See LICENSE for details.
Copyright 2026 Cascade Network Contributors
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
Building the open rails for humanitarian and financial aid on Stellar.