Authorization Engine

The MPPFi Authorization Engine is a Solana-based policy enforcement system that validates AI agent payments against spending rules before on-chain execution. All policies are deployed as smart contracts, providing cryptographic guarantees and transparent audit trails.

Overview

Key Features

• On-Chain Enforcement: Policies deployed as Solana smart contracts

• Pre-Flight Validation: Check compliance before submitting transactions

• Cryptographic Guarantees: Impossible to bypass without private key

• Real-Time State: Policy limits updated atomically on-chain

• Transparent Auditing: All policy checks recorded on blockchain

• Multi-Signature Support: Threshold-based approvals for high-value payments

Architecture

Policy Lifecycle

1. Policy Configuration (API)
   └─> Define rules (limits, allowlists, timeblocks)

2. Policy Compilation
   └─> Convert rules to Solana program instructions

3. Smart Contract Deployment
   └─> Deploy to Solana blockchain
   └─> Link to agent's Solana address

4. Payment Validation
   └─> Check payment against on-chain policy
   └─> Update spending counters

5. Transaction Execution
   └─> Policy passed → Execute payment
   └─> Policy failed → Reject with reason

Smart Contract Structure

// Simplified Solana policy program structure
#[program]
pub mod mppfi_policy {
    use anchor_lang::prelude::*;

    #[derive(Accounts)]
    pub struct ValidatePayment<'info> {
        #[account(mut)]
        pub policy: Account<'info, PolicyState>,
        pub agent: Signer<'info>,
        pub system_program: Program<'info, System>,
    }

    #[account]
    pub struct PolicyState {
        pub agent_pubkey: Pubkey,
        pub daily_limit: u64,
        pub daily_spent: u64,
        pub last_reset: i64,
        pub merchant_allowlist: Vec<Pubkey>,
        pub requires_multisig_above: u64,
        pub authorized_signers: Vec<Pubkey>,
        pub min_signatures: u8,
    }

    pub fn validate_payment(
        ctx: Context<ValidatePayment>,
        amount: u64,
        destination: Pubkey,
    ) -> Result<()> {
        let policy = &mut ctx.accounts.policy;

        // Check daily limit
        let current_time = Clock::get()?.unix_timestamp;
        if current_time - policy.last_reset > 86400 {
            policy.daily_spent = 0;
            policy.last_reset = current_time;
        }

        require!(
            policy.daily_spent + amount <= policy.daily_limit,
            PolicyError::DailyLimitExceeded
        );

        // Check merchant allowlist
        require!(
            policy.merchant_allowlist.contains(&destination),
            PolicyError::MerchantNotAllowed
        );

        // Update state
        policy.daily_spent += amount;

        Ok(())
    }
}

Policy Rules

1. Amount Limits

Daily/Weekly/Monthly Spending Caps

// Policy state on Solana
{
  daily_limit: 500_000_000, // 500 USDC (6 decimals)
  daily_spent: 123_450_000, // 123.45 USDC spent today
  last_reset: 1705334400,   // Unix timestamp

  weekly_limit: 2_000_000_000,
  weekly_spent: 450_000_000,

  monthly_limit: 7_500_000_000,
  monthly_spent: 1_234_560_000
}

Validation Logic:

pub fn check_amount_limit(
    policy: &mut PolicyState,
    amount: u64,
    current_time: i64,
) -> Result<()> {
    // Reset counters if period expired
    if current_time - policy.daily_reset > SECONDS_IN_DAY {
        policy.daily_spent = 0;
        policy.daily_reset = current_time;
    }

    // Check if payment would exceed limit
    let new_daily_spent = policy.daily_spent
        .checked_add(amount)
        .ok_or(PolicyError::Overflow)?;

    require!(
        new_daily_spent <= policy.daily_limit,
        PolicyError::DailyLimitExceeded
    );

    // Update spent amount
    policy.daily_spent = new_daily_spent;

    Ok(())
}

2. Merchant Allowlists

Restrict payments to approved Solana addresses

#[account]
pub struct MerchantAllowlist {
    pub agent_pubkey: Pubkey,
    pub allowed_merchants: Vec<Pubkey>,  // Max 50 merchants
    pub bump: u8,
}

pub fn validate_merchant(
    allowlist: &MerchantAllowlist,
    destination: &Pubkey,
) -> Result<()> {
    require!(
        allowlist.allowed_merchants.contains(destination),
        PolicyError::MerchantNotAllowed
    );
    Ok(())
}

Adding Merchants:

// Add merchant to allowlist via API
await mppfi.policies.addMerchant('pol_abc123', {
  address: 'GHvFFSZ8dDbN9eDeTe3vPqX7jHhgYFLkLGVrHjG6FH2P',
  name: 'OpenAI API',
  category: 'ai_services'
});

