Kosmos Contracts

Smart contracts for the KosmosShop decentralized multi-vendor e-commerce marketplace built with Soroban on the Stellar blockchain.

Kosmos Contracts implement the core logic for shops, products, orders, escrow, and payments—ensuring trustless, transparent transactions between buyers and sellers.

🌟 Features

• Shop Contract - Seller shop creation and management
• Product Contract - Product listing and inventory
• Order Contract - Order creation and tracking
• Escrow Contract - Secure fund holding and release
• Marketplace Contract - Platform governance and fees
• Reputation Contract - Seller and product ratings
• Multi-token Support - XLM, USDC, and other Stellar assets
• Dispute Resolution - Built-in conflict resolution
• Gas Optimized - Efficient contract execution
• Upgrade Mechanism - Safe contract updates

🛠️ Tech Stack

• Language: Rust
• Platform: Stellar Soroban (Smart Contract Platform)
• Framework: Soroban SDK
• Testing: Rust test framework + Soroban testing utilities
• Package Manager: Cargo
• Blockchain: Stellar Testnet / Mainnet

📋 Prerequisites

• Rust >= 1.73.0
• Soroban CLI latest version
• Stellar SDK for Rust
• Docker (optional, for consistent environment)

🚀 Installation

1. Install Rust

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env
rustup update

2. Install Soroban CLI

cargo install --locked soroban-cli

3. Clone Repository

git clone https://github.com/yourusername/kosmos-contracts.git
cd kosmos-contracts

4. Build Contracts

soroban contract build

Compiled WASM files in target/wasm32-unknown-unknown/release/

📁 Project Structure

kosmos-contracts/
├── contracts/
│   ├── marketplace/          # Platform governance
│   │   ├── src/
│   │   │   ├── lib.rs
│   │   │   ├── contract.rs
│   │   │   └── error.rs
│   │   └── Cargo.toml
│   ├── shop/                 # Shop management
│   │   ├── src/
│   │   │   ├── lib.rs
│   │   │   ├── contract.rs
│   │   │   └── error.rs
│   │   └── Cargo.toml
│   ├── product/              # Product listings
│   │   ├── src/
│   │   │   ├── lib.rs
│   │   │   ├── contract.rs
│   │   │   └── error.rs
│   │   └── Cargo.toml
│   ├── order/                # Order processing
│   │   ├── src/
│   │   │   ├── lib.rs
│   │   │   ├── contract.rs
│   │   │   └── error.rs
│   │   └── Cargo.toml
│   ├── escrow/               # Escrow management
│   │   ├── src/
│   │   │   ├── lib.rs
│   │   │   ├── contract.rs
│   │   │   ├── token.rs
│   │   │   └── error.rs
│   │   └── Cargo.toml
│   └── reputation/           # Ratings & reviews
│       ├── src/
│       │   ├── lib.rs
│       │   ├── contract.rs
│       │   └── error.rs
│       └── Cargo.toml
├── Cargo.toml                # Workspace config
├── Cargo.lock
└── README.md

🏗️ Contract Architecture

1. Marketplace Contract

Purpose: Platform governance, fees, and settings

Responsibilities:

• Initialize the marketplace with admin settings
• Manage platform fee percentages
• Handle fee withdrawals to platform wallet
• Register and manage admin addresses
• Track platform-wide statistics

2. Shop Contract

Purpose: Seller shop management

Responsibilities:

• Create new shops with seller information
• Update shop details (name, description, branding)
• Retrieve shop information and metadata
• Toggle shop active/inactive status
• List all shops owned by a seller
• Manage shop followers and reputation

3. Product Contract

Purpose: Product listings and inventory

Responsibilities:

• Create products with details and pricing
• Update product information and pricing
• Manage product inventory and stock levels
• Delete products from listings
• Retrieve product details by ID
• List products by shop
• Track product categories and tags

4. Order Contract

Purpose: Order creation and tracking

Responsibilities:

• Create new orders with buyer and shop details
• Track order status through lifecycle
• Store order items and quantities
• Confirm delivery status
• List orders by buyer
• List orders by shop
• Track order timestamps and metadata

5. Escrow Contract

Purpose: Secure fund holding and release

Responsibilities:

