Tesseract: Cross-Rollup Atomic Swap Protocol

Tesseract is a production-ready cross-rollup atomic swap protocol enabling trustless token exchanges across Ethereum L2s. Built with Vyper smart contracts, a high-performance Rust relayer, and comprehensive DeFi security features including MEV protection, flash loan resistance, and atomic swap groups.

Use Cases

Cross-Chain DeFi Operations

Execute atomic transactions across multiple rollups for DeFi protocols:

Arbitrage: Execute simultaneous trades across Ethereum, Polygon, and Arbitrum
Liquidity Management: Rebalance liquidity pools across multiple chains atomically
Cross-Chain Lending: Coordinate collateral deposits and borrows across rollups
Multi-Chain Governance: Execute governance decisions across multiple networks

Enterprise Cross-Chain Workflows

Enable complex business logic across blockchain networks:

Supply Chain: Track and verify goods across multiple blockchain networks
Identity Management: Synchronize identity states across enterprise rollups
Payment Rails: Coordinate payments and settlements across different networks
Data Synchronization: Ensure consistent state across multi-chain applications

Infrastructure and Protocol Integration

Build robust cross-chain infrastructure:

Bridge Protocols: Coordinate secure asset transfers between rollups
Oracle Networks: Synchronize data feeds across multiple chains
Cross-Chain DAOs: Enable governance across multiple blockchain networks
Interoperability Layers: Build universal compatibility between rollups

Quick Start

# Clone and setup environment
git clone https://github.com/your-org/tesseract.git
cd tesseract
uv sync

# Verify contract compilation (7 contracts)
uv run pytest tests/test_compilation.py -v

# Run full test suite
uv run pytest tests/ -v

# Deploy to testnet
uv run python scripts/deploy_simple.py sepolia

Documentation: docs/ | API Reference: docs/API_DOCUMENTATION_UPDATED.md | Contributing: CONTRIBUTING.md

Core Features

DeFi Security

MEV Protection: Commit-reveal scheme prevents front-running and sandwich attacks
Flash Loan Resistance: Minimum 2-block delay before transaction resolution
Atomic Swap Groups: Multi-leg swaps execute atomically or revert together
Slippage Protection: Configurable minimum receive amounts per swap

Cross-Rollup Coordination

Atomic Swaps: Trustless token exchanges across L2s without bridges
Dependency Resolution: DAG-based transaction ordering and validation
Time-Bounded Execution: Configurable coordination windows (5-300 seconds)
Automatic Refunds: Failed/expired transactions return funds to users

High-Performance Relayer (Rust)

Multi-Chain Monitoring: WebSocket + HTTP failover for 4+ chains
Finality Tracking: Chain-specific confirmation requirements
Nonce Management: Gap handling and stuck transaction recovery
Auto-Scaling: 2-10 instances with CPU-based scaling

Tokenomics & Governance

TESS Token: Governance and fee discount token
Staking Rewards: 5-15% APY based on lock duration
Fee Discounts: Up to 50% fee reduction for stakers
On-Chain Governance: Proposal and voting system

Multi-Network Support

Ethereum (Mainnet / Sepolia)
Polygon (Mainnet / Amoy)
Arbitrum (One / Sepolia)
Optimism (Mainnet / Sepolia)
Base (Mainnet / Sepolia)

Architecture

