Open-source Soroban smart contracts powering transparent, secure and verifiable humanitarian aid distribution on the Stellar blockchain.
- Overview
- Why Smart Contracts
- Core Features
- Architecture
- Contract Modules
- Technology Stack
- Project Structure
- Development Setup
- Build
- Testing
- Deployment
- Security
- Upgrade Strategy
- Contract Interfaces
- Events
- Storage Layout
- Contribution Guide
- License
The Alian Structure Contracts repository contains every on-chain component responsible for securely executing humanitarian aid transactions on the Stellar blockchain using Soroban.
These contracts serve as the trust layer of the platform.
Instead of relying on centralized intermediaries, every payment, verification, referral reward, and settlement is executed transparently on-chain.
The contracts are designed to be:
- Secure
- Auditable
- Upgradeable
- Gas Efficient
- Modular
- Production Ready
Traditional donation systems rely heavily on centralized infrastructure.
Alian Structure replaces this model by executing critical operations directly on-chain.
The contracts provide:
- Transparent aid settlements
- Immutable transaction records
- Referral commission distribution
- Treasury management
- Multi-signature administration
- Emergency controls
- Upgrade governance
Every important financial action becomes publicly verifiable.
Transfers donor funds directly to verified recipients.
Features
- Atomic transfers
- Escrow support
- Expiration handling
- Claim verification
- Replay protection
Generate secure claim identifiers.
Supports
- One-time claims
- Expiration dates
- Maximum claims
- Signature validation
- Hash verification
Automatically distributes affiliate commissions.
Supports
- Multi-tier referrals
- Percentage configuration
- Reward limits
- Treasury payouts
Central treasury responsible for:
- Holding protocol reserves
- Reward distribution
- Administrative transfers
- Emergency withdrawals
Administrative controls include
- Contract upgrades
- Parameter updates
- Treasury permissions
- Emergency pause
- Role assignments
Stores verification references without exposing private user information.
Supports
- Hash verification
- Metadata pointers
- AI verification references
- Off-chain oracle integration
┌────────────────────────────┐
│ Frontend │
└────────────┬───────────────┘
│
▼
┌────────────────────────────┐
│ Backend API │
└────────────┬───────────────┘
│
▼
┌────────────────────────────┐
│ Soroban Contracts │
├────────────────────────────┤
│ Aid Contract │
│ Treasury Contract │
│ Referral Contract │
│ Governance Contract │
│ Oracle Contract │
│ Registry Contract │
└────────────┬───────────────┘
│
▼
Stellar Ledger
Responsible for
- Aid creation
- Aid claiming
- Settlement
- Escrow
- Refunds
Responsible for
- Treasury balances
- Reward distribution
- Protocol funds
- Emergency reserve
Responsible for
- Referral registration
- Commission calculations
- Tier rewards
- Reward claims
Responsible for
- Upgrade authorization
- Admin roles
- Parameter management
- Contract registry
Responsible for
- AI verification references
- External signatures
- Verification proofs
Responsible for
- Contract discovery
- Address registry
- Version tracking
| Technology | Purpose |
|---|---|
| Rust | Smart contract language |
| Soroban SDK | Contract development |
| Stellar CLI | Deployment |
| Cargo | Package manager |
| Soroban RPC | Network interaction |
| GitHub Actions | CI/CD |
contracts/
├── aid-contract/
├── treasury-contract/
├── referral-contract/
├── governance-contract/
├── oracle-contract/
├── registry-contract/
│
├── shared/
│ ├── errors.rs
│ ├── events.rs
│ ├── storage.rs
│ ├── auth.rs
│ ├── math.rs
│ └── utils.rs
│
├── scripts/
│ ├── deploy.sh
│ ├── upgrade.sh
│ ├── initialize.sh
│ └── verify.sh
│
├── tests/
├── Cargo.toml
├── Cargo.lock
└── README.md
rustup update
Install Soroban CLI
cargo install --locked soroban-cli
Clone repository
git clone https://github.com/SourceXXL/alian_structure-contracts.git
cd alian_structure-contracts
cargo build --release
Build optimized WASM
cargo build \
--target wasm32v1-none \
--release
Run all tests
cargo test
Run integration tests
cargo test --test integration
Generate coverage
cargo llvm-cov
Deploy to Testnet
soroban contract deploy \
--wasm target/wasm32v1-none/release/aid_contract.wasm \
--source admin
Initialize
soroban contract invoke \
--id CONTRACT_ID \
-- initialize
The contracts implement
- Reentrancy protection
- Signature verification
- Overflow-safe arithmetic
- Access control
- Replay protection
- Input validation
- Treasury limits
- Emergency pause
- Time-based expirations
- Storage validation
Supports controlled upgrades through governance.
Only authorized administrators may:
- Upgrade contracts
- Register new implementations
- Pause protocol
- Resume protocol
- Update treasury
- Modify protocol parameters
Persistent storage includes
Aid Records
- Aid ID
- Donor
- Recipient
- Amount
- Status
- Timestamp
Referral Records
- Wallet
- Referrer
- Commission
- Tier
Treasury
- Balance
- Rewards
- Fees
Governance
- Admins
- Roles
- Versions
- Registry
Contracts emit events for:
AidCreated
AidClaimed
AidSettled
AidRefunded
CommissionPaid
TreasuryDeposit
TreasuryWithdrawal
ContractPaused
ContractResumed
ContractUpgraded
- Cross-chain settlement
- Stellar Asset support
- Multi-token donations
- DAO governance
- Zero Knowledge verification
- On-chain reputation
- Human identity proofs
- Streaming donations
- Batch settlements
We welcome contributions from Rust and Soroban developers.
Workflow
-
Fork repository
-
Create feature branch
-
Write tests
-
Submit Pull Request
Every contract contribution must include:
-
Unit tests
-
Documentation
-
Security considerations
-
Gas optimization review
Licensed under the MIT License.
See LICENSE for details.
- Stellar
- Soroban
- Rust
- Open Source Community
Building transparent humanitarian infrastructure for everyone.