Skip to content

chuci-qin/1024-settlement-program

BranchesTags

Repository files navigation

1024EX Settlement Program

A fully on-chain settlement program for decentralized exchanges on Solana/1024Chain

License: MIT Rust Solana

🌟 Features

  • ✅ Complete Trade Data: Store all 19 fields on-chain (vs 7 fields in Memo)
  • ✅ Unlimited Capacity: 10KB+ per settlement (vs 566 bytes Memo limit)
  • ✅ Data Integrity: SHA256 hash + volume + fees verification
  • ✅ Fully Decentralized: No IPFS, no off-chain storage needed
  • ✅ Auditable: Complete trade history verifiable by anyone
  • ✅ Rent-Exempt Storage: Permanent on-chain data storage

📊 Why Settlement Program?

Feature Memo Program Settlement Program Improvement
Data Capacity 566 bytes 10KB+ unlimited 17x+
Trade Fields 7 summary fields 19 complete fields 2.7x
Verification None Hash + calculation 100%
Decentralization Needs IPFS Fully on-chain 100%
Audit Trail Limited Complete Complete

🏗️ Architecture

Complete Trade Data Structure (19 Fields)

pub struct CompleteTrade {
    // Basic Info (2)
    pub id: String,
    pub market: String,
    
    // Price & Quantity (3, e6 format)
    pub price_e6: i64,
    pub qty_e6: i64,
    pub notional_e6: i64,
    
    // Direction & Time (3)
    pub taker_side: Side,
    pub ts_ms: i64,
    pub engine_seq: u64,
    
    // Order Association (2)
    pub taker_order_id: String,
    pub maker_order_id: String,
    
    // Account Info (4)
    pub taker_account_id: String,
    pub maker_account_id: String,
    pub taker_wallet: Pubkey,
    pub maker_wallet: Pubkey,
    
    // Leverage (2)
    pub taker_leverage: u32,
    pub maker_leverage: u32,
    
    // Fees (4)
    pub taker_fee_e6: i64,
    pub maker_fee_e6: i64,
    pub fee_rate_taker_bp: u32,
    pub fee_rate_maker_bp: u32,
}

Data Flow

Trading Engine
    ↓
Batch Trades (100ms window)
    ↓
Relayer Backend
    ├─ Convert to SettlementData
    ├─ Calculate hash, volume, fees
    ├─ Serialize (Borsh)
    └─ Create transaction
        ↓
Settlement Program (On-Chain)
    ├─ Verify authority signature
    ├─ Validate data integrity
    ├─ Derive PDA: settlement/<batch_id>
    ├─ Create account (pay rent)
    └─ Store complete data
        ↓
1024Chain Confirmed
    ├─ Settlement account created
    ├─ All 19 fields stored
    └─ Queryable by anyone

🚀 Quick Start

Prerequisites

  • Rust 1.90+ (nightly recommended for BPF compilation)
  • Solana CLI 3.0+
  • Docker (for BPF compilation)

Build

Option 1: Using Docker (Recommended)

# Pull Solana development image
docker pull solanalabs/rust:latest

# Build BPF
docker run -it \
  -v $(pwd):/workspace \
  solanalabs/rust:latest \
  bash -c "cd /workspace && cargo build-sbf"

Option 2: Local Build

# Build library version (for testing)
cargo build --lib

# Run tests
cargo test --lib

# Build BPF (requires nightly with edition2024 support)
cargo build-sbf

Deploy

# Configure Solana CLI
solana config set --url https://testnet-rpc.1024chain.com/rpc/
solana config set --keypair <your-keypair.json>

# Deploy program
solana program deploy target/deploy/settlement_program.so

# Note the Program ID from output
# Program Id: <YOUR_PROGRAM_ID>

📦 Integration

Add to Your Project

[dependencies]
settlement-program = { git = "https://github.com/chuci-qin/1024-settlement-program" }

Basic Usage

use settlement_program::{
    CompleteTrade, SettlementData, SettlementInstruction, Side,
};
use solana_sdk::{
    instruction::Instruction,
    pubkey::Pubkey,
    transaction::Transaction,
};