┌─────────────────────────────────────────────────────────────────────────────┐
│                              Tesseract Protocol                              │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                              │
│  ┌──────────────┐    ┌──────────────┐    ┌──────────────┐    ┌───────────┐  │
│  │  Ethereum    │    │   Polygon    │    │   Arbitrum   │    │  Optimism │  │
│  │  Sepolia     │    │    Amoy      │    │   Sepolia    │    │  Sepolia  │  │
│  └──────┬───────┘    └──────┬───────┘    └──────┬───────┘    └─────┬─────┘  │
│         │                   │                   │                  │        │
│         └───────────────────┴───────────────────┴──────────────────┘        │
│                                     │                                        │
│                          ┌──────────▼──────────┐                            │
│                          │    Rust Relayer     │                            │
│                          │  ┌───────────────┐  │                            │
│                          │  │ Chain Listener│  │                            │
│                          │  │ Coordination  │  │                            │
│                          │  │ TX Sender     │  │                            │
│                          │  └───────────────┘  │                            │
│                          └──────────┬──────────┘                            │
│                                     │                                        │
│  ┌──────────────────────────────────┼──────────────────────────────────┐    │
│  │                    Smart Contracts (Vyper)                          │    │
│  │  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────────┐  │    │
│  │  │ TesseractBuffer │  │ SwapCoordinator │  │    Tokenomics       │  │    │
│  │  │ • Buffer TX     │  │ • Create Order  │  │ • TESS Token        │  │    │
│  │  │ • Commit-Reveal │  │ • Fill Order    │  │ • Staking           │  │    │
│  │  │ • Swap Groups   │  │ • Slippage      │  │ • Fee Collector     │  │    │
│  │  │ • Refunds       │  │ • Partial Fills │  │ • Governance        │  │    │
│  │  └─────────────────┘  └─────────────────┘  └─────────────────────┘  │    │
│  └─────────────────────────────────────────────────────────────────────┘    │
│                                                                              │
└─────────────────────────────────────────────────────────────────────────────┘

Smart Contracts (7 total):

Contract	Size	Purpose
`TesseractBuffer.vy`	12,578 bytes	Core transaction buffering with DeFi security
`AtomicSwapCoordinator.vy`	8,332 bytes	Order book and swap coordination
`TesseractToken.vy`	4,521 bytes	TESS governance token (ERC-20)
`TesseractStaking.vy`	6,890 bytes	Staking with tiered rewards
`FeeCollector.vy`	3,245 bytes	Protocol fee collection and distribution
`RelayerRegistry.vy`	4,112 bytes	Relayer bonding and management
`TesseractGovernor.vy`	5,678 bytes	On-chain governance

Rust Relayer:

Multi-chain event monitoring with WebSocket/HTTP
Cross-chain coordination engine
Transaction submission with retry logic
PostgreSQL state persistence
Prometheus metrics export

Documentation

Document	Description
System Architecture	Technical architecture and design patterns
Deployment Guide	Contract deployment instructions
API Documentation	Complete API reference
Security Guidelines	Security best practices
Terraform Infrastructure	AWS deployment with Terraform
Relayer Setup	Rust relayer configuration
Production Checklist	Production deployment checklist

Development Setup

Prerequisites

Python 3.11+: Vyper compiler and testing
Rust 1.75+: Relayer development (optional)
uv: Python package manager
Anvil: Local testing (install via Foundry)

Installation

# Clone repository
git clone https://github.com/your-org/tesseract.git
cd tesseract

# Install Python dependencies
uv sync

# Verify installation
uv run python -c "import vyper; print(f'Vyper: {vyper.__version__}')"

# Build Rust relayer (optional)
cd relayer && cargo build --release

Local Development

# Run all tests
uv run pytest tests/ -v

# Run specific test file
uv run pytest tests/test_compilation.py -v

# Deploy to testnet
uv run python scripts/deploy_simple.py sepolia

# Build and run relayer
cd relayer && cargo run --release

Integration Examples

Atomic Swap with MEV Protection

from web3 import Web3
from eth_utils import keccak

w3 = Web3(Web3.HTTPProvider('YOUR_RPC_URL'))
buffer = w3.eth.contract(address="0x...", abi=buffer_abi)

# Phase 1: Commit (hides payload from MEV bots)
payload = b"swap_100_USDC_for_ETH"
secret = keccak(b"my_secret_salt")
commitment = keccak(payload + secret)

tx_id = keccak(b"unique_swap_id")
swap_group_id = keccak(b"atomic_group_1")

