Deshare Protocol

A comprehensive blockchain-based ecosystem management protocol built on Solidity 0.8.24, providing secure, upgradeable smart contracts for managing partner ecosystems, merchant onboarding, device management, and transaction processing through the Deshare contract.

📚 Documentation

📖 Auto-Generated Contract Documentation - Complete API documentation auto-generated from NatSpec comments using Foundry's forge doc command. Includes detailed contract interfaces, function signatures, parameter descriptions, and usage examples extracted directly from the source code.

Generate Documentation Locally

# Generate documentation from NatSpec comments
forge doc

# Serve documentation locally
forge doc --serve --port 3000

# Build documentation for deployment
forge doc --build

The documentation includes:

• Contract APIs: Auto-generated from NatSpec comments in source code
• Function Signatures: Complete interface documentation with parameters and return values
• Integration Examples: Code samples extracted from contract comments
• Deployment Guides: Based on the deployment scripts and configurations

🏗️ Architecture Overview

The Deshare Protocol is built around the Deshare contract with a secure, upgradeable proxy architecture:

├── Deshare.sol                  # Core Deshare Protocol contract
├── PowerPass.sol                # ERC721 NFT contract for access tokens
├── ShareXWallet.sol             # User wallet contract for token & NFT operations
├── ShareXWalletManager.sol      # Wallet management system (upgradeable)
├── interfaces/                  # Interface definitions
│   ├── IDeshare.sol             # Main contract interface
│   ├── IShareXWallet.sol        # Wallet interface
│   └── IShareXWalletManager.sol # Wallet manager interface
├── libraries/                   # Shared utilities
│   ├── DataTypes.sol            # Data structures for protocol entities
│   ├── Errors.sol               # Custom error definitions
│   └── Events.sol               # Event definitions for tracking
├── script/                      # Deployment and upgrade scripts
│   └── Deploy.s.sol             # Foundry deployment script
└── deploy-config/               # Network-specific configurations
    ├── local.json               # Local development config
    ├── bsc-testnet.json         # BSC Testnet config
    └── devnet.json              # Development network config

🚀 Key Features

Upgradeable Proxy Architecture

• TransparentUpgradeableProxy: Secure upgrade mechanism with role separation
• Proxy Admin Owner: Controls proxy upgrades and admin functions
• Deshare Admin: Controls business logic and operational functions
• Implementation Contract: Upgradeable Deshare business logic

Partner Ecosystem Management

• Partner Registration: Complete partner onboarding with verification codes
• Partner Profiles: Business type classification and country tracking
• Partner Analytics: Business type statistics and reporting
• Verification System: Built-in compliance and verification tracking

Merchant Management System

• Merchant Onboarding: Streamlined merchant registration process
• Geographic Organization: Location-based merchant management
• Merchant Categories: Support for various business types
• Regional Analytics: Location-based merchant statistics

Device Registration & Tracking

• Device Management: Registration and tracking of various device types
• Device Association: Link devices to partners and merchants
• Device Validation: Ensure device dependencies exist before registration
• Status Monitoring: Track device registration and operational status

Transaction Processing

• Batch Transaction Processing: High-throughput transaction batch handling with compressed data storage
• Transaction Validation: Comprehensive data validation and verification
• Event-Driven Architecture: Real-time transaction tracking through events
• Data Integrity: Immutable transaction records on blockchain
• Compression Support: Automatic compression/decompression for efficient storage using LibZip

Enhanced Statistics System

• User-Friendly Stats: New getDetailedStats() method returns descriptive, labeled statistics instead of anonymous tuples
• Backward Compatibility: Original getStats() method remains unchanged for existing integrations
• Rich Metadata: Includes metric names, descriptions, timestamps, and contract version information
• Self-Documenting: Each statistic includes a human-readable description of what it represents

PowerPass NFT System

• Standard ERC721: OpenZeppelin-based NFT contract with gas optimizations
• Access Control: Role-based permissions with admin and minter roles
• Supply Management: Fixed maximum supply of 5000 tokens with enforcement
• Metadata Support: Full token URI functionality for rich metadata
• Mint/Burn Operations: Secure token lifecycle management
• Custodial Minting: ShareX wallet-based custodial minting system that bypasses sales logic

ShareX Wallet System

• User Wallet Management: Individual wallet creation and management for users with multi-user support
• Multi-Token Support: Native ETH, ERC20 tokens, and ERC721 NFT operations in a single wallet
• PowerPass Integration: Direct NFT minting, transferring, and burning capabilities through wallet system
• Batch Operations: Efficient multiple token transfers to multiple recipients in single transactions
• Gas Optimization: Advanced gas-saving techniques based on RareSkills optimization patterns
• Upgradeable Architecture: Proxy-based wallet management system for future enhancements
• Access Control: Role-based permissions with comprehensive admin-controlled operations
• Multicall Pattern: Efficient aggregated contract calls for complex operations

Security & Access Control

• Role-Based Access Control: Multi-tier permission system with admin and operator roles
• Reentrancy Protection: Comprehensive attack prevention mechanisms
• Input Validation: Robust parameter checking and data sanitization
• Upgrade Security: Secure contract upgrade procedures with proper authorization

🔧 Core Data Structures

Partner Management

• PartnerInfo: Partner ecosystem data with verification codes and business classification
• Business Classification: Support for various business types with statistical tracking
• Geographic Coverage: Country-specific partner management with ISO2 codes
• Partner Analytics: Business type statistics and partner counting

Merchant Infrastructure

• MerchantInfo: Complete merchant data with geographic organization
• Location Management: Region-based organization with location IDs
• Merchant Categories: Flexible business type categorization system
• Regional Analytics: Location-based merchant statistics and counting

