StyxPay Smart Contracts

Authorization-based onchain banking smart contracts built with Anchor for Solana.

Overview

StyxPay implements three core smart contracts:

1. Vault Program

The vault program manages secure asset storage with programmable spending limits.

Features:

• Initialize user vaults with daily/monthly spending limits
• Deposit and withdraw funds with authorization checks
• Automatic limit resets based on time periods
• Emergency freeze/unfreeze functionality
• Real-time spending tracking

Key Functions:

• initialize_vault - Create a new vault with spending limits
• deposit - Add funds to vault
• withdraw - Withdraw with authorization checks
• update_limits - Modify spending limits
• freeze_vault / unfreeze_vault - Emergency controls

2. Authorization Program

Implements programmable authorization policies for transaction validation.

Features:

• Whitelist/blacklist merchant controls
• Category-based spending restrictions
• Transaction amount limits
• Two-factor authentication requirements
• Real-time transaction validation

Policy Types:

• Whitelist - Only allow specified merchants/categories
• Blacklist - Block specified merchants/categories
• AllowAll - Allow all transactions (with amount/2FA checks)

Key Functions:

• create_policy - Create authorization policy
• update_policy - Modify existing policy
• validate_transaction - Validate transaction against policy
• activate_policy / deactivate_policy - Toggle policy state

3. Card Program

Manages virtual cards linked to vaults for spending.

Features:

• Create unlimited virtual cards per vault
• Per-card spending limits
• Card expiry management
• Freeze/unfreeze individual cards
• Transaction tracking

Key Functions:

• create_card - Create new virtual card
• process_transaction - Process card payment
• update_spending_limit - Modify card limit
• freeze_card / unfreeze_card - Card controls
• deactivate_card - Permanently disable card
• extend_expiry - Extend card expiration

Architecture

┌─────────────────────────────────────────────────────────┐
│                    StyxPay Platform                      │
├─────────────────────────────────────────────────────────┤
│                                                           │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  │
│  │    Vault     │  │Authorization │  │  Virtual     │  │
│  │   Program    │◄─┤   Program    │◄─┤   Card       │  │
│  │              │  │              │  │  Program     │  │
│  └──────────────┘  └──────────────┘  └──────────────┘  │
│         │                  │                  │          │
│         └──────────────────┴──────────────────┘          │
│                         │                                 │
│                    SPL Token                              │
│                                                           │
└─────────────────────────────────────────────────────────┘

Development

Prerequisites

• Rust 1.70+
• Solana CLI 1.16+
• Anchor 0.29+
• Node.js 16+

Build

cd contracts
anchor build

Test

anchor test

Deploy

Localnet:

anchor deploy

Devnet:

anchor deploy --provider.cluster devnet

Mainnet:

anchor deploy --provider.cluster mainnet

Security Features

1. Authorization-Based Withdrawals: All withdrawals require policy validation
2. Spending Limits: Daily and monthly limits enforced on-chain
3. Emergency Controls: Instant freeze functionality
4. Time-Based Resets: Automatic limit resets
5. Granular Permissions: Per-card and per-vault controls
6. Merchant Controls: Whitelist/blacklist support
7. Transaction Validation: Real-time policy enforcement

Program IDs

Localnet/Devnet

• Vault: VauLT1111111111111111111111111111111111111
• Authorization: Auth11111111111111111111111111111111111111
• Card: Card11111111111111111111111111111111111111

Example Usage

Initialize Vault

// Create vault with $5000 daily, $20000 monthly limits
vault::initialize_vault(
    ctx,
    5_000_000_000, // 5000 USDC (6 decimals)
    20_000_000_000, // 20000 USDC
)?;

Create Authorization Policy

// Whitelist policy for specific merchants
authorization::create_policy(
    ctx,
    PolicyType::Whitelist,
    vec!["amazon.com".to_string(), "uber".to_string()],
    vec!["shopping".to_string(), "transport".to_string()],
    1_000_000_000, // Max 1000 USDC per transaction
    true, // Require 2FA
)?;

Create Virtual Card

// Create card with $500 spending limit
card::create_card(
    ctx,
    "My Shopping Card".to_string(),
    500_000_000, // 500 USDC
    expiry_timestamp,
)?;

License

MIT

Contributing

See CONTRIBUTING.md for details.