// Smart contract updated on-chain

3. Multi-Signature Approvals

Require multiple signatures for high-value payments

#[account]
pub struct MultiSigApproval {
    pub payment_id: [u8; 32],
    pub amount: u64,
    pub destination: Pubkey,
    pub required_signatures: u8,
    pub received_signatures: Vec<Pubkey>,
    pub expires_at: i64,
    pub status: ApprovalStatus,
}

#[derive(AnchorSerialize, AnchorDeserialize, Clone, PartialEq)]
pub enum ApprovalStatus {
    Pending,
    Approved,
    Rejected,
    Expired,
}

pub fn sign_approval(
    ctx: Context<SignApproval>,
    payment_id: [u8; 32],
) -> Result<()> {
    let approval = &mut ctx.accounts.approval;
    let signer = ctx.accounts.signer.key();

    // Check not expired
    let current_time = Clock::get()?.unix_timestamp;
    require!(
        current_time < approval.expires_at,
        PolicyError::ApprovalExpired
    );

    // Check signer is authorized
    require!(
        ctx.accounts.policy.authorized_signers.contains(&signer),
        PolicyError::UnauthorizedSigner
    );

    // Check not already signed
    require!(
        !approval.received_signatures.contains(&signer),
        PolicyError::AlreadySigned
    );

    // Add signature
    approval.received_signatures.push(signer);

    // Check if threshold met
    if approval.received_signatures.len() >= approval.required_signatures as usize {
        approval.status = ApprovalStatus::Approved;
        // Trigger payment execution
    }

    Ok(())
}

4. Time-Based Restrictions

Control when payments can be made

#[account]
pub struct TimeRestriction {
    pub allowed_days: u8,        // Bitmap: Mon=1, Tue=2, Wed=4, ...
    pub allowed_hours_start: u8, // 0-23
    pub allowed_hours_end: u8,   // 0-23
    pub timezone_offset: i8,     // UTC offset in hours
    pub blackout_periods: Vec<BlackoutPeriod>,
}

#[derive(AnchorSerialize, AnchorDeserialize, Clone)]
pub struct BlackoutPeriod {
    pub start: i64,
    pub end: i64,
    pub reason: String,
}

pub fn check_time_restriction(
    restriction: &TimeRestriction,
    current_time: i64,
) -> Result<()> {
    // Adjust for timezone
    let local_time = current_time + (restriction.timezone_offset as i64 * 3600);

    // Check day of week
    let day_of_week = ((local_time / 86400) % 7) as u8;
    let day_bit = 1 << day_of_week;
    require!(
        restriction.allowed_days & day_bit != 0,
        PolicyError::OutsideAllowedDays
    );

    // Check hour of day
    let hour_of_day = ((local_time % 86400) / 3600) as u8;
    require!(
        hour_of_day >= restriction.allowed_hours_start &&
        hour_of_day < restriction.allowed_hours_end,
        PolicyError::OutsideAllowedHours
    );

    // Check blackout periods
    for blackout in &restriction.blackout_periods {
        require!(
            current_time < blackout.start || current_time > blackout.end,
            PolicyError::InBlackoutPeriod
        );
    }

    Ok(())
}

5. Velocity Limits

Maximum number of transactions per time period

#[account]
pub struct VelocityLimit {
    pub max_transactions_hourly: u16,
    pub max_transactions_daily: u16,
    pub hourly_count: u16,
    pub daily_count: u16,
    pub hourly_reset: i64,
    pub daily_reset: i64,
}

pub fn check_velocity(
    velocity: &mut VelocityLimit,
    current_time: i64,
) -> Result<()> {
    // Reset hourly counter
    if current_time - velocity.hourly_reset > 3600 {
        velocity.hourly_count = 0;
        velocity.hourly_reset = current_time;
    }

    // Reset daily counter
    if current_time - velocity.daily_reset > 86400 {
        velocity.daily_count = 0;
        velocity.daily_reset = current_time;
    }

    // Check limits
    require!(
        velocity.hourly_count < velocity.max_transactions_hourly,
        PolicyError::HourlyVelocityExceeded
    );

    require!(
        velocity.daily_count < velocity.max_transactions_daily,
        PolicyError::DailyVelocityExceeded
    );

    // Increment counters
    velocity.hourly_count += 1;
    velocity.daily_count += 1;

    Ok(())
}

Policy Deployment

Deploying a New Policy