Device Ecosystem

• DeviceInfo: Device registration data linked to partners and merchants
• Device Dependencies: Validation of partner and merchant associations
• Device Types: Support for various device categories and classifications
• Registration Tracking: Device registration with timestamp tracking

Transaction Processing

• TransactionBatch: High-level batch information with device association and metadata
• Transaction Data: JSON-formatted transaction data stored as compressed bytes
• Batch Processing: Efficient handling of multiple transaction records in a single batch
• Data Compression: Automatic compression/decompression using LibZip for storage efficiency
• Data Integrity: Immutable transaction records with comprehensive validation

Geographic Organization

• CountryInfo: Country registration system with ISO2 code management
• Regional Statistics: Location-based analytics and merchant distribution
• Geographic Validation: Country existence verification for registrations

🔧 Usage Examples

Deshare Protocol Integration

// Deploy Deshare with proxy
Deshare deshare = Deshare(proxyAddress);

// Register a protocol partner
PartnerParams memory partner = PartnerParams({
    partnerCode: "DESHARE001",
    partnerName: "Deshare Solutions Inc",
    iso2: "US",
    verification: "KYB12345",
    description: "Blockchain ecosystem infrastructure provider",
    businessType: "Technology"
});
deshare.registerPartner(partner);

// Register merchants in the ecosystem
MerchantParams memory merchant = MerchantParams({
    merchantName: "Coffee Shop Downtown",
    merchantId: "MERCHANT_CS001",
    description: "Coffee and pastry retail shop",
    iso2: "US",
    locationId: "NYC_DOWNTOWN_001",
    location: "123 Main St, New York, NY",
    merchantType: "Retail_Food",
    verification: "MER_VER_001"
});
deshare.registerMerchant(merchant);

// Register devices in the ecosystem
DeviceParams memory device = DeviceParams({
    deviceId: "DEVICE_001",
    deviceType: "Terminal",
    partnerCode: "DESHARE001",
    merchantId: "MERCHANT_CS001"
});
deshare.registerDevice(device);

Transaction Batch Processing

// Prepare transaction data as JSON string
string memory jsonData = '[{"userId":"USER001","amount":100,"timestamp":1234567890,"type":"purchase"},{"userId":"USER002","amount":200,"timestamp":1234567891,"type":"service"}]';

// Compress transaction data for efficient storage
bytes memory compressedData = LibZip.flzCompress(bytes(jsonData));

// Upload transaction batch with compressed data
UploadBatchParams memory batchParams = UploadBatchParams({
    deviceId: "DEVICE_001",
    dateComparable: 20250703,     // Date in YYYYMMDD format
    orderCount: 2,                // Number of transactions in batch
    totalAmount: 300,             // Total amount of all transactions
    transactionData: compressedData // Compressed JSON transaction data
});

deshare.uploadTransactionBatch(batchParams);

// Retrieve transaction data (automatically decompressed)
string memory retrievedData = deshare.getTransactionData(1);
// retrievedData will contain the original JSON string

Contract Upgrade Process

// Deploy new Deshare implementation
Deshare newImplementation = new Deshare(adminAddress);

// Upgrade proxy (only proxy admin can execute)
ITransparentUpgradeableProxy(proxyAddress).upgradeToAndCall(
    address(newImplementation),
    abi.encodeWithSignature("initializeV2()")
);

// Verify upgrade success
Version memory newVersion = Deshare(proxyAddress).getVersion();
require(
    newVersion.major >= previousVersion.major,
    "Upgrade failed"
);

PowerPass NFT Integration

PowerPass is an ERC721 NFT contract with sophisticated whitelist-based sales rounds and discount systems.

Sales Configuration

# Configure two-round sales system with timestamps and pricing
source .env && cast send 0x3d3624D578bf7bF81a76633a355320B3123c70f7 \
  "configureSalesRounds((uint128,uint128,uint128,uint128,uint128,uint128))" \
  "(PRIORITY_START,PRIORITY_END,GENERAL_START,GENERAL_END,50000000,5000000)" \
  --rpc-url $RPC_URL --private-key $PRIVATE_KEY

# Parameters:
# - priorityStartTime/priorityEndTime: Priority round for MAGNA/NOVA holders
# - generalStartTime/generalEndTime: General round for all stakers
# - standardPrice: 50000000 (50 USDT with 6 decimals)
# - discountCodeDiscount: 5000000 (5 USDT discount with 6 decimals)

Whitelist Management

# Set regular whitelist allocations (priority and general rounds)
source .env && cast send 0x3d3624D578bf7bF81a76633a355320B3123c70f7 \
  "batchSetWhitelists(address[],uint256[],uint256[])" \
  "[0xUSER1,0xUSER2]" \
  "[10,5]" \
  "[10,10]" \
  --rpc-url $RPC_URL --private-key $PRIVATE_KEY

# Set Nova discount allocations (80% discount: 40 USDT instead of 50 USDT)
source .env && cast send 0x3d3624D578bf7bF81a76633a355320B3123c70f7 \
  "batchSetNovaDiscounts(address[],uint256[])" \
  "[0xUSER1,0xUSER2]" \
  "[10,5]" \
  --rpc-url $RPC_URL --private-key $PRIVATE_KEY

Discount Code Management

# Generate discount code hashes
python3 -c "
import hashlib
codes = ['POWERPASS2024', 'EARLY_BIRD']
for code in codes:
    hash_val = '0x' + hashlib.sha256(code.encode()).hexdigest()
    print(f'{code} -> {hash_val}')
"

# Add discount codes to contract
source .env && cast send 0x3d3624D578bf7bF81a76633a355320B3123c70f7 \
  "addDiscountCodes(bytes32[])" \
  "[0x76e0436f2bbe1a2ea4010b9baea8f6515e092fba88c16588f111d27cc5651463]" \
  --rpc-url $RPC_URL --private-key $PRIVATE_KEY

