@cura-lab/monad-sdk v1.4.0

@cura/monad-sdk

TypeScript SDK for interacting with Cura Protocol contracts on the Monad blockchain.

Overview

The Monad SDK provides a comprehensive interface for interacting with Cura Protocol's smart contracts on the Monad network. Monad is a high-performance, EVM-compatible blockchain that offers Ethereum compatibility with significantly improved throughput and efficiency.

Contract Suite

The SDK provides access to three core CURA contracts:

• CuraToken: ERC20 token with whitelist/blacklist functionality
• AdminManagement: Role-based access control for protocol governance
• RewardDistribution: Signature-based reward distribution system

Installation

npm install @cura/monad-sdk
# or
yarn add @cura/monad-sdk

Environment Setup

For development and testing, you'll need to set up environment variables:

1. Copy the example environment file:

cp .env.example .env

2. Fill in your configuration:

# Your Monad testnet private key (without 0x prefix)
MONAD_PRIVATE_KEY=your_private_key_here

# Deployed contract addresses on Monad testnet
CURA_TOKEN_ADDRESS=0xf2F44cb5302c38e627779529eed2d17a85DE9Fbf
ADMIN_MANAGEMENT_ADDRESS=0x331918D01f7E992620cEa50cbd7bba1c892E0624
REWARD_DISTRIBUTION_ADDRESS=0x6cb12396f502b01c44Dc91A4aA145E9672D61268

3. Test your connection:

yarn test:connection

Features

• 🔐 Full contract interaction support for all Cura Protocol contracts
• 💰 ERC20 token operations with whitelist/blacklist functionality
• 👥 Admin management for protocol governance
• 🎁 Signature-based reward distribution system
• 📝 TypeScript-first with comprehensive type definitions
• ⚡ Ethers v6 integration for modern blockchain interactions
• 🔄 Flexible initialization with multiple connection methods
• 🧪 Complete test suite with unit and integration tests

Quick Start

import { MonadSDK } from '@cura/monad-sdk';
import { ethers } from 'ethers';

// Initialize from RPC URL
const sdk = await MonadSDK.fromRpcUrl('https://testnet-rpc.monad.xyz');

// Or initialize with private key
const sdk = await MonadSDK.fromPrivateKey(
  privateKey,
  'https://testnet-rpc.monad.xyz'
);

// Or initialize with existing provider/signer
const provider = new ethers.JsonRpcProvider('https://testnet-rpc.monad.xyz');
const signer = new ethers.Wallet(privateKey, provider);
const sdk = new MonadSDK({
  provider,
  signer,
  contracts: {
    curaToken: '0xf2F44cb5302c38e627779529eed2d17a85DE9Fbf',
    adminManagement: '0x331918D01f7E992620cEa50cbd7bba1c892E0624',
    rewardDistribution: '0x6cb12396f502b01c44Dc91A4aA145E9672D61268'
  }
});

Core Contracts

1. CuraToken Contract

ERC20 token with additional whitelist/blacklist functionality.

// Basic ERC20 operations
const balance = await sdk.curaToken.balanceOf(address);
const tx = await sdk.curaToken.transfer(recipient, amount);

// Minting and burning (admin only)
await sdk.curaToken.mint(recipient, amount);
await sdk.curaToken.burn(amount);

// Whitelist/Blacklist management (admin only)
await sdk.curaToken.updateWhitelist(address, true); // Add to whitelist
await sdk.curaToken.updateBlacklist(address, true); // Add to blacklist

// Check status
const isWhitelisted = await sdk.curaToken.whitelist(address);
const isBlacklisted = await sdk.curaToken.blacklist(address);

// Helper methods
const balance = await sdk.curaToken.getBalance(address); // Returns formatted balance
const parsedAmount = sdk.curaToken.parseAmount('100.5'); // Convert to wei
const formattedAmount = sdk.curaToken.formatAmount(amount); // Convert from wei

2. AdminManagement Contract

Manages admin roles and permissions across the protocol.

// Check roles
const isAdmin = await sdk.adminManagement.isAdmin(address);
const isSuperAdmin = await sdk.adminManagement.isSuperAdmin(address);

// Manage admins (super admin only)
await sdk.adminManagement.addAdmin(newAdminAddress);
await sdk.adminManagement.removeAdmin(adminAddress);

// Transfer ownership (super admin only)
await sdk.adminManagement.transferOwnership(newOwnerAddress);

3. RewardDistribution Contract

Distributes rewards using cryptographic signatures for verification.

import { createRewardSignature } from '@cura/monad-sdk';

// Create signature for reward
const signature = await createRewardSignature(
  signer,
  rewardId,
  recipient,
  amount
);

// Distribute single reward
await sdk.rewardDistribution.distributeReward(
  rewardId,
  recipient,
  amount,
  signature
);

// Distribute multiple rewards (batch)
const rewards = [
  { rewardId: 1, recipient: '0x...', amount: 100n },
  { rewardId: 2, recipient: '0x...', amount: 200n }
];
await sdk.rewardDistribution.distributeRewards(rewards, signer);

// Check if reward is processed
const isProcessed = await sdk.rewardDistribution.isRewardProcessed(rewardId);

Batch Reward Distribution

