Move-to-Cairo Transpiler

🚀 v0.2.1 - Package-level transpiler for converting Move/Sui Move smart contracts to Cairo for Starknet deployment

📋 Overview

The Move-to-Cairo transpiler enables developers to leverage Sui Move's object-oriented programming model on Starknet by converting entire Move packages to deployable Cairo packages.

Key Features

• ✅ Package-level transpilation - Convert complete Move packages, not just single files
• ✅ Standard library support - Full Move Core and Sui Framework implementations in Cairo
• ✅ Validated output - Ensures Move code passes sui move build before transpilation
• ✅ Production-ready Cairo - Generated code compiles with scarb build
• ✅ Auto .gitignore - Automatically generates appropriate .gitignore for Cairo projects
• ✅ Storage traits - Proper handling of Cairo 2.8.2 storage access patterns

🏗️ Architecture v2

Transpilation Pipeline

Move Package → Validation → Transpilation → Cairo Package → Compilation
     ↓           ↓              ↓               ↓              ↓
  Move.toml   sui move     Transpiler    Scarb.toml      scarb build
               build                      + .cairo files

Core Components

Component	Description	Status
Package Parser	Parses Move.toml, validates with sui move build, resolves dependencies	✅ Complete
Stdlib Transpiler	Converts Move/Sui standard libraries to Cairo packages	✅ Complete
Cairo Stdlib	cairo-move-core and cairo-sui-framework packages	✅ Complete
Code Generator	Generates Cairo packages with proper structure, Scarb.toml, .gitignore	✅ Complete
Test Coin Example	Successfully transpiles and compiles fungible token contracts	✅ Verified

🚀 Quick Start

Prerequisites

# Required tools
- Rust 1.70+
- Sui CLI: curl --proto '=https' -sSf https://sui.io/install.sh | sh
- Scarb: curl --proto '=https' -sSf https://docs.swmansion.com/scarb/install.sh | sh

Installation

# Clone and build
git clone https://github.com/foundation3dao/move-to-cairo
cd move-to-cairo
cargo build --release

# Optional: Install globally
cargo install --path crates/cli

📦 Standard Libraries

Cairo Move Core (cairo-move-core)

Implementation of Move standard library (0x1) for Cairo:

Module	Description	API Status
vector	Dynamic arrays	✅ Complete
option	Optional values	✅ Complete
string	UTF-8 strings	✅ Complete
bcs	Binary serialization	✅ Complete
hash	Cryptographic hashing	✅ Complete
type_name	Type reflection	✅ Complete

Cairo Sui Framework (cairo-sui-framework)

Implementation of Sui Framework (0x2) for Cairo:

Module	Description	API Status
object	Object system with UID	✅ Complete
transfer	Ownership & transfers	✅ Complete
tx_context	Transaction context	✅ Complete
event	Event emission	✅ Complete
coin	Fungible tokens	✅ Complete
balance	Balance management	✅ Complete
table	Key-value storage	🚧 In Progress
dynamic_field	Dynamic object fields	🚧 In Progress

🛠️ CLI Usage

Standard Library Commands

# Initialize Move/Sui stdlib sources
move2cairo stdlib init --output ./stdlib

# Build Cairo standard libraries
move2cairo stdlib build --source ./stdlib --output ./cairo-stdlib

# List available stdlib modules
move2cairo stdlib list

# Generate specific module
move2cairo stdlib generate vector --output vector.cairo

Package Commands

# Create new Move package from template
move2cairo package new my_project

# Validate and build Move package
cd my_project
sui move build

# Transpile to Cairo package
move2cairo package build --output ../my_project_cairo

# Compile Cairo package
cd ../my_project_cairo
scarb build

📝 Example: NFT Contract

Move Source (sources/nft.move)

module my_project::nft {
    use sui::object::{Self, UID};
    use sui::transfer;
    use sui::tx_context::{Self, TxContext};
    use std::string::String;

    struct NFT has key, store {
        id: UID,
        name: String,
        description: String,
        url: String,
    }

    public fun mint(
        name: String,
        description: String,
        url: String,
        ctx: &mut TxContext
    ) {
        let nft = NFT {
            id: object::new(ctx),
            name,
            description,
            url,
        };
        transfer::transfer(nft, tx_context::sender(ctx));
    }

    public fun burn(nft: NFT) {
        let NFT { id, name: _, description: _, url: _ } = nft;
        object::delete(id);
    }
}

Generated Cairo (src/nft.cairo)

#[starknet::contract]
mod nft {
    use starknet::ContractAddress;
    use cairo_sui_framework::object::{UID, new_uid, delete_uid};
    use cairo_sui_framework::transfer;
    use cairo_sui_framework::tx_context::TxContext;
    use cairo_move_core::string::String;

    #[storage]
    struct Storage {
        nft_storage: LegacyMap<felt252, NFT>,
    }

    #[derive(Drop, Serde, starknet::Store)]
    struct NFT {
        id: UID,
        name: String,
        description: String,
        url: String,
    }

    #[external(v0)]
    fn mint(
        ref self: ContractState,
        name: String,
        description: String,
        url: String,
        ctx: TxContext
    ) {
        let nft = NFT {
            id: new_uid(),
            name,
            description,
            url,
        };
        let sender = ctx.sender;
        transfer::transfer(nft, sender);
    }

