XTract (v1.0.0)

Solidity to MultiversX transpiler with wallet, build, deploy, and TypeScript SDK — the full EVM-to-MultiversX developer toolkit.

Quick Start

# Install
pip install xtract           # transpile only
pip install xtract[deploy]   # + wallet creation and on-chain deployment

# 1. Transpile Solidity → Rust
xtract MyContract.sol        # writes MyContract.rs

# 2. Build Rust → WASM  (requires mxpy)
xtract build ./my_contract/

# 3. Create a wallet (first time)
xtract wallet create         # saves to ~/.multiversx/wallet.pem
#    → prints your address and funding URLs for devnet/testnet

# 4. Deploy
xtract deploy ./my_contract/output/my_contract.wasm \
  --abi ./my_contract/output/my_contract.abi.json \
  --wallet ~/.multiversx/wallet.pem \
  --network devnet
#    → prints contract address and explorer link

npm package: https://www.npmjs.com/package/xtract-cli

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.

v1.0.0 — What's New

v1.0 adds the full deployment pipeline on top of v0.30's transpiler. See docs/v1.0/CHANGELOG.md for the complete change list.

New in v1.0

• xtract build — compiles transpiled Rust to WASM via mxpy
• xtract wallet create — generates a BIP39 wallet, saves as PEM
• xtract deploy — deploys compiled WASM to devnet/testnet/mainnet
• pip install xtract[deploy] — optional dep group for the above
• TypeScript SDK — xtract-cli/sdk exposes XtractTranspiler and ContractDeployer

Transpiler features (from v0.30.1)

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.

TypeScript SDK

The xtract-cli package bundles a full TypeScript SDK for programmatic use:

import { XtractTranspiler, ContractDeployer } from 'xtract-cli/sdk';

// Transpile Solidity to Rust
const transpiler = new XtractTranspiler();
const result = await transpiler.transpileCode('contract Foo { uint x; }');
console.log(result.rustCode);

// Deploy compiled contract to MultiversX
const deployer = new ContractDeployer();
const deployed = await deployer.deploy({
  network: 'devnet',
  wasmPath: './output/foo.wasm',
  abiPath: './output/foo.abi.json',
  walletPath: './wallet.pem',
});
console.log(deployed.contractAddress);

Prerequisite: the SDK shells out to the Python transpiler — pip install xtract must be run first (Python 3.9+).

Installation

# Transpile only (lightweight — just click)
pip install xtract

# Full pipeline: transpile + build wrapper + wallet + deploy
pip install xtract[deploy]

# CLI tool for npm users (includes TypeScript SDK)
npm install -g xtract-cli

mxpy is required separately for the xtract build command:

pip install mxpy

CLI Reference

# Transpile
xtract transpile MyContract.sol              # → MyContract.rs
xtract transpile MyContract.sol -o output.rs
xtract transpile -v MyContract.sol           # verbose diagnostics
xtract transpile --json MyContract.sol       # JSON to stdout

# Flags can be passed before the file without the 'transpile' subcommand:
xtract --json MyContract.sol       # shorthand for 'xtract transpile --json'
xtract -v MyContract.sol           # shorthand for 'xtract transpile -v'

# Build (requires mxpy)
xtract build ./my_contract/

# Wallet  (requires xtract[deploy])
xtract wallet create
xtract wallet create --output ./wallet.pem
xtract wallet create --no-faucet  # skip automatic devnet faucet request

# Faucet  (request devnet/testnet EGLD — requires xtract[deploy])
xtract faucet --network devnet                           # reads ~/.multiversx/wallet.pem
xtract faucet --wallet ./wallet.pem --network testnet
xtract faucet --address erd1... --network devnet

# Deploy  (requires xtract[deploy])
xtract deploy ./output/my_contract.wasm \
  --abi       ./output/my_contract.abi.json \
  --wallet    ~/.multiversx/wallet.pem \
  --network   devnet              # devnet | testnet | mainnet
  --gas-limit 10000000            # default: 10 000 000
  --no-upgrade                    # deploy as non-upgradeable

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

Current version

• docs/v1.0/README.md — v1.0 feature overview and full pipeline walkthrough
• docs/v1.0/CHANGELOG.md — what changed from v0.30 to v1.0
• docs/DEVELOPER_GUIDE.md — CLI reference, Python API, TypeScript SDK, type mapping

Previous versions

• docs/v0.30/ — v0.30.1 release notes, implementation report, test results
• docs/v0.25/ — v0.25 release notes

Repository Structure

XTract/
  xtract/            # Python package
    transpiler.py    #   Solidity parser and Rust emitter
    cli.py           #   CLI entry point (transpile / build / wallet / deploy)
    build.py         #   mxpy contract build wrapper
    wallet.py        #   BIP39 wallet generation
    deploy.py        #   Contract deployment via multiversx-sdk
  sdk/               # TypeScript SDK (bundled into xtract-cli npm package)
  tests/             # Python unit tests (64 test functions)
  test_cases/        # Solidity inputs and expected Rust outputs (50 contracts)
  docs/              # Documentation
  .github/workflows/ # CI configuration
  package.json       # xtract-cli npm package
  pyproject.toml     # Python packaging config

How It Works

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

Solidity Source (.sol)
        ↓  xtract MyContract.sol
┌─────────────────────┐
│  Transpiler         │
│  (parse + emit)     │
└──────────┬──────────┘
           ↓
   Rust Source (.rs)
        ↓  xtract build ./my_contract/
┌─────────────────────┐
│  mxpy contract      │
│  build              │
└──────────┬──────────┘
           ↓
   WASM + ABI
        ↓  xtract deploy ...
┌─────────────────────┐
│  multiversx-sdk     │
│  (sign + broadcast) │
└──────────┬──────────┘
           ↓
  Live contract on MultiversX

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.