Smart Contracts

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

Contract Overview

┌─────────────────────────────────────┐
│        Jarvis402 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          │  │
│  └───────────────────────────────┘  │
│  ┌───────────────────────────────┐  │
│  │  Jarvis402Token.sol           │  │
│  │  - Ecosystem token (J402)     │  │
│  │  - Rewards & governance       │  │
│  └───────────────────────────────┘  │
├─────────────────────────────────────┤
│  Blockchain (Ethereum/Solana/etc)   │
└─────────────────────────────────────┘

1. PaymentGateway.sol

Purpose

Handles all payment processing, escrow, and fund transfers.

Key Features

  • Native token and ERC20 support

  • Payment escrow and release

  • Refund mechanism

  • Transaction tracking

Core Functions

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

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

// Complete payment (release funds)
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.

Key Features

  • Daily/weekly/monthly limits

  • Automatic time-based resets

  • Approved spender management

  • Real-time limit checking

Core Functions

// Set spending limits
function setLimits(
    uint256 dailyLimit,
    uint256 weeklyLimit,
    uint256 monthlyLimit
) external

// Approve spender (AI agent)
function approveSpender(
    address spender
) external

// Revoke spender approval
function revokeSpender(
    address spender
) external

// Record spending (called by approved spender)
function recordSpending(
    address user,
    uint256 amount
) external returns (bool)

// Get remaining allowance
function getRemainingAllowance(
    address user
) external view returns (
    uint256 daily,
    uint256 weekly,
    uint256 monthly
)

Data Structures

struct Limit {
    uint256 dailyLimit;        // Max per day
    uint256 weeklyLimit;       // Max per week
    uint256 monthlyLimit;      // Max per month
    uint256 dailySpent;        // Spent today
    uint256 weeklySpent;       // Spent this week
    uint256 monthlySpent;      // Spent this month
    uint256 lastDailyReset;    // Last reset timestamp
    uint256 lastWeeklyReset;   // Last reset timestamp
    uint256 lastMonthlyReset;  // Last reset timestamp
    bool active;               // Limits enabled?
}

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 registry for x402-compatible services and their pricing.

Key Features

  • Service registration

  • Multi-tier pricing

  • Service verification

  • Statistics tracking

Core Functions

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

// Add pricing tier
function addPricingTier(
    bytes32 serviceId,
    string memory tierName,
    uint256 price,
    uint256 requestLimit,
    uint256 validityPeriod
) external

// Update service details
function updateService(
    bytes32 serviceId,
    string memory description,
    uint256 basePrice,
    address paymentAddress
) external

// Verify service (admin only)
function verifyService(
    bytes32 serviceId
) external onlyOwner

// Record service request
function recordRequest(
    bytes32 serviceId,
    uint256 amount
) external

Data Structures

struct Service {
    address provider;       // Service owner
    string name;           // Service name
    string description;    // Description
    string endpoint;       // API endpoint
    address paymentAddress;// Payment recipient
    uint256 basePrice;     // Base price
    address acceptedToken; // Token accepted
    bool active;           // Service status
    uint256 registeredAt;  // Registration time
    uint256 totalRequests; // Request count
    uint256 totalRevenue;  // Total earned
}

struct PricingTier {
    string tierName;       // Tier name
    uint256 price;         // Tier price
    uint256 requestLimit;  // Requests included
    uint256 validityPeriod;// How long valid
}

Events

event ServiceRegistered(
    bytes32 indexed serviceId,
    address indexed provider,
    string name,
    string endpoint
);

event ServiceVerified(
    bytes32 indexed serviceId
);

event PricingTierAdded(
    bytes32 indexed serviceId,
    string tierName,
    uint256 price
);

event RequestRecorded(
    bytes32 indexed serviceId,
    uint256 amount
);

4. Jarvis402Token.sol (J402)

Purpose

Native ecosystem token for rewards, governance, and staking.

Key Features

  • ERC20 compliant

  • Fixed max supply (1B)

  • Reward distribution

  • Staking mechanism

Core Functions

// Mint new tokens (owner only)
function mint(
    address to,
    uint256 amount
) external onlyOwner

// Distribute rewards
function distributeReward(
    address recipient,
    uint256 amount,
    string memory reason
) external

// Reward service provider
function rewardServiceProvider(
    address provider
) external

// Reward payment completion
function rewardPayment(
    address payer
) external

// Stake tokens
function stake(
    uint256 amount
) external

// Unstake tokens
function unstake(
    uint256 amount
) external

// Get staking info
function getStakingInfo(
    address account
) external view returns (
    uint256 staked,
    uint256 stakingTime,
    uint256 rewardsEarned
)

Token Economics

Max Supply: 1,000,000,000 J402
Initial Supply: 100,000,000 J402

Rewards:
- Service Registration: 100 J402
- Payment Completion: 1 J402

Distribution:
- 40% Community rewards
- 20% Team & advisors
- 20% Ecosystem fund
- 10% Liquidity
- 10% Development

Contract Interactions

Payment Flow

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

Limit Enforcement Flow

AI Agent attempts payment
   ↓
SpendingLimits.canSpend()
   ├─ Check daily limit
   ├─ Check weekly limit
   └─ Check monthly limit
   ↓
If all pass:
   SpendingLimits.recordSpending()
   PaymentGateway.payNative/payToken()
   ↓
If any fail:
   Reject transaction
   Notify user

Security Features

Access Control

  • Ownable: Admin functions

  • approvedSpenders: Authorized agents

  • ReentrancyGuard: Prevent reentrancy attacks

Input Validation

  • Non-zero addresses

  • Positive amounts

  • Valid limit hierarchies

  • Service existence checks

State Management

  • Payment completion flags

  • Spending trackers

  • Timestamp validations

  • Limit resets

Gas Optimization

Efficient Storage

  • Pack structs to save slots

  • Use uint256 for counters

  • Minimize SLOAD operations

Batch Operations

  • Coming soon: Batch payments

  • Coming soon: Batch limit updates

Upgradeability

Current Status

Contracts are not upgradeable for security.

Future Plans

Consider proxy pattern with:

  • Timelock governance

  • Multi-sig approval

  • Community voting

Testing

Each contract has 30+ tests covering:

  • ✅ Normal operations

  • ✅ Edge cases

  • ✅ Access control

  • ✅ Error handling

  • ✅ Gas optimization

  • ✅ Integration scenarios

See /contracts/test for full test suite.

Deployment

Networks Supported

  • Ethereum Mainnet

  • Polygon

  • Base

  • Arbitrum

  • Optimism

  • Solana (adapted version)

Deployment Process

# Compile contracts
npx hardhat compile

# Run tests
npx hardhat test

# Deploy to testnet
npx hardhat run scripts/deploy.js --network sepolia

# Verify on Etherscan
npx hardhat verify --network sepolia CONTRACT_ADDRESS

Contract Addresses

Mainnet

PaymentGateway: Coming soon
SpendingLimits: Coming soon
X402Registry: Coming soon
Jarvis402Token: Coming soon

Testnet (Sepolia)

PaymentGateway: 0x...
SpendingLimits: 0x...
X402Registry: 0x...
Jarvis402Token: 0x...

Audits

Status

  • ⏳ Security audit in progress

  • Target: Q1 2025

Auditors

  • Trail of Bits (planned)

  • OpenZeppelin (planned)

Source Code

All contracts are open source:

Learn More

Questions? Email [email protected]

PreviousProject StructureNextChat API

Last updated