Active Discount Codes

The following discount codes are active on both BSC Testnet and BSC Mainnet:

Query discount code usage count:

# Check usage count for a specific discount code (e.g., SHARE)
cast call $POWERPASS_PROXY "getDiscountCodeUsageCount(bytes32)" \
  0x6ecee827156c952a04f57a0610c4ec267270d7865b010b3163aa1d3657d9a421 \
  --rpc-url $RPC_URL

Minting Process

# 1. Check user's mint status and eligibility
source .env && cast call 0x3d3624D578bf7bF81a76633a355320B3123c70f7 \
  "getMintStatus(address)" 0xUSER_ADDRESS --rpc-url $RPC_URL

# 2. Approve USDT spending (example: 80 USDT for 2 NFTs with Nova discount)
source .env && cast send 0x6350a32a4406469608B5D93A77572e140b5F3D73 \
  "approve(address,uint256)" \
  0x3d3624D578bf7bF81a76633a355320B3123c70f7 \
  80000000 \
  --rpc-url $RPC_URL --private-key $PRIVATE_KEY

# 3. Mint PowerPass NFTs
# With Nova discount (automatic 80% discount)
source .env && cast send 0x3d3624D578bf7bF81a76633a355320B3123c70f7 \
  "mint(uint256,string)" 2 "" \
  --rpc-url $RPC_URL --private-key $PRIVATE_KEY

# With discount code (5 USDT discount)
source .env && cast send 0x3d3624D578bf7bF81a76633a355320B3123c70f7 \
  "mint(uint256,string)" 1 "POWERPASS2024" \
  --rpc-url $RPC_URL --private-key $PRIVATE_KEY

# 4. Verify minting results
source .env && cast call 0x3d3624D578bf7bF81a76633a355320B3123c70f7 \
  "balanceOf(address)" 0xUSER_ADDRESS --rpc-url $RPC_URL

PowerPass Pricing Structure

Key Features:

• Maximum Supply: 5000 NFTs
• Payment Token: ShareXUSDT (6 decimals)
• Nova Discount: 80% of standard price (20% savings)
• Discount Codes: 5 USDT reduction per NFT
• Two Sales Rounds: Priority (MAGNA/NOVA holders) and General (all stakers)
• Channel Tracking: Web3 and Web2 mint counts via getChannelMintedCounts()

// Contract integration example
PowerPass powerPass = PowerPass(0x3d3624D578bf7bF81a76633a355320B3123c70f7);

// Check user's mint status
PowerPass.MintStatus memory status = powerPass.getMintStatus(userAddress);
// status.priorityRemaining, status.generalRemaining, status.novaDiscountRemaining
// status.standardPrice (50 USDT), status.novaDiscountPrice (40 USDT)

// Get whitelist information
PowerPass.WhitelistInfo memory info = powerPass.getWhitelistInfo(userAddress);
// info.priorityAllocation, info.generalAllocation, info.priorityMinted, etc.

Enhanced Statistics Usage

// Traditional stats (backward compatible)
StatsInfo memory basicStats = deshare.getStats();
// Returns tuple: (partnersCount, merchantsCount, devicesCount, batchesCount, countriesCount)

// Enhanced stats with user-friendly labels
DetailedStatsInfo memory detailedStats = deshare.getDetailedStats();

// Access descriptive information
console.log("Metric: %s", detailedStats.metricNames[0]);          // "Partners"
console.log("Count: %d", detailedStats.basicStats.partnersCount); // 0
console.log("Description: %s", detailedStats.metricDescriptions[0]);
// "Total number of registered business partners in the ecosystem"

// Access metadata
console.log("Last Updated: %d", detailedStats.lastUpdated);       // 1753155363
console.log("Contract Version: v%d.%d.%d",
    detailedStats.contractVersion.major,    // 1
    detailedStats.contractVersion.minor,    // 0
    detailedStats.contractVersion.patch);   // 0

ShareX Wallet System Usage

// Deploy ShareX Wallet Manager with proxy
ShareXWalletManager manager = ShareXWalletManager(proxyAddress);

// Create wallet for a user
(uint256 walletId, address walletAddr) = manager.createWallet(userId);

// Deposit native tokens (ETH)
manager.deposit{value: 1 ether}(userId, walletId, address(0), 1 ether);

// Deposit ERC20 tokens
IERC20(token).approve(address(manager), 100e18);
manager.deposit(userId, walletId, address(token), 100e18);

// Withdraw tokens to external address
manager.withdraw(userId, walletId, payable(recipient), address(token), 50e18);

// Transfer tokens between wallets
manager.transfer(
    fromUserId, fromWalletId,
    toUserId, toWalletId,
    address(token), 25e18
);

// Batch transfer to multiple recipients
address[] memory tokens = [address(tokenA), address(0), address(tokenB)];
address[] memory recipients = [user1, user2, user3];
uint256[] memory amounts = [100e18, 1e18, 50e18];
manager.batchTransfer(userId, walletId, tokens, recipients, amounts);

ShareX Wallet + PowerPass Integration

// Setup: Grant MINTER_ROLE to user's wallet
address walletAddr = manager.getWalletAddr(userId, walletId);
powerPass.grantRole(powerPass.MINTER_ROLE(), walletAddr);

// Mint PowerPass NFT through wallet system
uint256 tokenId = manager.mintPowerPass(
    userId,
    walletId,
    address(powerPass),
    recipient,
    "https://metadata.example.com/token/1"
);