// Create settlement data
let settlement = SettlementData {
    batch_id: "batch_abc123".to_string(),
    timestamp_ms: chrono::Utc::now().timestamp_millis(),
    relayer: relayer_pubkey,
    trades: vec![
        CompleteTrade {
            id: "trade_001".to_string(),
            market: "BTC-PERP".to_string(),
            price_e6: 105315000000,  // 105315 USDC
            qty_e6: 1000,             // 0.001 BTC
            notional_e6: 105315000,   // 105.315 USDC
            taker_side: Side::Sell,
            // ... other 14 fields
        },
    ],
    accounts: vec![],
    block_height: 0,
    tx_signature: [0u8; 64],
    total_volume_e6: 105315000,
    total_fees_e6: 63188,
    data_hash: [0u8; 32],  // Will be calculated
};

// Create instruction
let instruction_data = SettlementInstruction::RecordSettlement {
    data: settlement,
};

// Derive PDA
let (settlement_pda, _bump) = Pubkey::find_program_address(
    &[b"settlement", batch_id.as_bytes()],
    &program_id,
);

// Create and send transaction
// ... (see examples/ for complete code)

📚 Documentation

🧪 Testing

# Run all tests
cargo test --lib

# Run specific test
cargo test test_validate_correct_data

# Test results
# running 7 tests
# test utils::tests::test_hash_consistency ... ok
# test utils::tests::test_hash_uniqueness ... ok
# test utils::tests::test_validate_batch_id ... ok
# test utils::tests::test_validate_correct_data ... ok
# test utils::tests::test_validate_empty_trades ... ok
# test utils::tests::test_validate_invalid_volume ... ok
# test result: ok. 7 passed; 0 failed

🔧 Development

Project Structure

settlement-program/
├── src/
│   ├── lib.rs              # Program entrypoint
│   ├── state.rs            # Data structures (CompleteTrade, etc.)
│   ├── processor.rs        # Core logic (verify, create, store)
│   ├── instruction.rs      # Instruction definitions
│   ├── error.rs            # Error types
│   └── utils.rs            # Validation and hash functions
├── tests/
│   └── integration_test.rs # Integration tests
├── examples/
│   ├── basic_settlement.rs
│   └── query_settlement.rs
├── docs/
│   ├── ARCHITECTURE.md
│   ├── DEPLOYMENT.md
│   ├── API.md
│   └── TRADE_FIELDS.md
└── Cargo.toml

Contributing

See CONTRIBUTING.md for development guidelines.

💰 Cost Analysis

Storage Cost

Trades/Batch Account Size Rent/Year Status
1-10 ~5KB 0.005 N1024 ✅ Supported
10-50 ~20KB 0.02 N1024 ✅ Supported
50-100 ~40KB 0.04 N1024 ✅ Supported
100-500 ~160KB 0.16 N1024 ✅ Supported

Rent-exempt storage means data is permanently stored

Performance

Metric Target Actual
Submission Latency <500ms ~300ms
Serialization Time <1ms <1ms
Gas Fee/Settlement <0.01 N1024 ~0.005 N1024
Throughput Support 1000+ TPS ✅

🌟 Use Cases

1. User Verification

Users can independently verify every trade detail:

  • Exact execution price
  • Fees charged
  • Order matching accuracy

2. Regulatory Compliance

Complete audit trail for regulators:

  • All 19 fields recorded
  • Immutable on-chain data
  • Verifiable by third parties

3. Dispute Resolution

Objective evidence for dispute resolution:

  • Complete trade history
  • Price and fee calculations
  • Time-stamped records

4. Third-Party Analytics

Enable independent market analysis:

  • Complete trade data
  • No platform dependency
  • Open access

🔐 Security

Data Integrity

  • ✅ SHA256 hash verification
  • ✅ Total volume calculation check
  • ✅ Total fees calculation check
  • ✅ Batch ID format validation
  • ✅ Authority signature verification

Access Control

  • Settlement authority (hardcoded in v1.0)
  • PDA-based account creation
  • Immutable data after creation

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🤝 Acknowledgments

  • Built for 1024EX - A fully decentralized exchange
  • Powered by Solana and 1024Chain
  • Inspired by the principles of transparency and decentralization

📞 Support

🚀 Roadmap

  • Core settlement program (v1.0)
  • 19-field complete trade data
  • Data integrity verification
  • TypeScript/JavaScript client SDK
  • Python client SDK
  • Settlement query API
  • Update settlement functionality
  • Multi-signature authority support

Built with ❤️ for the decentralized future

Making exchange settlements fully transparent and verifiable

About

1024-settlement-program for 1024ex

Resources

Readme

License

MIT license

Contributing

Contributing
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

No packages published

Languages