// Step 1: Create policy configuration
const policyConfig = {
  agentId: 'agt_7xK9mN2pQ1',
  rules: [
    {
      type: 'amount_limit',
      period: 'daily',
      limit: { amount: 500.00, currency: 'USDC' }
    },
    {
      type: 'merchant_allowlist',
      addresses: [
        'GHvFFSZ8dDbN9eDeTe3vPqX7jHhgYFLkLGVrHjG6FH2P',
        '8qN5L3kZ9xM2vY7cB4jT6wE1rP9sU5hG3fD8aQ2nK7m'
      ]
    }
  ]
};

// Step 2: Deploy via API
const policy = await mppfi.policies.create(policyConfig);

// Step 3: MPPFi compiles and deploys Solana program
console.log(`Policy deployed at: ${policy.blockchain.contract_address}`);
console.log(`Transaction: ${policy.blockchain.tx_signature}`);

Behind the Scenes:

// MPPFi backend process
async function deployPolicy(policyConfig) {
  // 1. Compile policy rules to Solana program
  const programBytecode = compilePolicyRules(policyConfig.rules);

  // 2. Create program-derived address (PDA)
  const [policyPDA, bump] = await PublicKey.findProgramAddress(
    [
      Buffer.from('policy'),
      new PublicKey(agent.solana_address).toBuffer(),
    ],
    MPPFI_PROGRAM_ID
  );

  // 3. Deploy smart contract
  const tx = await program.methods
    .initializePolicy(policyConfig)
    .accounts({
      policy: policyPDA,
      agent: agent.solana_address,
      payer: MPPFI_TREASURY,
      systemProgram: SystemProgram.programId,
    })
    .rpc();

  // 4. Store policy metadata in database
  await db.policies.create({
    id: generatePolicyId(),
    agent_id: policyConfig.agentId,
    contract_address: policyPDA.toBase58(),
    deployment_tx: tx,
    rules: policyConfig.rules,
  });

  return {
    id: policy.id,
    blockchain: {
      network: 'solana-mainnet',
      contract_address: policyPDA.toBase58(),
      tx_signature: tx,
    }
  };
}

Payment Validation Flow

Pre-Flight Check

// Client-side validation before submitting payment
const validation = await mppfi.payments.validatePolicy({
  agentId: 'agt_7xK9mN2pQ1',
  amount: 250.00,
  currency: 'USDC',
  destination: 'GHvFFSZ8dDbN9eDeTe3vPqX7jHhgYFLkLGVrHjG6FH2P'
});

if (!validation.approved) {
  console.error('Policy violation:', validation.violations);
  // Handle rejection (e.g., show error to user)
  return;
}

// Proceed with payment
const payment = await mppfi.payments.create({...});

On-Chain Validation

// Solana program instruction
pub fn execute_payment(
    ctx: Context<ExecutePayment>,
    amount: u64,
    destination: Pubkey,
) -> Result<()> {
    // 1. Load policy state
    let policy = &mut ctx.accounts.policy;

    // 2. Validate all rules
    check_amount_limit(policy, amount, Clock::get()?.unix_timestamp)?;
    validate_merchant(&policy.merchant_allowlist, &destination)?;
    check_velocity(&mut policy.velocity, Clock::get()?.unix_timestamp)?;
    check_time_restriction(&policy.time_restriction, Clock::get()?.unix_timestamp)?;

    // 3. Check if multi-sig required
    if amount > policy.multisig_threshold {
        // Create approval request
        create_multisig_approval(ctx, amount, destination)?;
        return Ok(());
    }

    // 4. Execute payment (transfer tokens)
    let transfer_ix = spl_token::instruction::transfer(
        &spl_token::id(),
        &ctx.accounts.agent_token_account.key(),
        &destination_token_account.key(),
        &ctx.accounts.agent.key(),
        &[],
        amount,
    )?;

    solana_program::program::invoke(
        &transfer_ix,
        &[
            ctx.accounts.agent_token_account.to_account_info(),
            destination_token_account.to_account_info(),
            ctx.accounts.agent.to_account_info(),
        ],
    )?;

    // 5. Emit event
    emit!(PaymentExecuted {
        agent: ctx.accounts.agent.key(),
        destination,
        amount,
        policy: ctx.accounts.policy.key(),
        timestamp: Clock::get()?.unix_timestamp,
    });

    Ok(())
}

Policy Updates

Updating Policy Rules

from mppfi import Client

client = Client(api_key='sk_live_...')

# Update policy (deploys new smart contract)
updated_policy = client.policies.update(
    policy_id='pol_abc123',
    rules=[
        # New rule
        {
            'type': 'amount_limit',
            'period': 'weekly',
            'limit': {'amount': 2000.00, 'currency': 'USDC'}
        },
        # Existing rules
        *existing_policy.rules
    ]
)