// Transfer PowerPass NFT (requires approval first)
powerPass.approve(walletAddr, tokenId); // Approve from current owner
manager.transferPowerPass(
    userId,
    walletId,
    address(powerPass),
    currentOwner,
    newOwner,
    tokenId
);

// Burn PowerPass NFT
manager.burnPowerPass(userId, walletId, address(powerPass), tokenId);

Custodial PowerPass Minting

The ShareX Wallet system supports custodial PowerPass minting, allowing the platform to mint PowerPass NFTs on behalf of users through ShareX wallets. This system bypasses normal sales rounds and pricing logic using custodial whitelist allocations.

Key Concepts

• Custodial Whitelist: Separate allocation system for platform-controlled minting
• MINTER_ROLE: Individual ShareX wallets need MINTER_ROLE to mint PowerPass NFTs
• Recipient-Based: Custodial whitelist must be set for the NFT recipient, not the minting wallet
• Sales Bypass: Custodial minting ignores sales rounds, pricing, and payment requirements

Complete Custodial Workflow

Step 1: Create ShareX Wallet

# Create wallet for user through ShareXWalletManager
source .env && cast send 0x5dC5Fdb90E57A5390c6524414f3d6da0b3Ef0f48 \
  "createWallet(uint256)" 13 \
  --rpc-url $RPC_URL --private-key $PRIVATE_KEY

# Get wallet address
WALLET_ADDR=$(cast call 0x5dC5Fdb90E57A5390c6524414f3d6da0b3Ef0f48 \
  "getWalletAddr(uint256,uint256)" 13 1 \
  --rpc-url $RPC_URL | cut -c 27-66)
WALLET_ADDR="0x$WALLET_ADDR"
# Example result: 0x7C4B5e96B336A60387CadeBa717Ae9859D61576B

Step 2: Grant MINTER_ROLE to Wallet

# Grant MINTER_ROLE to the ShareX wallet (required for custodial minting)
MINTER_ROLE=$(cast call 0x3d3624D578bf7bF81a76633a355320B3123c70f7 \
  "MINTER_ROLE()" --rpc-url $RPC_URL)

source .env && cast send 0x3d3624D578bf7bF81a76633a355320B3123c70f7 \
  "grantRole(bytes32,address)" $MINTER_ROLE $WALLET_ADDR \
  --rpc-url $RPC_URL --private-key $PRIVATE_KEY

Step 3: Set Custodial Whitelist for NFT Recipient

# Set custodial whitelist for the NFT recipient (NOT the wallet!)
source .env && cast send 0x3d3624D578bf7bF81a76633a355320B3123c70f7 \
  "batchSetCustodialWhitelists(address[],uint256[])" \
  "[$WALLET_ADDR]" "[5]" \
  --rpc-url $RPC_URL --private-key $PRIVATE_KEY

# Verify custodial whitelist
cast call 0x3d3624D578bf7bF81a76633a355320B3123c70f7 \
  "getCustodialWhitelistInfo(address)" $WALLET_ADDR --rpc-url $RPC_URL

Step 4: Mint PowerPass NFT Through ShareX Wallet

# Mint PowerPass NFT through ShareXWalletManager to the ShareX wallet
source .env && cast send 0x5dC5Fdb90E57A5390c6524414f3d6da0b3Ef0f48 \
  "mintPowerPass(uint256,uint256,address,address,string)" \
  13 1 0x3d3624D578bf7bF81a76633a355320B3123c70f7 $WALLET_ADDR \
  "https://api.sharex.network/powerpass/metadata/custodial-1" \
  --rpc-url $RPC_URL --private-key $PRIVATE_KEY

# Verify minting results
cast call 0x3d3624D578bf7bF81a76633a355320B3123c70f7 \
  "balanceOf(address)" $WALLET_ADDR --rpc-url $RPC_URL
cast call 0x3d3624D578bf7bF81a76633a355320B3123c70f7 \
  "totalSupply()" --rpc-url $RPC_URL

Contract Addresses (BSC Testnet)

export POWERPASS_PROXY=0x3d3624D578bf7bF81a76633a355320B3123c70f7
export WALLET_MANAGER=0x5dC5Fdb90E57A5390c6524414f3d6da0b3Ef0f48

Integration Script

For a complete workflow demonstration, use the included script:

# Execute complete custodial minting workflow
source .env && ./tools/custodial_powerpass_workflow.sh

Key Advantages

• Gas Efficiency: No USDT payments or approvals required
• Flexible Distribution: Platform can distribute NFTs to any address with custodial allocation
• Sales Independence: Operates independently of regular sales rounds and timing
• Role-Based Security: Controlled through PowerPass MINTER_ROLE system
• Audit Trail: All operations logged with comprehensive events

For detailed implementation and troubleshooting, see CUSTODIAL_POWERPASS_WORKFLOW.md.

🧪 Testing

The Deshare Protocol includes comprehensive test suites covering all Deshare functionality:

# Run all tests with optimization
make foundry-test

# Run specific test contracts
forge test --match-contract Deshare -vvv

# Run ShareX Wallet tests
forge test --match-contract ShareX -v

# Run with gas reporting
forge test --gas-report

# Generate coverage reports
forge coverage

# Test specific ShareX functionality
forge test --match-test testMintPowerPass -vvv
forge test --match-test testBatchTransfer -vvv

Test Structure

test/
├── unit/                           # Unit tests for specific functionality
│   ├── Country.t.sol              # Country registration tests
│   ├── Partner.t.sol              # Partner management tests
│   ├── Merchant.t.sol             # Merchant management tests
│   ├── Device.t.sol               # Device management tests
│   ├── Transaction.t.sol          # Transaction and core tests
│   ├── PowerPass.t.sol            # PowerPass ERC721 NFT tests
│   ├── ShareXWallet.t.sol         # ShareX Wallet tests
│   └── ShareXWalletManager.t.sol  # ShareX Wallet Manager tests
└── integration/                   # Integration tests
    └── Deshare.t.sol               # End-to-end workflow tests

