Smart Contracts

Miko402's autonomous payment system is powered by three core smart contracts that work together to enable secure, transparent, and trustless transactions.

Contract Overview

┌─────────────────────────────────────┐
│          Miko402 Ecosystem          │
├─────────────────────────────────────┤
│  User Interface (Next.js App)       │
├─────────────────────────────────────┤
│  AI Agent (Google Gemini)           │
├─────────────────────────────────────┤
│          Smart Contracts            │
│  ┌───────────────────────────────┐  │
│  │  PaymentGateway.sol           │  │
│  │  - Payment processing         │  │
│  │  - Escrow & release           │  │
│  └───────────────────────────────┘  │
│  ┌───────────────────────────────┐  │
│  │  SpendingLimits.sol           │  │
│  │  - Limit enforcement          │  │
│  │  - Spending tracking          │  │
│  └───────────────────────────────┘  │
│  ┌───────────────────────────────┐  │
│  │  X402Registry.sol             │  │
│  │  - Service discovery          │  │
│  │  - Provider registry          │  │
│  └───────────────────────────────┘  │
├─────────────────────────────────────┤
│  Blockchain (Solana / EVM chains)   │
└─────────────────────────────────────┘

1. PaymentGateway.sol

Purpose

Handles all payment processing, escrow, and fund transfers between users and x402 service providers.

Key Features

• Native token and ERC-20 support

• Payment escrow and release

• Refund mechanism

• Transaction tracking with full audit trail

Core Functions

// Initiate payment with native token
function payNative(
    address payee,
    bytes32 requestHash
) external payable returns (bytes32 paymentId)

// Initiate payment with ERC-20
function payToken(
    address payee,
    address token,
    uint256 amount,
    bytes32 requestHash
) external returns (bytes32 paymentId)

// Complete payment (release funds to provider)
function completePayment(
    bytes32 paymentId
) external

// Refund payment (owner only)
function refundPayment(
    bytes32 paymentId
) external onlyOwner

Data Structures

struct Payment {
    address payer;          // Who paid
    address payee;          // Who receives
    uint256 amount;         // Payment amount
    address token;          // Token address (0x0 for native)
    uint256 timestamp;      // When created
    bytes32 requestHash;    // Service request hash
    bool completed;         // Payment status
}

Events

event PaymentInitiated(bytes32 indexed paymentId, address indexed payer, address indexed payee, uint256 amount, address token);
event PaymentCompleted(bytes32 indexed paymentId, address indexed payer, address indexed payee, uint256 amount);
event PaymentRefunded(bytes32 indexed paymentId, address indexed payer, uint256 amount);

2. SpendingLimits.sol

Purpose

Enforces user-defined spending limits to prevent overspending during autonomous payment operations.

Key Features

• Daily, weekly, and monthly limits

• Automatic time-based resets

• Approved spender management

• Real-time limit checking

Core Functions

function setLimits(uint256 dailyLimit, uint256 weeklyLimit, uint256 monthlyLimit) external
function approveSpender(address spender) external
function revokeSpender(address spender) external
function recordSpending(address user, uint256 amount) external returns (bool)
function getRemainingAllowance(address user) external view returns (uint256 daily, uint256 weekly, uint256 monthly)

Data Structures

struct Limit {
    uint256 dailyLimit;
    uint256 weeklyLimit;
    uint256 monthlyLimit;
    uint256 dailySpent;
    uint256 weeklySpent;
    uint256 monthlySpent;
    uint256 lastDailyReset;
    uint256 lastWeeklyReset;
    uint256 lastMonthlyReset;
    bool active;
}

Events

event LimitSet(address indexed user, uint256 dailyLimit, uint256 weeklyLimit, uint256 monthlyLimit);
event SpendingRecorded(address indexed user, address indexed spender, uint256 amount, uint256 timestamp);
event SpenderApproved(address indexed user, address indexed spender);
event SpenderRevoked(address indexed user, address indexed spender);

3. X402Registry.sol

Purpose

Central on-chain registry for x402-compatible services and their pricing.

Key Features

• Service registration and discovery

• Multi-tier pricing

• Service verification

• Usage statistics tracking

Core Functions

function registerService(
    string memory name,
    string memory description,
    string memory endpoint,
    address paymentAddress,
    uint256 basePrice,
    address acceptedToken
) external returns (bytes32 serviceId)

function addPricingTier(bytes32 serviceId, string memory tierName, uint256 price, uint256 requestLimit, uint256 validityPeriod) external
function updateService(bytes32 serviceId, string memory description, uint256 basePrice, address paymentAddress) external
function verifyService(bytes32 serviceId) external onlyOwner
function recordRequest(bytes32 serviceId, uint256 amount) external

Data Structures

struct Service {
    address provider;
    string name;
    string description;
    string endpoint;
    address paymentAddress;
    uint256 basePrice;
    address acceptedToken;
    bool active;
    uint256 registeredAt;
    uint256 totalRequests;
    uint256 totalRevenue;
}

struct PricingTier {
    string tierName;
    uint256 price;
    uint256 requestLimit;
    uint256 validityPeriod;
}

Contract Interactions

Payment Flow

1. User makes request via AI chat
   ↓
2. AI queries X402Registry for service
   ↓
3. SpendingLimits checks if payment is allowed
   ↓
4. PaymentGateway processes payment
   ↓
5. Service delivers content
   ↓
6. PaymentGateway releases funds
   ↓
7. X402Registry records the request

Limit Enforcement Flow

AI Agent attempts payment
   ↓
SpendingLimits.canSpend()
   ├─ Check daily limit
   ├─ Check weekly limit
   └─ Check monthly limit
   ↓
All pass → recordSpending() → PaymentGateway.pay()
Any fail → Reject → Notify user

Security Features

Access Control

• Ownable — Admin-only functions

• approvedSpenders — Authorized agent addresses

• ReentrancyGuard — Reentrancy attack prevention

Input Validation

• Non-zero address checks

• Positive amount validation

• Limit hierarchy enforcement

• Service existence verification

Gas Optimization

• Struct packing for efficient storage slots

• Minimized SLOAD operations

• Batch payments coming soon

Upgradeability

Contracts are currently non-upgradeable for security. Future plans include a proxy pattern with timelock governance, multi-sig approval, and community voting.

Testing

Each contract has 30+ tests covering normal operations, edge cases, access control, error handling, gas optimization, and integration scenarios.

See /contracts/test/ for the full test suite.

Deployment

Supported Networks

• Solana (adapted version)

• Ethereum Mainnet

• Polygon

• Base

• Arbitrum

• Optimism

Deployment Process

npx hardhat compile
npx hardhat test
npx hardhat run scripts/deploy.js --network sepolia
npx hardhat verify --network sepolia CONTRACT_ADDRESS

Contract Addresses

Mainnet: Coming soon Testnet (Sepolia): Available in the repository

Audits

Security audits are in progress with professional auditing firms. All contracts are open source and available for community review.

Source Code

All contracts are open source under the MIT License:

• GitHub: github.com/Miko402-xyz/miko402

• Folder: /contracts

Related Documentation

• Spending Limits — User-facing limit configuration

• Autonomous Payments — Payment flow details

• Chat API — API endpoint documentation

---

Questions? Email [email protected] or open an issue on GitHub.