• Hold buyer funds securely during transactions
• Release funds to seller upon delivery confirmation
• Process refunds back to buyer if needed
• Freeze funds during dispute periods
• Track escrow status for each order
• Support multiple token types (XLM, USDC, etc.)
• Maintain transparent escrow balance records

6. Reputation Contract

Purpose: Seller and product ratings

Responsibilities:

• Store product reviews with ratings and comments
• Store seller reviews and ratings
• Retrieve reviews for products
• Retrieve reviews for sellers
• Calculate seller reputation scores
• Track review authors and timestamps
• Manage review visibility and moderation

🧪 Testing

# Run all tests
cargo test --release

# Run specific contract tests
cargo test -p escrow-contract --release

# Run with Soroban testing
soroban contract test --release

# Coverage report
cargo tarpaulin --release

Test suite covers functionality, edge cases, and security validation for all contracts.

🚀 Deployment

1. Setup Stellar Network

Set environment variables for your target network:

# For testnet
export SOROBAN_RPC_URL=https://soroban-testnet.stellar.org
export SOROBAN_NETWORK_PASSPHRASE="Test SDF Network ; September 2015"

# For mainnet
export SOROBAN_RPC_URL=https://soroban-mainnet.stellar.org
export SOROBAN_NETWORK_PASSPHRASE="Public Global Stellar Network ; September 2015"

2. Create Deployer Account

Generate a keypair for contract deployment:

soroban keys generate deployer

Fund the account from the Stellar faucet (testnet only) or transfer funds from an existing account.

3. Build & Deploy Contracts

Build all contracts:

soroban contract build

Deploy each contract to the network using the Soroban CLI.

4. Initialize Marketplace

After deploying the marketplace contract, initialize it with admin settings and platform parameters.

5. Deploy Other Contracts

Deploy shop, product, order, escrow, and reputation contracts in the order specified in the deployment guide.

Deployment Script

A deployment script is provided to automate the process of building and deploying all contracts to testnet or mainnet.

📋 Contract Addresses

After deployment, store contract addresses in your backend environment variables for blockchain interactions.

🔐 Security Audits

Before mainnet deployment:

1. Internal Review - Code walkthrough and security checklist
2. External Audit - Professional security firm conducts full contract audit
3. Bug Bounty - Launch bug bounty program for community review

🔧 Contract Upgrades

Safe Upgrade Pattern

Contracts include upgrade mechanisms that:

• Require admin authorization
• Preserve state during upgrades
• Allow safe migration of data
• Include fallback options for rollback

Migration Strategy

1. Deploy new contract version to testnet
2. Run migration function to transfer state
3. Validate all data transferred correctly
4. Test thoroughly on testnet
5. Deploy to mainnet in controlled manner

📊 Gas Optimization

Reduce Execution Costs

• Minimize state writes per transaction
• Use efficient data structures
• Batch operations when possible
• Cache frequently accessed data
• Optimize contract method signatures

Benchmarking

Gas usage for common operations is documented to help understand cost implications of different flows.

📝 Error Handling

Standard Error Types

• UnauthorizedCaller - Caller lacks required permissions
• InvalidShopId - Referenced shop doesn't exist
• InvalidProductId - Referenced product doesn't exist
• InvalidOrderId - Referenced order doesn't exist
• InsufficientFunds - Not enough funds for operation
• ProductOutOfStock - Product inventory exhausted
• OrderAlreadyFulfilled - Can't modify completed order
• DisputeInProgress - Can't take action during dispute
• InvalidAmount - Amount doesn't meet requirements
• ContractError - General contract execution error

All operations return detailed error messages for debugging and user feedback.

🤝 Contributing

1. Fork repository
2. Create feature branch for your changes
3. Test thoroughly with the Rust test suite
4. Ensure code passes all security checks
5. Commit with clear, descriptive messages
6. Push to your fork and open a Pull Request

📄 License

MIT License - see LICENSE file for details

🆘 Support

For issues and questions:

• Open GitHub issue
• Check Stellar documentation: https://developers.stellar.org/docs

🔗 Related Repositories

• Kosmos API - NestJS backend
• Kosmos Frontend - Next.js frontend

📚 Documentation

• Soroban Documentation
• Stellar SDK Rust
• Stellar Smart Contract Platform
• Cargo Book