buffer.functions.buffer_transaction_with_commitment(
    tx_id,
    deployer_address,
    target_chain_address,
    commitment,
    bytes(32),  # No dependency
    int(time.time()) + 300,  # 5 min deadline
    swap_group_id,
    refund_recipient
).transact({'from': deployer_address})

# Phase 2: Reveal (after commitment is on-chain)
buffer.functions.reveal_transaction(
    tx_id, payload, secret
).transact({'from': deployer_address})

# Phase 3: Resolve (after MIN_RESOLUTION_DELAY blocks)
buffer.functions.resolve_dependency(tx_id).transact({'from': operator})

Multi-Leg Atomic Swap

# Create 3-way atomic swap: ETH -> USDC -> MATIC
swap_group_id = keccak(b"three_way_swap")
legs = [
    {"from": "ETH", "to": "USDC", "chain": "ethereum"},
    {"from": "USDC", "to": "MATIC", "chain": "polygon"},
    {"from": "MATIC", "to": "ETH", "chain": "arbitrum"},
]

for i, leg in enumerate(legs):
    tx_id = keccak(f"leg_{i}".encode())
    buffer.functions.buffer_transaction_with_commitment(
        tx_id, origin, target, commitment,
        bytes(32), deadline, swap_group_id, refund
    ).transact({'from': deployer})

# All legs must resolve for swap to complete
# If any fail, users can claim refunds after timeout

Creating Swap Orders

coordinator = w3.eth.contract(address="0x...", abi=coordinator_abi)

# Create a swap order
order_id = coordinator.functions.create_swap_order(
    offer_token="0x...",      # USDC address
    offer_amount=1000 * 10**6,  # 1000 USDC
    want_token="0x...",       # WETH address
    want_amount=0.5 * 10**18,   # 0.5 ETH
    min_receive=0.48 * 10**18,  # 4% slippage tolerance
    deadline=int(time.time()) + 3600  # 1 hour
).transact({'from': maker})

# Taker fills the order
coordinator.functions.fill_swap_order(
    order_id, fill_amount=500 * 10**6  # Partial fill: 500 USDC
).transact({'from': taker})

Testing

Test Suite (135 tests)

# Run full test suite
uv run pytest tests/ -v
# Result: 86 passed, 40 xfailed, 9 xpassed

# Run specific test categories
uv run pytest tests/test_compilation.py -v      # Contract compilation
uv run pytest tests/test_tokenomics.py -v       # Tokenomics contracts
uv run pytest tests/test_defi_security.py -v    # DeFi security features

# Run integration tests (requires Anvil)
uv run pytest tests/integration/ -v

# Run load tests
uv run pytest tests/integration/test_load.py -v

Test Categories

Category	Tests	Description
`test_compilation.py`	11	All 7 contracts compile
`test_tokenomics.py`	21	Token, staking, governance
`test_access_control.py`	27	Role-based permissions
`test_safety.py`	26	Emergency controls, circuit breaker
`test_integration/`	23	Cross-chain scenarios

Deployment

Contract Deployment

# Configure environment
export PRIVATE_KEY="0x..."
export SEPOLIA_RPC_URL="https://eth-sepolia.g.alchemy.com/v2/..."

# Deploy to Sepolia
uv run python scripts/deploy_simple.py sepolia

# Verify on block explorer
uv run python scripts/verify_on_explorer.py sepolia

# Health check
uv run python scripts/health_check.py sepolia

Infrastructure Deployment (AWS)

cd infrastructure/terraform

# Deploy staging
terraform init -backend-config=environments/staging/backend.tf
terraform apply -var-file=environments/staging/terraform.tfvars

# Deploy production
terraform init -backend-config=environments/production/backend.tf
terraform apply -var-file=environments/production/terraform.tfvars

Production Status

Component	Status
Smart Contracts (7)	Complete
Rust Relayer	Complete
Test Suite (135 tests)	Complete
Monitoring Stack	Complete
Terraform Infrastructure	Complete
Testnet Deployment	Ready
Security Audit	Pending

See Production Checklist for complete requirements.