Test Categories

• Unit Tests: Individual Deshare, PowerPass, and ShareX Wallet function validation
• Integration Tests: Multi-component workflow testing across all systems
• Access Control Tests: Role-based permission validation for all contracts
• Security Tests: Input validation and error handling across all components
• Edge Case Testing: Boundary conditions and error scenarios
• Gas Optimization Tests: Performance and efficiency validation
• NFT Tests: ERC721 compliance and metadata functionality
• Wallet Tests: Multi-token operations and wallet management functionality
• Batch Operation Tests: Efficient multi-transfer and multi-call validations

Comprehensive test coverage of all Deshare Protocol functionality including PowerPass NFT system and ShareX Wallet management.

🔒 Security Considerations

Access Control Roles

Deshare Roles

• DEFAULT_ADMIN_ROLE: Complete system administration and role management
• OPERATOR_ROLE: Day-to-day protocol operations and entity registration

PowerPass Roles

• DEFAULT_ADMIN_ROLE: PowerPass administration and token URI management
• MINTER_ROLE: PowerPass minting operations

Proxy Security Architecture

• Initializable Pattern: Secure initialization with disable guards for implementation
• Implementation Security: Storage layout protection and initialization guards
• Role Separation: Clear boundaries between proxy and business logic control

Risk Management

• Input Validation: Comprehensive parameter validation and bounds checking
• Reentrancy Protection: ReentrancyGuard on transaction batch uploads
• Data Integrity: Immutable transaction records and audit trails
• Access Control: Role-based permissions with proper inheritance
• Counter Management: Secure incrementing counters for unique ID generation
• Batch Processing Security: Transaction validation and data consistency checks

📊 Performance Metrics

Gas Optimization

• Efficient Data Structures: Optimized struct packing and storage patterns
• Batch Operations: Reduced transaction costs through bulk processing
• Data Compression: LibZip compression reduces storage costs by 30%+
• Minimal External Calls: Streamlined contract interactions
• Strategic Storage: Cost-effective state variable management

Scalability Features

• High-Throughput Processing: Efficient batch transaction handling with compression
• Optimized Queries: Fast data retrieval and partner/merchant lookups
• Event-Driven Architecture: Comprehensive event emission for off-chain analytics
• Upgradeable Design: Future-proof architecture for continuous improvements

Expected Performance (Network Dependent)

• Transaction Processing: 100+ transactions per batch (MAX_BATCH_SIZE limit)
• Partner Onboarding: Sub-second registration with verification
• Device Management: Real-time registration and dependency validation
• Query Performance: Efficient data retrieval across all entity types
• Compression Efficiency: 30%+ reduction in storage costs through LibZip compression

Note: Performance metrics vary based on network congestion, gas prices, and batch sizes. The system is optimized for high-throughput protocol operations with compressed data storage.

🛠️ Deployment

Prerequisites

# Install Foundry
curl -L https://foundry.paradigm.xyz | bash
foundryup

# Clone and setup project
git clone <repository-url>
cd sharex-evm-contracts
forge install

Build and Test

# Clean and build contracts
make clean && make build

# Run comprehensive tests
make foundry-test

# Generate ABI files
make abi

Local Development

# Start local Anvil node
anvil

# Deploy to local network (dry run first)
DEPLOYMENT_CONTEXT=local forge script script/Deploy.s.sol:Deploy --ffi -vvv

# Deploy with broadcast
DEPLOYMENT_CONTEXT=local forge script script/Deploy.s.sol:Deploy \
  --rpc-url http://localhost:8545 \
  --private-key $PRIVATE_KEY \
  --broadcast --ffi -vvv

BSC Testnet Deployment

Environment Setup

Create a .env file in the project root:

# BSC Testnet Configuration
PRIVATE_KEY=your_private_key_without_0x_prefix
CHAIN_ID=97
RPC_URL=https://data-seed-prebsc-1-s1.binance.org:8545
VERIFIER=etherscan
VERIFIER_URL=https://api.etherscan.io/v2/api
ETHERSCAN_API_KEY=your_bscscan_api_key_here
DEPLOYMENT_CONTEXT=bsc-testnet

Deployment Commands (All Contracts)

# 1. Build contracts
forge build

# 2. Deploy all contracts at once (legacy approach)
source .env && DEPLOYMENT_CONTEXT="bsc-testnet" forge script script/Deploy.s.sol:Deploy \
  --rpc-url $RPC_URL \
  --private-key $PRIVATE_KEY \
  --broadcast --ffi -vvv

Modular Deployment Commands (Recommended)

Deploy contracts individually for better control and flexibility:

# 1. Build contracts
forge build

# 2a. Deploy Deshare contract only
source .env && DEPLOYMENT_CONTEXT="bsc-testnet" forge script script/DeployDeshare.s.sol:DeployDeshare \
  --rpc-url $RPC_URL \
  --private-key $PRIVATE_KEY \
  --broadcast --ffi -vvv

# 2b. Deploy ShareX USDT (test token) first
source .env && DEPLOYMENT_CONTEXT="bsc-testnet" forge script script/DeployShareXUSDT.s.sol:DeployShareXUSDT \
  --rpc-url $RPC_URL \
  --private-key $PRIVATE_KEY \
  --broadcast --verify --etherscan-api-key $ETHERSCAN_API_KEY --ffi -vvv