    #[external(v0)]
    fn burn(ref self: ContractState, nft: NFT) {
        let NFT { id, name: _, description: _, url: _ } = nft;
        delete_uid(id);
    }
}

🗺️ Type Mappings

Basic Types

Move Type	Cairo Type	Notes
u8-u256	u8-u256	Direct mapping
bool	bool	Direct mapping
address	ContractAddress	Starknet addresses
vector<T>	Array<T>	Dynamic arrays
string	ByteArray	UTF-8 strings

Object System

Move Ability	Cairo Implementation	Effect
key	Storage + UID field	Enables global storage
store	Store trait	Can be stored in objects
copy	Copy trait	Value duplication
drop	Drop trait	Automatic cleanup

📊 Project Status

✅ Completed (v0.2.1)

• Package-level transpilation architecture
• Complete Move Core library (0x1) with all modules
• Core Sui Framework modules (0x2) including coin, balance, object, transfer
• CLI with comprehensive commands
• Basic type system conversion
• Object ownership model
• Automatic .gitignore generation for Cairo projects
• Cairo 2.8.2 storage trait support (StoragePointerReadAccess, StoragePointerWriteAccess, etc.)
• Scarb.toml generation with proper edition and target configuration
• Successful test_coin transpilation and verification

🚧 In Progress

• Additional collection types (Table, Bag, LinkedTable)
• Dynamic fields and object fields
• Generic type instantiation
• Comprehensive test suite
• Full Move AST to Cairo AST conversion
• Advanced pattern matching for complex Move constructs

📋 Roadmap

• Basic coin/token transpilation
• Storage trait handling for Cairo 2.8.2
• Complete Sui Framework implementation
• PTB (Programmable Transaction Blocks) support
• Source mapping for debugging
• VS Code extension
• Gas optimization analysis
• Formal verification bridge
• Publishing cairo-move-core and cairo-sui-framework to Scarb registry

📁 Project Structure

move-to-cairo/
├── crates/
│   ├── ast/                    # AST definitions for Move/Cairo/IR
│   ├── cli/                    # CLI binary and commands
│   ├── package-parser/         # Move package parsing and validation
│   └── stdlib-transpiler/      # Standard library transpilation
├── cairo-move-stdlib/           # Generated Cairo standard libraries
│   ├── cairo-move-core/        # Move Core library (0x1)
│   └── cairo-sui-framework/    # Sui Framework (0x2)
├── examples/                    # Example Move packages
└── docs/                       # Additional documentation

📦 Example: Test Coin Transpilation

Successfully Verified Example

# 1. Create a Move coin package
sui move new test_coin
cd test_coin

# 2. Write Move coin module (sources/test_coin.move)
# Implements mint, burn, transfer functions

# 3. Validate Move package
sui move build

# 4. Transpile to Cairo
move2cairo package build -o ../test_coin_cairo

# 5. Compile Cairo package
cd ../test_coin_cairo
scarb build  # ✅ Compiles successfully!

The transpiler correctly handles:

• Treasury cap pattern for minting control
• Storage Map for balance tracking
• Event emissions for all operations
• Cairo 2.8.2 storage access traits

🧪 Testing

# Run all tests
cargo test --all

# Test specific component
cargo test -p package-parser
cargo test -p stdlib-transpiler

# Build and test Cairo libraries
cd cairo-move-stdlib/cairo-move-core && scarb test
cd cairo-move-stdlib/cairo-sui-framework && scarb test

# Test with example packages
cd examples/simple_nft && move2cairo package build && scarb build

🐛 Troubleshooting

Common Issues

Issue: sui move build fails

# Solution: Ensure Sui CLI is installed and Move.toml is valid
sui --version
cat Move.toml

Issue: Cairo package doesn't compile

# Solution: Check Scarb version and dependencies
scarb --version  # Should be 2.8.2+
scarb clean && scarb build

Issue: Type conversion errors

# Solution: Review type mappings and ensure proper trait bounds
# Add +Drop<T>, +Copy<T> as needed for generic types

🤝 Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

Development Workflow

# 1. Fork and clone
git clone https://github.com/YOUR_USERNAME/move-to-cairo

# 2. Create feature branch
git checkout -b feature/amazing-feature

# 3. Make changes and test
cargo test --all
cargo fmt --all
cargo clippy --all

# 4. Commit and push
git commit -m "Add amazing feature"
git push origin feature/amazing-feature

# 5. Open Pull Request

📄 License

Dual-licensed under:

• MIT License (LICENSE-MIT)
• Apache License 2.0 (LICENSE-APACHE)

🙏 Acknowledgments

• Sui - Move language and framework
• Starknet - Cairo language and platform
• Foundation3 DAO - Project support and funding
• Community contributors

📚 Resources

• Move Book - Learn Move
• Sui Docs - Sui Framework
• Cairo Book - Learn Cairo
• Starknet Docs - Starknet platform

📞 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Email: contact@foundation3.org

---

Current Version: 0.2.1-alpha | Status: Active Development | Last Updated: August 2025