🌟 MilestoneX

📚 Community Documentation

• Contributing Guide - Learn how to contribute to the project
• Code of Conduct - Guidelines for community interactions
• Maintainers - Project maintainers and areas of ownership
• Changelog - Release notes and version history
• Security Policy - Security guidelines and vulnerability reporting

Contract Canonicalization

Decision: Option B (conservative) — keep campaign/ (milestonex-campaign) as the canonical crowdfunding contract for all new development, audits, deployments, and integrations. The campaign/ implementation remains the authoritative contract for milestone flows, refunds, freeze/upgrade controls, reentrancy protection, typed errors, and dashboard analytics.

crates/contracts/core/ (milestonex-core) is retained only as a legacy compatibility/reference contract. Do not add new campaign features there; use campaign/ for any new logic, analytics endpoints, or deployment work. Any remaining behavior worth preserving from core should be migrated into campaign/ before core is removed in a future breaking release.

Canonical campaign analytics now live on milestonex-campaign: use get_campaign_report, get_platform_summary, get_dashboard_metrics, get_donation_count, get_donor_count, get_release_count, and get_total_tx_count for dashboard and export workflows.

MilestoneX is an on-chain crowdfunding protocol built on the Stellar Network and Soroban smart contracts. It provides a transparent, trust-minimized platform where campaign creators can raise funds in native XLM or any Stellar-based asset (USDC, NGNT, custom tokens), and donors retain full visibility into how their contributions are deployed.

The protocol is governed by a set of deterministic Soroban contracts — handling campaign lifecycle management, milestone-based fund release, multi-asset donation processing, and cross-chain token bridging — complemented by a comprehensive CLI toolchain for deployment, transaction signing, wallet integration, and network diagnostics.

� Workspace Layout

This project uses a Rust Cargo workspace with the following structure:

milestonex-contract/
|-- campaign/                  # Canonical campaign contract
|   |-- Cargo.toml
|   `-- src/
|       `-- lib.rs
├── Cargo.toml                 # Workspace configuration
├── crates/
│   ├── contracts/
│   │   └── core/             # Legacy compatibility/reference contract
│   │       ├── Cargo.toml
│   │       └── src/
│   │           └── lib.rs    # Contract implementation
│   └── tools/                # CLI utilities and deployment tools
│       ├── Cargo.toml
│       └── src/
│           └── main.rs       # CLI entry point
├── .gitignore
└── README.md

Crates Overview

• milestonex-campaign: Canonical Soroban crowdfunding contract for milestones, multi-asset donations, refunds, lifecycle controls, and analytics
• milestonex-core: Legacy compatibility/reference contract; do not use for new campaign features
• milestonex-tools: Advanced CLI utilities for contract deployment, configuration, transaction management, and debugging

🛠️ Implemented CLI Commands

The milestonex-cli binary (in crates/tools) ships with a focused set of sub-commands today. Anything not listed below is unimplemented and will print either ❌ Unknown command: … or a stubbed "not yet implemented" banner with an issue link. Older documentation referenced several commands that do not exist yet; the canonical status table lives in docs/deployment.md and is tracked in issue #37.

Configuration & Network

• config — Print resolved environment and active network.
• network — Print active Soroban network (RPC, Horizon, passphrase).
• vault — Show SecureVault status and security best practices.
• toggle <testnet|mainnet> — Switch the active network profile.

Asset Issuing

• asset config — Show asset configuration.
• asset generate — Generate issuing keypair.
• asset check — Check issuing readiness.
• asset trustline <holder> [asset_code] — Establish a trustline.
• asset issue <recipient> <amount> — Issue assets to a recipient.

Key Management

• keymanager encrypt <password> <secret_key> — Encrypt a Stellar secret key.
• keymanager decrypt <password> <encrypted_hex> — Decrypt back to a secret key.
• keymanager init-vault <password> — Initialize an encrypted vault.
• keymanager vault-status / vault-save <path> / vault-load <path> <password> — Vault lifecycle.

