Mezo Compose SDK

A React SDK for building DeFi apps on Mezo. Handles multi-asset allocation, swaps, and portfolio management with Bitcoin and MUSD.

What is this?

Building DeFi UIs on Mezo means dealing with oracles, token approvals, transaction batching, and all that fun stuff. This SDK wraps those primitives into React components and hooks so you can focus on your app logic instead of reinventing the wheel.

What's included:

• React components for asset allocation and portfolio management
• Hooks for prices (Skip Connect + Pyth oracles) and balances
• Transaction builders for approvals, allocations, and swaps
• Full TypeScript support
• Works with RainbowKit, MetaMask, or bring your own wallet

Current status: Deployed on Mezo Testnet, allocate mode fully tested with on-chain transactions. Swap mode integrated with Mezo Pools (Tigris DEX) but limited by testnet liquidity.

Install

npm install mezo-compose-sdk

You'll also need these peer dependencies if you don't have them:

npm install react react-dom @rainbow-me/rainbowkit @tanstack/react-query viem wagmi

Quick start

Basic component usage

import { MezoOracleService, MEZO_TESTNET_CONFIG, Assets } from 'mezo-compose-sdk';

function App() {
  const service = new MezoOracleService(MEZO_TESTNET_CONFIG);
  
  return (
    <Assets
      service={service}
      targetAmount={1000}
      onPurchase={(payload) => {
        console.log('User wants to allocate:', payload);
        // Handle the transaction
      }}
    />
  );
}

This gives you a full UI with sliders for allocating between BTC, MUSD, mUSDC, and mUSDT. The component handles:

• Real-time price feeds (updates every 5s)
• Balance checking
• Allocation calculations
• Input validation

Using hooks directly

If you want more control:

import { usePrices, useBalances } from 'mezo-compose-sdk';

function MyComponent() {
  const { prices, loading } = usePrices(service);
  const { balances } = useBalances(service, wallet);
  
  if (loading) return <div>Loading prices...</div>;
  
  return (
    <div>
      <p>BTC: ${(Number(prices.btcUsd) / 1e8).toFixed(2)}</p>
      <p>MUSD: ${(Number(prices.musdUsd) / 1e8).toFixed(4)}</p>
      <p>Your balance: {(Number(balances.btc) / 1e18).toFixed(6)} BTC</p>
    </div>
  );
}

Building transactions

import { buildAllocateBatchTransaction, MEZO_COMPOSE_CONTRACT } from 'mezo-compose-sdk';

// After user confirms allocation
const batchCalls = buildAllocateBatchTransaction(payload.items, 31611);

// This gives you an array of transactions: approvals first, then allocate call
// Feed these to your wallet connector

Features

Two modes

Allocate: Transfer multiple tokens to a holding contract in one transaction. Good for portfolio rebalancing, DCA strategies, or batching deposits.

Swap: Execute swaps through Mezo Pools (Tigris DEX). Supports both direct swaps (like MUSD→mUSDC) and multi-hop routing through MUSD.

Note: Swap mode works on mainnet where pools have liquidity. On testnet, BTC pools are mostly empty but stablecoin pairs (MUSD/mUSDC/mUSDT) should work.

Oracle integration

• BTC prices: Skip Connect Oracle (Chainlink-compatible)
• Stablecoin prices: Pyth Network (MUSD, mUSDC, mUSDT)
• All prices normalized to 8 decimals
• Automatic retries and error handling

Transaction helpers

The SDK handles annoying stuff like:

• Building approval transactions for multiple tokens
• Batching approvals + main transaction
• BigInt arithmetic for precision
• ABI encoding for contract calls
• Route optimization for swaps

Supported assets

Mezo Testnet (Chain ID: 31611)

| Token | Address | Decimals | |-------|---------|----------| | BTC | 0x7b7C000000000000000000000000000000000000 | 18 | | MUSD | 0x118917a40FAF1CD7a13dB0Ef56C86De7973Ac503 | 18 | | mUSDC | 0x04671C72Aab5AC02A03c1098314b1BB6B560c197 | 6 | | mUSDT | 0xeB5a5d39dE4Ea42C2Aa6A57EcA2894376683bB8E | 6 |

Mainnet support coming soon (just need to update addresses in config).