# 2c. Deploy PowerPass contract only (requires payment token in config)
source .env && DEPLOYMENT_CONTEXT="bsc-testnet" forge script script/DeployPowerPass.s.sol:DeployPowerPass \
  --rpc-url $RPC_URL \
  --private-key $PRIVATE_KEY \
  --broadcast --verify --etherscan-api-key $ETHERSCAN_API_KEY --ffi -vvv

# 2d. Deploy ShareX Wallet Manager contract only
source .env && DEPLOYMENT_CONTEXT="bsc-testnet" forge script script/DeployShareXWalletManager.s.sol:DeployShareXWalletManager \
  --rpc-url $RPC_URL \
  --private-key $PRIVATE_KEY \
  --broadcast --ffi -vvv

# 2e. Deploy ShareX Keys Series contract only
source .env && DEPLOYMENT_CONTEXT="bsc-testnet" forge script script/DeployShareXKeysSeries.s.sol:DeployShareXKeysSeries \
  --rpc-url $RPC_URL \
  --private-key $PRIVATE_KEY \
  --broadcast --verify --etherscan-api-key $ETHERSCAN_API_KEY --ffi -vvv

# 3. Verify contracts manually (if needed)
source .env && forge verify-contract <CONTRACT_ADDRESS> src/Deshare.sol:Deshare \
  --chain-id 97 \
  --etherscan-api-key $ETHERSCAN_API_KEY \
  --constructor-args $(cast abi-encode "constructor(address)" 0xd559c7e581233F19cD4E3F2Ce969ddE01D3dEEC4)

Post-Deployment Validation

# Validate deployment
source .env
export PROXY_ADDRESS=$(jq -r '.DeshareProxy' deployments/bsc-testnet/.deploy)
cast call $PROXY_ADDRESS "getVersion()" --rpc-url $RPC_URL
cast call $PROXY_ADDRESS "hasRole(bytes32,address)" \
  0x0000000000000000000000000000000000000000000000000000000000000000 \
  0xd559c7e581233F19cD4E3F2Ce969ddE01D3dEEC4 --rpc-url $RPC_URL

Deployed Contracts (BSC Testnet)

Network Details:

• Chain ID: 97 (BSC Testnet)
• RPC URL: https://data-seed-prebsc-1-s1.binance.org:8545
• Explorer: BSCScan Testnet
• Admin Address: 0xd559c7e581233F19cD4E3F2Ce969ddE01D3dEEC4
• ProxyAdmin Owner: 0xd559c7e581233F19cD4E3F2Ce969ddE01D3dEEC4
• PowerPass Admin/Minter: 0xd559c7e581233F19cD4E3F2Ce969ddE01D3dEEC4

PowerPassStaking Configuration:

• PowerPass Contract: 0x3d3624D578bf7bF81a76633a355320B3123c70f7
• Payment Token: ShareXUSDT (0x6350a32a4406469608B5D93A77572e140b5F3D73)
• Default Reward Percentage: 25% (2500 BPS)

Environment Variables (BSC Testnet):

export POWERPASS_PROXY=0x3d3624D578bf7bF81a76633a355320B3123c70f7
export POWERPASS_STAKING=0x5560e8CD017D2BD8474601D682731a807a66654B
export POWERPASS_STAKING_IMPL=0xcDA6366b624D4Fe52f25469912E3c788F0D19024
export POWERPASS_STAKING_PROXY_ADMIN=0x2c56854aaf4d483b85f0580dad5ae4eec8fc4148
export WALLET_MANAGER=0x5dC5Fdb90E57A5390c6524414f3d6da0b3Ef0f48
export USDT_TOKEN=0x6350a32a4406469608B5D93A77572e140b5F3D73
export ADMIN_ADDRESS=0xd559c7e581233F19cD4E3F2Ce969ddE01D3dEEC4

Deployed Contracts (BSC Mainnet)

Network Details:

• Chain ID: 56 (BSC Mainnet)
• RPC URL: https://bsc-dataseed.bnbchain.org
• Explorer: BSCScan
• Admin Address: 0x3047dB262c4e142B2C7927BB7df5cC86A0f6EE78
• ProxyAdmin Owner: 0x3047dB262c4e142B2C7927BB7df5cC86A0f6EE78
• PowerPass Payment Token: BSC USDT (0x55d398326f99059fF775485246999027B3197955) - 18 decimals
• PowerPass Base URI: https://f004.backblazeb2.com/file/sharex-powerpass/metadata/
• PowerPass MAX_SUPPLY: 5000
• ShareXMomentumBadge: Symbol "SMB", Metadata URI: https://rwa.sharex.network/metadata/momentum-badge.json

PowerPass Sales Schedule (UTC):

• Priority Whitelist: Dec 22, 2025, 10:00 - 14:00
• General Whitelist: Dec 22, 2025, 14:00 - Dec 23, 2025, 14:00

PowerPass Pricing:

• Standard Price: 50 USDT
• Discount Code: 5 USDT discount (45 USDT final)
• Nova Discount: 80% (40 USDT)

Deployed Contracts (opBNB Mainnet)

Network Details:

• Chain ID: 204 (opBNB Mainnet)
• RPC URL: https://opbnb-mainnet-rpc.bnbchain.org
• Explorer: opBNBScan
• Admin Address: 0x3047dB262c4e142B2C7927BB7df5cC86A0f6EE78
• ProxyAdmin Owner: 0x3047dB262c4e142B2C7927BB7df5cC86A0f6EE78

Contract Verification on opBNBScan

Command-Line Verification using NodeReal API:

# Set environment variables
export NODEREAL_API_KEY=051d517322704e9aba88993bd8e2555b
export RPC_URL=https://opbnb-mainnet-rpc.bnbchain.org