Security

DeFi Security Features

MEV Protection: Commit-reveal scheme hides transaction details until execution
Flash Loan Resistance: 2-block minimum delay before resolution
Reentrancy Protection: No external calls during state changes
Slippage Protection: Configurable minimum receive amounts

Smart Contract Security

Vyper Language: Built-in overflow protection, no inheritance complexity
Role-Based Access: Granular permissions (BUFFER_ROLE, RESOLVE_ROLE, ADMIN_ROLE)
Circuit Breaker: Auto-triggers after 50 consecutive failures
Emergency Pause: Instant halt by owner or emergency_admin

Operational Security

Secrets Management: AWS Secrets Manager for private keys
Monitoring: Prometheus metrics + Grafana dashboards + PagerDuty alerts
Multi-RPC Failover: Automatic provider switching on failures

Security Audit Status: Pending professional third-party audit

See Security Guidelines for detailed information.

Performance

Contract Metrics

Operation	Gas Cost	Notes
`buffer_transaction`	~120,000	Basic buffering
`buffer_transaction_with_commitment`	~150,000	With commit-reveal
`reveal_transaction`	~80,000	Reveal phase
`resolve_dependency`	~100,000	Resolution
`create_swap_order`	~180,000	Order creation
`fill_swap_order`	~200,000	Order fill

Relayer Performance

Latency: <30s cross-chain coordination (target)
Throughput: 100+ tx/min per instance
Availability: 99.9% uptime (multi-instance)
Scaling: 2-10 ECS tasks auto-scaling

Optimization Features

512-byte Payload Limit: Minimizes storage costs
Indexed Events: Efficient log filtering
EIP-1559 Gas: Dynamic fee estimation
Batch Operations: Reduced RPC overhead

Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

# Development workflow
git checkout -b feature/my-feature
uv sync --all-extras
uv run pytest tests/ -v
uv run black .
# Submit PR

Code Standards

Vyper: Follow Vyper Style Guide
Python: Format with Black
Rust: Format with cargo fmt, lint with cargo clippy
Tests: Required for all new functionality

License

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

MIT License

Copyright (c) 2025 Tesseract Protocol

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

Acknowledgments

Inspired by CRATE Protocol research
Smart contracts built with Vyper
Relayer built with ethers-rs
Infrastructure powered by Terraform and AWS

Support & Community

Documentation: docs/
Issues: GitHub Issues
Discussions: GitHub Discussions
Discord: Tesseract Community
Twitter: @TesseractProtocol

Built for the multi-rollup future

Name		Name	Last commit message	Last commit date
Latest commit History 6 Commits
.github		.github
artifacts		artifacts
config		config
contracts		contracts
docs		docs
documentation		documentation
infrastructure/terraform		infrastructure/terraform
relayer		relayer
scripts		scripts
tesseract		tesseract
tests		tests
.env.example		.env.example
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
pyproject.toml		pyproject.toml
uv.lock		uv.lock

License

cryptuon/tesseract

Folders and files

Latest commit

History

Repository files navigation

Tesseract: Cross-Rollup Atomic Swap Protocol

Use Cases

Cross-Chain DeFi Operations

Enterprise Cross-Chain Workflows

Infrastructure and Protocol Integration

Quick Start

Core Features

DeFi Security

Cross-Rollup Coordination

High-Performance Relayer (Rust)

Tokenomics & Governance

Multi-Network Support

Architecture

Documentation

Development Setup

Prerequisites

Installation

Local Development

Integration Examples

Atomic Swap with MEV Protection

Multi-Leg Atomic Swap

Creating Swap Orders

Testing

Test Suite (135 tests)

Test Categories

Deployment

Contract Deployment

Infrastructure Deployment (AWS)

Production Status

Security

DeFi Security Features

Smart Contract Security

Operational Security

Performance

Contract Metrics

Relayer Performance

Optimization Features

Contributing

Code Standards

License

Acknowledgments

Support & Community

About

Topics

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Languages

Packages