XTract (v0.30.1)

An open-source tool for converting Solidity smart contracts to MultiversX-compatible Rust smart contracts.

Quick Start

# Install
npm install -g xtract-cli

# Transpile a Solidity contract to MultiversX Rust
xtract MyContract.sol

# That's it! Your MultiversX Rust contract is ready at MyContract.rs

Overview

XTract analyzes Solidity code and generates MultiversX Rust code that can be compiled and deployed on the MultiversX blockchain. It supports a comprehensive set of Solidity features including control flow, mappings, modifiers, and inheritance.

Version 0.30.1 (Beta Release)

This version introduces comprehensive Solidity support:

Core Features

• Function body transpilation: Converts require(), emit(), return, and assignments
• Error handling: Maps Solidity require() → MultiversX require!() and revert() → sc_panic!()
• Event emission: Properly converts Solidity events to MultiversX event calls
• Storage operations: Handles variable assignments and storage access patterns

Mapping Support

• Single mappings: mapping(address => uint256) → storage mappers with key parameters
• Nested mappings: mapping(address => mapping(address => uint256)) → multi-key storage mappers

Control Flow

• If/else statements: Full if/else transpilation with proper Rust syntax
• For loops: Counter-based loops transpiled to for i in 0..n syntax
• While loops: While loop transpilation with condition conversion
• Payable functions: Automatic #[payable("EGLD")] annotation

Advanced Features

• Function modifiers: onlyOwner, whenNotPaused, custom modifiers
• Basic inheritance: Contract inheritance with supertrait generation
• Enhanced diagnostics: Detailed warnings for unsupported features

Test Coverage: 100% unit test success across 50 Solidity contracts with 64 test functions.

Installation

Via npm (recommended)

npm install -g xtract-cli

Via pip (Python)

pip install xtract

From source

git clone https://github.com/XTract-build/Xtract.git
cd XTract
pip install -e .

Usage

Basic Usage

# Transpile a Solidity contract
xtract MyContract.sol

# Specify output file
xtract MyContract.sol output.rs

# Verbose mode (show diagnostics)
xtract -v MyContract.sol

# Quiet mode
xtract -q MyContract.sol

Quick Example

# Create a simple Solidity contract
cat > MyStorage.sol << 'EOF'
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;

contract MyStorage {
    uint256 public value;
    address public owner;

    modifier onlyOwner() {
        require(msg.sender == owner, "Not owner");
        _;
    }

    event ValueChanged(uint256 indexed newValue);

    constructor() {
        owner = msg.sender;
    }

    function setValue(uint256 newValue) public onlyOwner {
        require(newValue > 0, "Value must be positive");
        value = newValue;
        emit ValueChanged(newValue);
    }

    function getValue() public view returns (uint256) {
        return value;
    }
}
EOF

# Transpile it
xtract MyStorage.sol

# View the generated MultiversX Rust code
cat MyStorage.rs

Supported Solidity Features

Fully Supported

• Contract declarations
• State variables (all basic types)
• Single mappings (mapping(address => uint256))
• Nested mappings (mapping(address => mapping(address => uint256)))
• Events with indexed parameters
• Custom errors
• Structs
• Functions (public, private, view, payable)
• Constructors
• Function modifiers (onlyOwner, custom)
• Basic inheritance (contract A is B, C)
• require/revert statements
• If/else statements
• For loops (counter-based)
• While loops

Requires Manual Review

• Complex expressions (may need adjustment)
• External contract calls

Not Yet Supported

• Do-while loops
• Inline assembly
• Try-catch blocks
• Libraries
• Diamond inheritance

Examples

The test_cases/ directory contains 50 fully working examples including:

| Category | Examples | |----------|----------| | Basic | SimpleStorage, Counter, Config | | Tokens | ERC20Token, SimpleToken, TokenMinter | | NFTs | NFTMarketplace, Certificate, Badge | | DeFi | Staking, RewardPool, TokenSwap, Vesting | | Governance | Voting, Governance, Poll, Multisig | | Access Control | OnlyOwner, AccessControl, Pausable | | Patterns | Escrow, Auction, Lottery, Vault |

Documentation

Version Documentation

• docs/v0.30/ - Complete documentation for v0.30.1
  • README.md - Feature overview and examples
  • CHANGELOG.md - Full release notes
  • IMPLEMENTATION_REPORT.md - Technical architecture
  • IMPLEMENTATION_SUMMARY.md - Feature matrix
  • TEST_RESULTS.md - Test coverage and results

Developer Guide

• docs/DEVELOPER_GUIDE.md - Getting started guide

Repository Structure

XTract/
  xtract/            # Python package (CLI + core transpiler)
  tests/             # Unit tests (64 test functions)
  test_cases/        # Solidity inputs and expected Rust outputs (50 contracts)
  demo/              # Compiled demo contracts
  docs/              # Documentation
  .github/workflows/ # CI configuration
  package.json       # npm package configuration
  pyproject.toml     # Python packaging config

How It Works

XTract follows a clear pipeline from Solidity source code to MultiversX Rust:

Solidity Source (.sol)
        ↓
┌─────────────────────┐
│  Validation &       │
│  Diagnostics        │
└──────────┬──────────┘
           ↓
┌─────────────────────┐
│  Parse Contract     │
│  - Name & Inheritance│
│  - Modifiers        │
│  - Storage & Events │
│  - Functions        │
└──────────┬──────────┘
           ↓
┌─────────────────────┐
│  Convert to         │
│  MultiversX Rust    │
└──────────┬──────────┘
           ↓
   Rust Output (.rs)

Testing

# Run all tests
pytest tests/ -v

# Run specific test
pytest tests/test_transpiler_core.py::test_nested_mapping_features -v

# Run with coverage
pytest tests/ --cov=xtract

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

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