# Method 1: Direct verification with NodeReal URL
forge verify-contract 0xD81B9c15dE92D9A5e373d3E0817B648987079c37 src/Deshare.sol:Deshare \
  --chain-id 204 \
  --verifier-url "https://open-platform.nodereal.io/$NODEREAL_API_KEY/op-bnb-mainnet/contract/" \
  --constructor-args $(cast abi-encode "constructor(address)" 0x3047dB262c4e142B2C7927BB7df5cC86A0f6EE78)

# Method 2: Using etherscan verifier with NodeReal endpoint
forge verify-contract 0xD81B9c15dE92D9A5e373d3E0817B648987079c37 src/Deshare.sol:Deshare \
  --chain-id 204 \
  --verifier etherscan \
  --etherscan-api-key $NODEREAL_API_KEY \
  --verifier-url "https://open-platform.nodereal.io/$NODEREAL_API_KEY/op-bnb-mainnet/contract/" \
  --constructor-args $(cast abi-encode "constructor(address)" 0x3047dB262c4e142B2C7927BB7df5cC86A0f6EE78)

Manual Verification via opBNBScan Web Interface:

If command-line verification encounters issues, verify manually:

1. Visit Verification Page: opBNBScan Contract Verification
2. Enter Contract Details:
   • Contract Address: 0xD81B9c15dE92D9A5e373d3E0817B648987079c37
   • Compiler Type: Solidity (Single file) or Standard JSON Input
3. Compiler Settings:
   • Compiler Version: 0.8.24
   • Optimization: Yes (999999 runs)
   • EVM Version: Paris
4. Constructor Arguments: 0x0000000000000000000000003047db262c4e142b2c7927bb7df5cC86A0f6EE78
5. Contract Source: Upload flattened contract or standard JSON input

Getting ProxyAdmin Address Programmatically:

# Get ProxyAdmin address from proxy storage slot
export PROXY_ADDRESS=0x28e3889A3bc57D4421a5041E85Df8b516Ab683F8
cast storage $PROXY_ADDRESS 0xb53127684a568b3173ae13b9f8a6016e243e63b6e8ee1178d6a717850b5d6103 --rpc-url $RPC_URL
# Returns: 0x000000000000000000000000dfd3c8bf6dad595293ecdce4c0e1b485f072119a (ProxyAdmin)

Usage Notes:

• Use the DeshareProxy address (0x28e3889A3bc57D4421a5041E85Df8b516Ab683F8) for all Deshare interactions
• The ProxyAdmin (0xdfd3c8bf6dad595293ecdce4c0e1b485f072119a) controls proxy upgrades
• NodeReal API Key: Get from NodeReal Platform
• Verification Guide: BNB Chain opBNB Verification Documentation

Important Deployment Notes:

• Environment Variables: Always use source .env to load environment variables before deployment
• Private Key Format: Use raw private key without 0x prefix in .env file
• RPC Endpoint: Use the stable BSC testnet RPC endpoint for reliable connections
• Verification: Manual verification may be required if automatic verification fails

Usage Notes (BSC Testnet):

• Use the DeshareProxy address (0x23E89f8aC6e7751095fD5DbC71B89Bd1C60f23C7) for all Deshare interactions
• Use the PowerPassProxy address (0x3d3624D578bf7bF81a76633a355320B3123c70f7) for all PowerPass NFT operations
• Use the ShareXUSDT address (0x6350a32a4406469608B5D93A77572e140b5F3D73) for PowerPass payment token operations
• Use the ShareXWalletManagerProxy address (0x5dC5Fdb90E57A5390c6524414f3d6da0b3Ef0f48) for all wallet management operations
• Use the ShareXKeysSeries address (0x5F8044C7Acf488C359EB1c8afDfc4e57c8E1733a) for all Keys Series NFT operations
• Use the ShareXKeysStakingProxy address (0xfCb95edFBEB8e47492558c6E36db7B8F6766D220) for all Keys staking operations

Usage Notes (BSC Mainnet):

• Use the PowerPassProxy address (0xdF9A38E920902022eF54B5F05bD28C8ca4eFD961) for all PowerPass NFT operations on BSC mainnet
• Use the ShareXWalletManagerProxy address (0x371c05B0CC9B6Fc3794A911DdD2DfbB266db5b38) for all wallet management operations on BSC mainnet
• Use the ShareXKeysSeries address (0x28e3889A3bc57D4421a5041E85Df8b516Ab683F8) for all Keys Series NFT operations on BSC mainnet
• Use the ShareXKeysStakingProxy address (0xC7e54532ea427b7Bcf682dc0BEF24CD1338b3026) for all Keys staking operations on BSC mainnet
• Use the ShareXMomentumBadge address (0x7184dCdFEBEE6D3910782FBEEE5Ea1470692eb21) for all Momentum Badge NFT operations on BSC mainnet

opBNB Mainnet Deployment

Environment Setup

Create a .env file in the project root:

# opBNB Mainnet Configuration
PRIVATE_KEY=your_private_key_without_0x_prefix
CHAIN_ID=204
RPC_URL=https://opbnb-mainnet-rpc.bnbchain.org
VERIFIER=etherscan
VERIFIER_URL=https://open-platform.nodereal.io/YOUR_NODEREAL_API_KEY/op-bnb-mainnet/contract/
ETHERSCAN_API_KEY=your_nodereal_api_key_here
NODEREAL_API_KEY=your_nodereal_api_key_here
DEPLOYMENT_CONTEXT=opbnb-mainnet

Deployment Commands

# 1. Build contracts
forge build

# 2. Deploy Deshare contract only
source .env && DEPLOYMENT_CONTEXT="opbnb-mainnet" forge script script/DeployDeshare.s.sol:DeployDeshare \
  --rpc-url $RPC_URL \
  --private-key $PRIVATE_KEY \
  --broadcast --ffi -vvv