Keypair Lifecycle

• keypair generate-master — Generate a master keypair.
• keypair generate-distribution <issuing_public_key> — Generate a distribution account.
• keypair show-master / keypair show-distribution — Print stored keypairs (safe view).
• keypair fund <account_public_key> <amount_xlm> — Friendbot-fund a testnet account.
• keypair validate-master / keypair validate-distribution — Validate stored keypairs.

Wallet Signing & Response

• signing build-donation <donor> <campaign_id> <amount> [asset] [memo] — Build a donation signing request.
• signing build-campaign <creator> <title> <goal> <deadline> — Build a campaign creation request.
• signing build-custom <xdr> [description] — Wrap an external XDR.
• signing validate <json_file> / signing export <json_file> — Validate or export.
• response process <json> / response validate <file> / response save <json> <file> / response load <file> — Wallet response lifecycle.
• response submit <file> — Placeholder for native network submission (tracked in #37).

Quick Examples

# Inspect active configuration and network
milestonex-cli config
milestonex-cli network
milestonex-cli toggle testnet

# Issue a custom asset and establish trustline
milestonex-cli asset generate
milestonex-cli asset trustline GABJ2... USDC
milestonex-cli asset issue GABJ2... 100

# Build a donation signing request for a donor
milestonex-cli signing build-donation GBJCHU... 1 5000000 XLM "Supporting education"

# Process the wallet's signed response
milestonex-cli response process '{"requestId":"req_123","xdr":"AAAA...","signer":"GBJCHU...","signedAt":1234567890}'

For the full command list, run milestonex-cli with no arguments.

🌐 Wallet Client (wallet_connect.html)

wallet_connect.html is a single-file browser application that provides a full donation UX for any deployed milestonex-campaign contract instance. It is generated by a small Webpack build in the wallet-client/ directory and bundles @stellar/stellar-sdk and @stellar/freighter-api so it has zero runtime dependencies.

Features

• Freighter wallet lifecycle — connect, authorize, and disconnect using the Freighter browser extension.
• Campaign ID query param — share links like wallet_connect.html?campaign=<CONTRACT_ID> to deep-link directly into a specific deployed campaign.
• Campaign state display — shows goal, total raised, donor count, donation count, days remaining, progress bar, and all milestones (Locked / Unlocked / Released) with a ↻ Refresh button.
• Multi-asset donation form — drop-down pre-populated from the campaign's accepted_assets, supports native XLM and any Stellar asset (USDC, NGNT, etc.).
• Soroban XDR signing — builds an invokeHostFunction transaction via stellar-sdk, simulates it to obtain the footprint, presents the assembled XDR to Freighter for signing, then displays the signed XDR for review.
• One-click submit — submits the signed XDR to the Soroban RPC, polls for confirmation, shows the transaction hash with an Explorer link, and auto-refreshes the campaign state.
• Testnet / mainnet — automatically selects the correct Horizon and RPC endpoints based on the network reported by Freighter.

Build

cd wallet-client
npm install
npm run build          # writes wallet_connect.html to the project root

For development with live reload:

npm run dev            # starts webpack-dev-server at http://localhost:3000

Usage

1. Open wallet_connect.html in a browser that has the Freighter extension installed.
2. Paste a deployed campaign contract ID into the Campaign field and click Load (or pass ?campaign=<ID> in the URL).
3. Click Connect Freighter and approve the connection.
4. Enter an amount (in stroops — 1 XLM = 10 000 000 stroops), select an asset, add an optional memo, and click Sign & Donate.
5. Approve the transaction in Freighter.
6. Review the signed XDR in the Signed XDR panel, then click Submit to Network.
7. The transaction hash and a Stellar Explorer link appear once confirmed.

Source layout

wallet-client/
├── package.json          # npm dependencies + build scripts
├── webpack.config.js     # bundles everything into a single HTML file
└── src/
    ├── index.js          # all wallet/signing/campaign logic
    └── template.html     # HTML template (Webpack inlines the JS bundle)

🛠️ Development Setup

Quick Start (New Contributors)

1. Clone the repository

   git clone https://github.com/YOUR_USERNAME/milestonex-contract.git
   cd milestonex-contract

2. Install Rust toolchain (automatically configured by rust-toolchain.toml)

   # Install Rust if not already installed
   curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
   
   # The project will automatically use the correct Rust version and targets
   rustup show

3. Install Soroban CLI

   # Method 1: Install via cargo (recommended for development)
   cargo install soroban-cli
   
   # Method 2: Install via npm (alternative)
   npm install -g soroban-cli
   
   # Verify installation
   soroban --version

4. Build the project

   # Using Make (recommended)
   make build
   
   # Or using cargo directly
   cargo build -p milestonex-campaign --target wasm32v1-none

Prerequisites

• Rust stable toolchain (automatically managed by rust-toolchain.toml)
• wasm32v1-none target (auto-installed by toolchain)
• Soroban CLI for contract deployment and testing

Toolchain Configuration

This project uses rust-toolchain.toml to ensure consistent development environments:

[toolchain]
channel = "stable"
targets = ["wasm32v1-none"]
components = ["rustfmt", "clippy"]

This ensures:

• Consistent Rust version across all contributors
• Required targets are automatically installed
• Essential components (rustfmt, clippy) are included

Development Commands

The project includes a Makefile for common development tasks:

# Build WASM contract
make build

# Run all tests
make test

# Format code
make fmt

# Run linter
make lint

# Clean build artifacts
make clean

# Show all available commands
make help

Building (Manual)

# Build the canonical campaign contract for WASM
cargo build -p milestonex-campaign --target wasm32v1-none --release

# Build the CLI tools
cargo build -p milestonex-tools

# Build entire workspace
cargo build --workspace

Testing

# Run canonical campaign contract tests
cargo test -p milestonex-campaign

# Run all tests
cargo test --workspace

CLI Usage

The commands below match crates/tools/src/main.rs and the canonical status table in docs/deployment.md. deploy and invoke are currently stubs in the CLI binary; use the native stellar contract … commands or make deploy-testnet instead. account is deprecated but still functional — it delegates to keypair commands with a deprecation warning. config init, contract-id, build-donation-tx, submit-tx, verify-tx, prepare-wallet-signing, and complete-wallet-signing shown in older docs are not implemented — see issue #37.

# Inspect resolved configuration / network / vault
cargo run -p milestonex-tools -- config
cargo run -p milestonex-tools -- network
cargo run -p milestonex-tools -- vault
cargo run -p milestonex-tools -- toggle testnet

# Issue assets via the asset namespace
cargo run -p milestonex-tools -- asset config
cargo run -p milestonex-tools -- asset generate
cargo run -p milestonex-tools -- asset trustline GABJ2... USDC
cargo run -p milestonex-tools -- asset issue GABJ2... 100

# Encrypted vault operations
cargo run -p milestonex-tools -- keymanager init-vault "$VAULT_MASTER_PASSWORD"
cargo run -p milestonex-tools -- keymanager vault-status

# Keypair lifecycle (the entry point that replaced `account create|fund`)
cargo run -p milestonex-tools -- keypair generate-master
cargo run -p milestonex-tools -- keypair fund GABJ2... 10

# Wallet signing + response
cargo run -p milestonex-tools -- signing build-donation GBJCHU... 1 5000000 XLM "Supporting education"
cargo run -p milestonex-tools -- response process '{"requestId":"req_123","xdr":"AAAA...","signer":"GBJCHU...","signedAt":1234567890}'

🚀 Quick Start: Deploy Your First Contract

This guide walks you through deploying the canonical campaign contract to testnet and invoking a health-check method.

Prerequisites

1. Install Soroban CLI:

   cargo install soroban-cli

2. Generate a keypair (for testnet):

   soroban keys generate test_account --network testnet

3. Get testnet XLM (optional but recommended for testing):

   • Visit Stellar Testnet Faucet

Step 1: Build the Contract

# Build WASM contracts (campaign + core + token-bridge + common)
make build-wasm

# Or build everything including CLI tools
make build

Step 2: Configure Environment

# Copy the example environment file
cp .env.example .env

# Edit .env and set your admin key:
# SOROBAN_ADMIN_KEY=YOUR_PUBLIC_KEY

Or generate and configure a new key:

# Generate a new keypair
soroban keys generate my_admin --network testnet

# Get the public key
soroban keys list

# Add to .env
SOROBAN_ADMIN_KEY=GA7...

Step 3: Deploy to Testnet

The in-CLI deploy command is a stub today. Use the build-in Makefile target (or scripts/deploy.sh) which is wired into stellar contract deploy for real network output. Tracking: issue #37.

# Deploy via the Makefile wrapper (uses scripts/deploy.sh + stellar-cli)
make deploy-testnet
# Or invoke the deploy script directly:
bash scripts/deploy.sh testnet

Expected output:

ℹ️  Using optimized WASM: target/wasm32v1-none/release/milestonex_core.wasm
🚀 Deploying to testnet...
   RPC: https://soroban-testnet.stellar.org:443
   WASM: target/wasm32v1-none/release/milestonex_core.wasm
✅ Contract deployed!
📝 Contract ID: CB7...ABC
💾 Deployment record saved to deployments/testnet.json
✅ Contract ID stored in .milestonex_contract_id

Step 4: Invoke the ping Method

The in-CLI invoke command is also a stub. Use stellar contract invoke natively against your deployed contract ID.

# Read the contract ID that Step 3 wrote out
CONTRACT_ID=$(cat .milestonex_contract_id)

# Invoke a contract method (replace `version` with any contract method such as `ping`)
stellar contract invoke \
  --id "$CONTRACT_ID" \
  --source test_account \
  --network testnet \
  -- version

Expected output:

🔄 Invoking method 'version' on network: testnet
📝 Using contract ID: CB7...ABC
✅ Invocation successful!
📤 Result: <contract version bytes>

Step 5: Check Deployment

# View the deployed contract ID written by scripts/deploy.sh
cat .milestonex_contract_id

# View the per-network deployment record
cat deployments/testnet.json

# View active network configuration
cargo run -p milestonex-tools -- network

Using Sandbox (Local Development)

For local testing without testnet:

# Start local sandbox (requires Docker)
make sandbox-start

# Deploy to sandbox (uses scripts/deploy.sh sandbox)
make deploy-sandbox

# Invoke on sandbox natively
CONTRACT_ID=$(cat .milestonex_contract_id)
stellar contract invoke \
  --id "$CONTRACT_ID" \
  --source test_account \
  --rpc-url http://localhost:8000/soroban/rpc \
  --network-passphrase "Standalone Network ; February 2017" \
  -- version

Troubleshooting

• "WASM file not found": Run make build-wasm to build the contracts first.
• "Unknown command" or "coming soon": You ran an milestonex-cli command that is still a stub (deploy, invoke). Run cargo run -p milestonex-tools with no arguments to see which commands are actually implemented, and follow docs/deployment.md.
• "No contract ID found": Run make deploy-testnet first — the scripts/deploy.sh wrapper writes the ID to .milestonex_contract_id.
• "Configuration error": Run cargo run -p milestonex-tools -- config to inspect resolved environment values.
• "soroban: command not found": Install with cargo install --locked stellar-cli --features opt.

📌 Features

🎯 For Donors

• Discover global fundraising campaigns
• Donate in XLM or Stellar assets
• Wallet integration (Freighter, Albedo, Lobstr)
• On-chain transparency: verify all transactions

🎯 For Creators

• Create social impact projects
• Accept multi-asset contributions
• Real-time donation tracking
• Withdraw funds directly on-chain

🎯 For Admins

• Campaign approval workflow
• User & KYC management
• Analytics dashboard

🏗️ Architecture Overview

MilestoneX Blockchain Layer is built with:

• Stellar Testnet / Mainnet support
• Donation verification
• On-chain withdrawal system
• Asset‑agnostic design

💰 Fee Estimation System

MilestoneX includes a comprehensive fee estimation service that provides accurate transaction fee calculations, surge pricing detection, and multi-currency conversion.

Features

• Real-time Fee Estimation: Fetch current base fees from Stellar Horizon
• Surge Pricing Detection: 4-level detection (Normal, Elevated, High, Critical)
• Multi-Currency Display: Convert fees to 10+ supported currencies
• Caching: 5-minute TTL cache to reduce API calls
• Fee History Tracking: 1000+ records for analytics and trend detection

Quick Start

use fee::FeeEstimationService;

#[tokio::main]
async fn main() -> Result<()> {
    let service = FeeEstimationService::public_horizon();
    
    // Estimate fee for 2-operation donation
    let fee_info = service.estimate_fee(2).await?;
    println!("Fee: {:.8} XLM", fee_info.total_fee_xlm);
    
    // Check for surge pricing
    if fee_info.is_surge_pricing {
        println!("⚠️ Network surging at {}%!", fee_info.surge_percent as i64);
    }
    
    Ok(())
}

Key Constants

• Base Fee: 100 stroops (0.00001 XLM)
• Conversion: 1 XLM = 10,000,000 stroops
• Cache TTL: 300 seconds (5 minutes)

📌 How to Contribute

1. Fork the Repository

Click the “Fork” button in the top‑right of the GitHub repo and clone your fork:

git clone https://github.com/YOUR_USERNAME/milestonex-contract.git
cd milestonex-contract

2. Create a Branch

git checkout -b feature/add-donation-flow

3. Commit Messages

Use conventional commits:

feat: add wallet connection modal
fix: resolve donation API error
docs: update project README
refactor: clean up project creation form

4. Submitting a Pull Request (PR)

Push your branch:

git push origin feature/add-donation-flow

Open a Pull Request from your fork back to the main branch.

Security Scans

This project uses cargo-audit and cargo-deny to maintain high security standards and license compliance.

Local Scans

You can run the security scans locally using the following commands:

• Check for vulnerabilities:

  make audit

• Check for license and ban policies:

  make deny

Resolving Failures

Vulnerabilities (cargo audit)

If a vulnerability is found, you should:

1. Update dependencies: Run cargo update to see if a newer version of the crate resolves the issue.
2. Ignore (Temporary): If a fix is not available and you have audited the vulnerability, you can temporarily ignore it by adding it to the [advisories] -> ignore list in the deny configuration.

License/Ban Policy (cargo deny)

If a license or ban policy violation is found:

1. Check Licenses: Ensure all dependencies use approved licenses. If a new license needs to be allowed, update the allow list in deny.toml.
2. Banned Crates: If a crate is banned, you must find an alternative or justify its use and add it to the skip list in deny.toml.

Automated CI

Security scans are automatically run on every push and pull request. CI will fail if any known vulnerabilities or policy violations are detected.

📜 License

MIT License — free to use, modify, and distribute.

Soroban Configuration (networks)

This workspace includes a deterministic, strongly-typed Soroban network configuration system.

Add a network (example CLI stub):

soroban config network add <name> \
   --rpc-url <url> \
   --network-passphrase "<passphrase>"

List networks (profiles in soroban.toml):

soroban config network ls

Select a network (this sets the active profile name; loader reads SOROBAN_NETWORK):

soroban config network use <name>

Environment variable override behavior

• SOROBAN_NETWORK selects a profile (e.g. testnet, mainnet, sandbox).
• SOROBAN_RPC_URL and SOROBAN_NETWORK_PASSPHRASE override profile values when set.

Verify the resolved network with the included CLI tool:

cargo run -p milestonex-tools -- network

See .env.example for a safe example of environment variables you can copy to .env.