Authorized Token

Overview

This project implements an authorized token system on Solana. The access-control program is based on the solana-security-token implementation from CoMakery/solana-security-token.

Features

• Secured token transfers
• Role-based access control
• Customizable transfer restrictions
• Merchant payment processing
• Transfer hook validation

Architecture

The system consists of three main Solana programs that work together:

1. Access Control Program (access_control) - Manages roles and permissions
2. Authorized Token Program (authorized_token) - Handles token transfer validation via SPL Token 2022 transfer hooks
3. Payment System Program (payment_system) - Processes merchant payments

How It Works

Authorized Token Flow

The Authorized Token system uses the SPL Token 2022 transfer hook feature to validate and control token transfers. Here's how it works:

1. Account Initialization:

   • Merchants are initialized with initialize_merchant instruction
   • Authorized accounts are initialized with initialize_authorized_account instruction
   • Both include status flags, spending limits, and permissions

2. Transfer Hook Registration:

   • Extra account meta lists are initialized for the token mint
   • When transfers occur, these accounts are automatically included in the transaction

3. Transfer Validation:

   • When a token transfer is attempted, the execute_transfer_hook function is called
   • The hook validates that both source and destination accounts meet requirements:
     • Checks the authorized account is active
     • Verifies the merchant account status
     • Enforces any spending limits or restrictions

Payment Processing

The Payment System program handles merchant transactions:

1. Purchase Flow:

   • Client calls purchase with the amount to be transferred
   • Transaction includes merchant and authorized account details
   • Uses invoke_transfer_checked to execute the token transfer
   • The transfer hook validates the transaction before it completes

2. Validation Process:

   • Transaction must be signed by both merchant and authorized account
   • Transfer hook validates account status and permissions
   • Transfer only succeeds if all validations pass

Program Interaction Example

Based on the test flow, here's how the programs interact:

1. Initialize merchant and authorized accounts with the Authorized Token program
2. Fund the authorized account with tokens
3. Create a purchase instruction from the Payment System program
4. Add extra account metas for the token transfer hook
5. Execute the transaction with signatures from both merchant and authorized account
6. Token transfer succeeds if all validations pass in the transfer hook

Program Details

Access Control Program

The Access Control Program manages user roles and permissions within the token ecosystem:

• Key Features:

  • Role-based access control system
  • Wallet freezing/thawing capabilities
  • Administrative forced transfers between accounts
  • Security token minting and burning

• Main Functions:

  • initialize_access_control: Sets up the access control system
  • initialize_wallet_role: Assigns roles to wallets (0-255)
  • update_wallet_role: Changes a wallet's role
  • freeze_wallet/thaw_wallet: Controls account usage
  • force_transfer_between: Administrative transfer between accounts
  • mint_securities/burn_securities: Manages token supply

• Security Model:

  • Hierarchical permission structure
  • Only authorized admins can modify roles
  • Transaction approval based on role permissions

Authorized Token Program

The Authorized Token Program implements transfer validation logic using SPL Token 2022 transfer hooks:

• Key Components:

  • AuthorizedAccount: Tracks user permissions, spending limits, and transaction history
  • MerchantAccount: Manages merchant permissions and transaction limits
  • Transfer hook validation logic

• Account Statuses:

  • Active: Account can participate in transactions
  • Paused: Temporary suspension
  • Sanctioned: Permanently blocked

• Spending Controls:

  • Daily and monthly purchase limits
  • Maximum transaction amounts
  • Tracked spending history with timestamp verification

• Validation Checks:

  • Account status verification
  • Transaction amount validation
  • Spending limit enforcement
  • Merchant authorization

Payment System Program

The Payment System Program facilitates transactions between merchants and authorized accounts:

• Main Operations:

  • purchase: Transfers tokens from customer to merchant
  • refund: Returns tokens from merchant to customer

• Transaction Flow:

  • Client initiates transaction with merchant
  • Both parties sign the transaction
  • Payment amount is validated against limits
  • Token transfer executed with transfer hook validation
  • Transaction succeeds only if all validations pass

• Security Features:

  • Multi-signature requirement
  • Integration with Authorized Token validation
  • Automated spending limit enforcement