# 3. Verify contract (using NodeReal API)
source .env && forge verify-contract 0xD81B9c15dE92D9A5e373d3E0817B648987079c37 src/Deshare.sol:Deshare \
  --chain-id 204 \
  --verifier-url "https://open-platform.nodereal.io/$NODEREAL_API_KEY/op-bnb-mainnet/contract/" \
  --constructor-args $(cast abi-encode "constructor(address)" 0x3047dB262c4e142B2C7927BB7df5cC86A0f6EE78)

Supported Networks

• Local: Anvil development network for testing
• BSC Testnet: Binance Smart Chain testnet (Chain ID: 97)
• BSC Mainnet: Production deployment target
• opBNB Mainnet: opBNB Layer 2 mainnet (Chain ID: 204)
• Devnet: Custom development network for staging

Deployment Artifacts

• Contract addresses stored in deployments/[network]/.deploy
• Chain ID configuration in deployments/[network]/.chainId
• Network-specific configs in deploy-config/[network].json

🔄 Contract Upgrades

Upgrade Architecture

The Deshare Protocol uses OpenZeppelin's TransparentUpgradeableProxy pattern with clear role separation:

• ProxyAdmin Contract: 0x606ad7a222bdcc5a43a1927794c29122d708e289
• ProxyAdmin Owner: 0xd559c7e581233F19cD4E3F2Ce969ddE01D3dEEC4 (controls proxy upgrades)
• Deshare Admin: 0xd559c7e581233F19cD4E3F2Ce969ddE01D3dEEC4 (controls business logic)

Step-by-Step Upgrade Process

# 1. Deploy new implementation
source .env && forge script script/DeployNewImplementation.s.sol:DeployNewImplementation \
  --rpc-url $RPC_URL --private-key $PRIVATE_KEY --broadcast -vvv

# 2. Get ProxyAdmin address from storage slot
export PROXY_ADMIN=$(cast storage 0x23E89f8aC6e7751095fD5DbC71B89Bd1C60f23C7 \
  0xb53127684a568b3173ae13b9f8a6016e243e63b6e8ee1178d6a717850b5d6103 \
  --rpc-url $RPC_URL)

# 3. Upgrade proxy to new implementation (ProxyAdmin owner only)
source .env && cast send $PROXY_ADMIN "upgradeAndCall(address,address,bytes)" \
  0x23E89f8aC6e7751095fD5DbC71B89Bd1C60f23C7 \
  <NEW_IMPLEMENTATION_ADDRESS> \
  0x \
  --rpc-url $RPC_URL --private-key $PRIVATE_KEY

# 4. Verify upgrade success
cast storage 0x23E89f8aC6e7751095fD5DbC71B89Bd1C60f23C7 \
  0x360894a13ba1a3210667c828492db98dca3e2076cc3735a920a3ca505d382bbc \
  --rpc-url $RPC_URL

# 5. Test functionality (both old and new methods)
cast call 0x23E89f8aC6e7751095fD5DbC71B89Bd1C60f23C7 "getVersion()" --rpc-url $RPC_URL
cast call 0x23E89f8aC6e7751095fD5DbC71B89Bd1C60f23C7 "getStats()" --rpc-url $RPC_URL
cast call 0x23E89f8aC6e7751095fD5DbC71B89Bd1C60f23C7 "getDetailedStats()" --rpc-url $RPC_URL

# 6. Verify new implementation on BSCScan
source .env && forge verify-contract <NEW_IMPLEMENTATION_ADDRESS> src/Deshare.sol:Deshare \
  --chain-id 97 --etherscan-api-key $ETHERSCAN_API_KEY \
  --constructor-args $(cast abi-encode "constructor(address)" 0xd559c7e581233F19cD4E3F2Ce969ddE01D3dEEC4)

Recent Upgrade Example (Enhanced Stats)

Upgrade Transaction: 0xeb375b644110da420ec9278423a16052349fb84ae118eb2737035e13c766c460

• From Implementation: 0x70E027Ce8B5a9FEdaE0fa04ED95d03214cCEcE25
• To Implementation: 0x09D3E9d08348b22AB5E03158Dc1927da4646EB79
• New Feature: Enhanced getDetailedStats() method with user-friendly labels
• Verification: View on BSCScan
• Status: ✅ Successfully deployed and verified

Upgrade Safety Guidelines

• Storage Layout: Never modify existing storage variable order or types
• Initialization: Use separate initializeV2(), initializeV3() functions for new versions
• Testing: Always test upgrades on local/testnet before mainnet
• Multi-sig: Use multi-signature wallets for production upgrades
• Verification: Always verify new implementation contracts on BSCScan
• Documentation: Update all relevant documentation after upgrades

🤝 Contributing

We welcome contributions to the Deshare Protocol! Please follow our development guidelines:

Development Workflow

1. Fork the repository and create a feature branch
2. Write comprehensive tests for new functionality
3. Ensure all tests pass (make foundry-test)
4. Follow Solidity coding standards and security best practices
5. Update documentation and examples as needed
6. Submit a pull request with detailed description

Coding Standards

• Follow Solidity 0.8.24 best practices
• Use NatSpec documentation for all public functions
• Implement proper access control and input validation
• Write comprehensive unit and integration tests
• Maintain gas efficiency and optimization

Security Guidelines

• Never modify storage layout in upgrades
• Always validate inputs and check access controls
• Use established patterns for reentrancy protection
• Test upgrade scenarios on testnet before mainnet

📄 License

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

⚠️ Disclaimer: This software is provided as-is for ecosystem management purposes. While designed with security best practices, users should conduct thorough testing and audits before production deployment. Use at your own risk and ensure compliance with applicable regulations.