print(f"New contract: {updated_policy.blockchain.contract_address}")
print(f"Old contract deprecated: {existing_policy.blockchain.contract_address}")

Version Control:

• Old policy contracts remain on-chain for audit

• New payments use latest policy version

• Historical transactions reference their policy version

• Grace period: 5 minutes before old policy disabled

Error Handling

Policy Violation Errors

#[error_code]
pub enum PolicyError {
    #[msg("Daily spending limit exceeded")]
    DailyLimitExceeded,

    #[msg("Weekly spending limit exceeded")]
    WeeklyLimitExceeded,

    #[msg("Monthly spending limit exceeded")]
    MonthlyLimitExceeded,

    #[msg("Merchant not in allowlist")]
    MerchantNotAllowed,

    #[msg("Payment requires multi-signature approval")]
    MultiSigRequired,

    #[msg("Outside allowed hours")]
    OutsideAllowedHours,

    #[msg("Outside allowed days")]
    OutsideAllowedDays,

    #[msg("In blackout period")]
    InBlackoutPeriod,

    #[msg("Hourly transaction velocity exceeded")]
    HourlyVelocityExceeded,

    #[msg("Daily transaction velocity exceeded")]
    DailyVelocityExceeded,

    #[msg("Insufficient balance")]
    InsufficientBalance,

    #[msg("Approval expired")]
    ApprovalExpired,

    #[msg("Unauthorized signer")]
    UnauthorizedSigner,
}

Client-Side Error Handling

try {
  const payment = await mppfi.payments.create({
    agentId: 'agt_7xK9mN2pQ1',
    amount: 600.00,
    currency: 'USDC',
    destination: 'GHvFFSZ8dDbN9eDeTe3vPqX7jHhgYFLkLGVrHjG6FH2P'
  });
} catch (error) {
  if (error.code === 'policy_violation') {
    const violation = error.details;

    switch (violation.error_code) {
      case 'DailyLimitExceeded':
        console.log(`Daily limit: ${violation.limit}`);
        console.log(`Already spent: ${violation.current}`);
        console.log(`Requested: ${violation.requested}`);
        console.log(`Available: ${violation.available}`);
        break;

      case 'MerchantNotAllowed':
        console.log(`Merchant ${violation.destination} not in allowlist`);
        break;

      case 'MultiSigRequired':
        console.log(`Amount exceeds threshold, approval required`);
        console.log(`Approval ID: ${violation.approval_id}`);
        break;
    }
  }
}

Performance Optimization

State Compression

For agents with many transactions, use Solana's state compression:

// Use Merkle tree for transaction history
#[account]
pub struct CompressedPolicyState {
    pub agent_pubkey: Pubkey,
    pub daily_limit: u64,
    pub daily_spent: u64,
    pub merkle_tree: Pubkey, // Points to compressed transaction log
}

// Transactions stored in Merkle tree (lower cost)
// Only leaf hashes stored on-chain
// Full transaction data in Arweave/Shadow Drive

Benefits:

• 10x reduction in on-chain storage costs

• Same security guarantees

• Verifiable transaction history

Batch Updates

Update multiple policy counters in single transaction:

pub fn batch_update_policies(
    ctx: Context<BatchUpdate>,
    updates: Vec<PolicyUpdate>,
) -> Result<()> {
    for update in updates {
        let policy = &mut ctx.accounts.policies[update.index];
        policy.daily_spent += update.amount;
    }
    Ok(())
}

Monitoring & Analytics

Policy Metrics

Track policy effectiveness via on-chain events:

// Listen for policy events
mppfi.policies.onEvent('pol_abc123', (event) => {
  switch (event.type) {
    case 'policy.validation.passed':
      metrics.increment('policy.passed');
      break;
    case 'policy.validation.failed':
      metrics.increment('policy.failed', {
        reason: event.violation.error_code
      });
      break;
    case 'policy.approval.required':
      metrics.increment('policy.approval_required');
      break;
  }
});

Audit Reports

Generate compliance reports from on-chain data:

report = client.policies.generate_audit_report(
    policy_id='pol_abc123',
    start_date='2025-01-01',
    end_date='2025-01-31'
)

print(f"Total transactions: {report.total_transactions}")
print(f"Approved: {report.approved_count}")
print(f"Blocked: {report.blocked_count}")
print(f"Pending approval: {report.pending_approval_count}")
print(f"Compliance rate: {report.compliance_rate}%")

# Download PDF
pdf = client.policies.download_audit_report(report.id, format='pdf')

Next Steps

• Implement Spending Policies for your agents

• Review Architecture for system design

• Explore API Reference for policy endpoints

• Check Quickstart for examples