For efficiently distributing rewards to multiple users:

import { createBatchRewards, parseUnits } from '@cura/monad-sdk';

// Define multiple recipients
const recipients = [
  { address: '0x742d35Cc6634C0532925a3b8D563d7c6a4F3A9BC', amount: parseUnits('10', 18) },
  { address: '0x8A39E1Ad1b721aE98a8924F62D047a2D94A8b84b', amount: parseUnits('25', 18) },
  { address: '0x1234567890123456789012345678901234567890', amount: parseUnits('5', 18) }
];

// Create batch with signatures
const batchRewards = createBatchRewards(recipients, serverPrivateKey);

// Distribute with optimized batching
await sdk.rewardDistribution.distributeRewardsBatch(batchRewards, {
  batchSize: 10, // Process 10 transactions in parallel
  gasMultiplier: 1.3, // 30% gas buffer
  maxFeePerGas: parseUnits('50', 'gwei')
});

console.log(`✅ Distributed rewards to ${recipients.length} users`);

Utility Functions

Signature Utilities

import { 
  createRewardMessage,
  createRewardSignature,
  verifyRewardSignature 
} from '@cura/monad-sdk';

// Create message hash
const messageHash = createRewardMessage(rewardId, recipient, amount);

// Sign message
const signature = await createRewardSignature(
  signer,
  rewardId,
  recipient,
  amount
);

// Verify signature
const isValid = verifyRewardSignature(
  messageHash,
  signature,
  expectedSigner
);

Network Configuration

Monad Network Details

• Testnet RPC: https://testnet-rpc.monad.xyz
• Chain ID: 10143
• Block Explorer: https://testnet.monadexplorer.com
• Faucet: https://monad-networks-testnet.vercel.app/

Contract Addresses

// Monad Testnet (Chain ID: 10143)
const MONAD_TESTNET_CONTRACTS = {
  curaToken: '0xf2F44cb5302c38e627779529eed2d17a85DE9Fbf',
  adminManagement: '0x331918D01f7E992620cEa50cbd7bba1c892E0624',
  rewardDistribution: '0x6cb12396f502b01c44Dc91A4aA145E9672D61268'
};

// Mainnet addresses (when available)
const MONAD_MAINNET_CONTRACTS = {
  curaToken: '0x...', // TBD
  adminManagement: '0x...', // TBD
  rewardDistribution: '0x...' // TBD
};

Advanced Usage

Custom Transaction Options

All write methods accept optional transaction parameters:

await sdk.curaToken.transfer(recipient, amount, {
  gasLimit: 100000n,
  gasPrice: ethers.parseUnits('20', 'gwei'),
  nonce: 42
});

Working with Different Signers

// Connect a new signer
const newSigner = new ethers.Wallet(privateKey, provider);
sdk.connect(newSigner);

// Get current signer address
const signerAddress = await sdk.getSignerAddress();

// Get chain ID
const chainId = await sdk.getChainId();

Architecture

The SDK follows a modular architecture:

• Core SDK Class: MonadSDK manages provider/signer and contract instances
• Contract Wrappers: Individual classes for each smart contract
• Base Contract: Abstract class providing common functionality
• Utilities: Helper functions for signatures, formatting, etc.
• Types: Comprehensive TypeScript definitions

Key Differences from Solana SDK

As Monad is EVM-compatible, this SDK differs significantly from the Solana SDK:

Development Status

✅ Completed

• Core SDK architecture
• All contract wrappers with full functionality
• Signature utilities for reward distribution
• TypeScript type definitions
• Comprehensive test suite (unit + integration)
• ERC20 helper methods
• Monad testnet deployment and testing
• Complete documentation

🚧 In Progress

• Mainnet deployment preparation
• Enhanced error handling with revert reasons
• Transaction receipt parsing for return values
• Additional integration test scenarios

📋 Planned

• Event listening and filtering utilities
• Gas estimation helpers
• Transaction retry logic
• Batch transaction utilities
• Developer documentation and tutorials

Contributing

🚨 IMPORTANT: Before making ANY changes to this SDK, you MUST read CONTRIBUTING.md

Quick Contribution Checklist

Before submitting any changes:

• Create changeset: yarn changeset
• Run unit tests: yarn test:unit (must pass 100%)
• Run integration tests: yarn test:integration (must pass 100%)
• Update documentation (README, TESTING.md, examples)
• Test against live Monad testnet contracts
• Verify build: yarn build
• Lint code: yarn lint

Contract Integration Testing

All changes affecting contract interactions MUST be tested against live deployed contracts:

# Set environment variables
export MONAD_PRIVATE_KEY="your-testnet-private-key"
export CURA_TOKEN_ADDRESS="0xf2F44cb5302c38e627779529eed2d17a85DE9Fbf"
export ADMIN_MANAGEMENT_ADDRESS="0x331918D01f7E992620cEa50cbd7bba1c892E0624"
export REWARD_DISTRIBUTION_ADDRESS="0x6cb12396f502b01c44Dc91A4aA145E9672D61268"

# Run integration tests
yarn test:integration

See CONTRIBUTING.md for detailed development procedures.

License

This project is licensed under the same terms as the main Cura Protocol repository.