Project structure

src/
├── components/      # React components (Assets.tsx)
├── hooks/           # usePrices, useBalances, useAssetData
├── services/        # MezoOracleService, MezoSwapService
├── contracts/       # ABIs and addresses (MezoCompose, MezoRouter)
├── utils/           # PurchaseCalculator, transactionBuilder, formatters
├── adapters/        # Wallet adapters (RainbowKit, MetaMask)
└── types/           # TypeScript definitions

Everything's exported from index.ts so you can import what you need.

API

Components

<Assets />

The main allocation UI component.

Props:

• service: AssetDataService - Oracle service instance
• assets?: AssetConfig[] - Custom asset list (defaults to Mezo testnet assets)
• wallet?: Wallet - Connected wallet info
• targetAmount?: number - Target USD amount (default: 1000)
• onAllocationChange?: (state) => void - Callback when sliders change
• onPurchase?: (payload) => void - Callback when user clicks Purchase

Hooks

usePrices(service, interval?)
Fetches prices from oracles, auto-refreshes every interval ms (default 5000).

useBalances(service, wallet)
Gets token balances for connected wallet.

useAssetData(service, wallet, interval?)
Combines prices + balances in one hook.

Services

MezoOracleService

const service = new MezoOracleService(config);
const prices = await service.getPrices();
const balances = await service.getBalances(address);

MezoSwapService

const swapService = new MezoSwapService(rpcUrl, chainId);
const quote = await swapService.getSwapQuote({
  fromToken: '0x...',
  toToken: '0x...',
  amountIn: 1000000n,
  slippageTolerance: 0.5
});

Utils

PurchaseCalculator.createPurchasePayload()
Takes allocation state and returns a structured payload with all the token amounts, fees, etc.

buildAllocateBatchTransaction(items, chainId)
Builds approval + allocate call.

buildRouterSwapTransaction(params, chainId)
Builds approval + swap call via Mezo Router.

Development

Run the demo app:

npm run dev
# Opens on localhost:5173

Build the SDK:

npm run build
# Outputs to dist/

The demo app (src/App.tsx) shows both allocate and swap modes. It's a good reference for integration.

Deployed contracts

MezoCompose (Testnet): 0x201b0a661d692Bd4938e4A7Ce957209b4288B259
Router (Testnet): 0x9a1ff7FE3a0F69959A3fBa1F1e5ee18e1A9CD7E9

See DEPLOYMENT.md for deployment details.

Known issues / limitations

• Testnet swap liquidity: BTC/MUSD pool is basically empty on testnet. Stablecoin pairs have better liquidity. This isn't an issue on mainnet.
• Oracle reliability: Pyth feeds update frequently. Skip Connect is rock solid. Both have fallback handling.
• Type warnings: Some Viem type incompatibilities in strict mode (doesn't affect runtime).

Network info

Testnet:

• Chain ID: 31611
• RPC: https://rpc.test.mezo.org
• Explorer: https://explorer.test.mezo.org
• Faucet: https://faucet.test.mezo.org or ask in Discord

Mainnet:

• Chain ID: 31612
• RPC: https://rpc-http.mezo.boar.network
• Explorer: https://explorer.mezo.org

Use cases

This SDK works well for:

• Portfolio managers / rebalancing UIs
• DeFi aggregators that need multi-asset support
• Payment flows with multiple tokens
• DEX frontends (especially with the Router integration)
• Anything that needs batched transactions on Mezo

Basically anywhere you're dealing with multiple ERC20s and need clean UX.

Contributing

PRs welcome. The codebase is pretty straightforward - components use hooks, hooks call services, services hit contracts.

If you're adding features:

1. Keep types updated
2. Add exports to index.ts
3. Test on testnet before opening PR
4. Update this README if you add new exports

Resources

• Mezo Docs: https://mezo.org/docs
• Discord: https://discord.com/invite/mezo
• Mezo Pools Docs: https://mezo.org/docs/developers/features/mezo-pools
• Testnet Explorer: https://explorer.test.mezo.org

License

MIT - see LICENSE

Built for the Mezo Hackathon (Advanced DeFi Solutions track).

Testnet contract: 0x201b0a661d692Bd4938e4A7Ce957209b4288B259