Protocol

Reviewing the core modules to understand their purpose and architecture.

[6 tools called]

1. ModuleRegistry.sol Purpose

Purpose: Central service registry for module discovery and versioning.

Current Implementation:

• Maps bytes32 moduleId → address moduleAddress

• Owner-controlled registration (one-time, immutable)

• Version query via getModuleVersion() calling module's getVersion()

Problems:

• No update mechanism (can't replace modules)

• No version history tracking

• No dependency management

• Silent failures if module not registered

---

2. Versioning Management Spec

2.1 Directory Structure

contracts/
├── XFT/                          # Active contracts (v2+)
│   ├── core/
│   │   ├── MoneyMarketFund.sol
│   ├── modules/
│   │   ├── AuthorizationModule.sol
│   │   ├── TransactionalModule.sol
│   │   ├── TransferAgentModule.sol
│   ├── infrastructure/
│   │   ├── ModuleRegistry.sol
│   │   ├── TokenRegistry.sol
│   └── interfaces/
│
└── archive/                      # Archived contracts
    └── v1/                       # Version 1 (current contracts/XFT/)
        ├── MoneyMarketFund.sol
        ├── infrastructure/
        │   ├── modules/
        │   │   └── upgrade_history/
        │   │       ├── authorization/
        │   │       ├── transactional/
        │   │       └── transfer_agent/
        └── README.md             # Migration notes, deprecation date

2.2 Versioning Strategy

Semantic Versioning:

• Major (v1, v2): Breaking changes, new architecture

• Minor (v1.1, v1.2): New features, backward compatible

• Patch (v1.1.1): Bug fixes only

Archive Process:

1. Create archive/v{N}/ directory

2. Move entire contracts/XFT/ → archive/v{N}/

3. Add archive/v{N}/README.md with:

   • Deprecation date

   • Migration guide

   • Known issues

   • Deployment addresses (if on-chain)

4. Update contracts/XFT/ with new version

5. Tag git commit: v{N}-archive

Module Version Tracking:

// In ModuleRegistry
struct ModuleInfo {
    address currentAddress;
    uint8 currentVersion;
    address[] versionHistory;  // All deployed versions
    uint256 deployedAt;
    bool deprecated;
}

mapping(bytes32 => ModuleInfo) public moduleInfo;

---

3. Archive Migration Script

Proposed structure:

# Archive current contracts/XFT/ to archive/v1/
archive/
└── v1/
    ├── contracts/
    │   └── XFT/
    │       ├── MoneyMarketFund.sol
    │       ├── infrastructure/
    │       │   ├── ModuleRegistry.sol
    │       │   ├── TokenRegistry.sol
    │       │   └── modules/
    │       │       ├── BaseUpgradeableModule.sol
    │       │       └── upgrade_history/
    │       └── interfaces/
    ├── deployments/
    │   └── arbitrum_sepolia.json  # Copy deployment addresses
    └── README.md
        # Version: 1.0.0
        # Deprecated: 2025-01-XX
        # Last deployed: arbitrum_sepolia:0x...
        # Migration notes: See contracts/XFT/README.md

---

4. Core Module Functionality Specs

4.1 ModuleRegistry

Purpose: Service discovery and version management

Core Functions:

interface IModuleRegistry {
    // Registration
    function registerModule(bytes32 id, address addr) external;
    function updateModule(bytes32 id, address newAddr) external; // NEW
    function deprecateModule(bytes32 id) external; // NEW
    
    // Discovery
    function getModuleAddress(bytes32 id) external view returns (address);
    function getModuleVersion(bytes32 id) external view returns (uint8);
    function isModuleRegistered(bytes32 id) external view returns (bool);
    
    // Version history
    function getModuleHistory(bytes32 id) external view returns (address[] memory);
}

Use Cases:

• Module discovery: TransactionalModule finds AuthorizationModule

• Version checking: Ensure compatible module versions

• Upgrade coordination: Track module upgrades

---

4.2 AuthorizationModule

Purpose: Account whitelisting and role management

Core Functions:

interface IAuthorization {
    // Account Management
    function authorizeAccount(address account) external;
    function deauthorizeAccount(address account) external;
    function isAccountAuthorized(address account) external view returns (bool);
    
    // Admin Management
    function isAdminAccount(address account) external view returns (bool);
    
    // Role Management
    function grantRole(bytes32 role, address account) external;
    function revokeRole(bytes32 role, address account) external;
    
    // Account Status
    function freezeAccount(address account, string memory memo) external;
    function unfreezeAccount(address account) external;
    function isAccountFrozen(address account) external view returns (bool);
}

Use Cases:

• KYC/whitelisting: Only authorized accounts can transact

• Admin control: Fund admins can settle transactions

• Account freezing: Suspend compromised accounts

• Role-based access: Different permissions for different roles

Dependencies:

• ModuleRegistry (to find TransactionalModule for pending tx checks)

• TokenRegistry (to get token address for balance checks)

---

4.3 TransactionalModule

Purpose: Transaction request storage and lifecycle management

Core Functions:

interface ITransactionalModule {
    // Self-Service (User-initiated)
    function requestSelfServiceCashPurchase(uint256 amount) external;
    function requestSelfServiceCashLiquidation(uint256 amount) external;
    function cancelSelfServiceRequest(bytes32 txId, string memory memo) external;
    
    // Admin-initiated
    function requestCashPurchase(address account, uint256 date, uint256 amount) external;
    function requestCashLiquidation(address account, uint256 date, uint256 amount) external;
    
    // Query
    function getAccountTransactions(address account) external view returns (bytes32[] memory);
    function getTransactionDetail(bytes32 txId) external view returns (TransactionDetail memory);
    function hasTransactions(address account) external view returns (bool);
    
    // Admin
    function enableSelfService() external;
    function disableSelfService() external;
}

Use Cases:

• Transaction queuing: Store buy/sell requests before settlement

• Self-service: Allow users to create their own requests

• Transaction lifecycle: Track pending → settled → cancelled

• Batch operations: Support end-of-day settlement

Dependencies:

• ModuleRegistry (to find AuthorizationModule for access checks)

• TokenRegistry (to get token address for holdings checks)

---

4.4 TransferAgentModule

Purpose: Transaction settlement and share minting/burning

Core Functions:

interface ITransferAgent {
    // Settlement
    function settleTransactions(address[] calldata accounts, bytes32[] calldata txIds, uint256 date, uint256 price) external;
    function endOfDay(address[] calldata accounts, bytes32[] calldata txIds, uint256 date, int256 rate, uint256 price) external;
    
    // Dividends
    function distributeDividends(address[] calldata accounts, uint256 date, int256 rate, uint256 price) external;
    
    // Admin Operations
    function adjustBalance(address account, uint256 currentBalance, uint256 newBalance, string memory memo) external;
    function recoverAccount(address from, address to, string memory memo) external;
}

Use Cases:

• Settlement: Convert pending transactions to share mints/burns

• Dividend distribution: Calculate and distribute dividends

• End-of-day processing: Batch settlement + dividends

• Account recovery: Recover funds from compromised accounts

Dependencies:

• ModuleRegistry (to find AuthorizationModule, TransactionalModule)

• TokenRegistry (to get token address)

• MoneyMarketFund (to mint/burn shares)

---

5. Redesigned Architecture

5.1 Problems with Current Design

1. Deep nesting: contracts/XFT/infrastructure/modules/upgrade_history/...

2. Unclear dependencies: Modules don't initialize properly

3. No dependency injection: Hard-coded registry lookups

4. Version confusion: _V3, _V5 suffixes mixed with upgrade_history/

5. Circular dependencies: Modules depend on each other via ModuleRegistry

5.2 Proposed Architecture

contracts/
└── XFT/
    ├── core/
    │   ├── MoneyMarketFund.sol          # ERC20 token (no module dependencies)
    │   └── FundToken.sol                 # Base token interface
    │
    ├── modules/
    │   ├── BaseModule.sol                # Base with proper initialization
    │   │
    │   ├── AuthorizationModule.sol       # Account management
    │   ├── TransactionalModule.sol       # Transaction storage
    │   ├── TransferAgentModule.sol       # Settlement engine
    │   │
    │   └── interfaces/
    │       ├── IAuthorization.sol
    │       ├── ITransactional.sol
    │       └── ITransferAgent.sol
    │
    ├── registry/
    │   ├── ModuleRegistry.sol            # Service discovery (enhanced)
    │   └── TokenRegistry.sol            # Token address mapping
    │
    └── interfaces/
        └── IFundToken.sol

5.3 Key Design Changes

1. Flattened Structure

• Remove infrastructure/ nesting

• Remove upgrade_history/ (use git tags instead)

• Clear separation: core/, modules/, registry/

2. Explicit Dependencies

// BaseModule.sol - Proper initialization
abstract contract BaseModule {
    ModuleRegistry public immutable moduleRegistry;
    TokenRegistry public immutable tokenRegistry;
    
    constructor(address _moduleRegistry, address _tokenRegistry) {
        require(_moduleRegistry != address(0), "INVALID_REGISTRY");
        moduleRegistry = ModuleRegistry(_moduleRegistry);
        tokenRegistry = TokenRegistry(_tokenRegistry);
    }
    
    // Helper to get other modules
    function getAuthorizationModule() internal view returns (IAuthorization) {
        return IAuthorization(moduleRegistry.getModuleAddress(MODULE_AUTHORIZATION));
    }
}

3. Initialization Pattern

// TransactionalModule.sol
contract TransactionalModule is BaseModule {
    function initialize(
        address moduleRegistry,
        address tokenRegistry,
        string memory tokenId,
        address admin
    ) public initializer {
        __BaseModule_init(moduleRegistry, tokenRegistry);
        __AccessControl_init();
        // ... rest of init
    }
}

4. Enhanced ModuleRegistry

contract ModuleRegistry {
    struct ModuleMetadata {
        address currentAddress;
        uint8 version;
        bool deprecated;
        uint256 registeredAt;
    }
    
    mapping(bytes32 => ModuleMetadata) public modules;
    mapping(bytes32 => address[]) public versionHistory;
    
    function registerModule(bytes32 id, address addr) external onlyOwner {
        require(modules[id].currentAddress == address(0), "ALREADY_REGISTERED");
        modules[id] = ModuleMetadata({
            currentAddress: addr,
            version: BaseModule(addr).getVersion(),
            deprecated: false,
            registeredAt: block.timestamp
        });
        versionHistory[id].push(addr);
    }
    
    function updateModule(bytes32 id, address newAddr) external onlyOwner {
        require(modules[id].currentAddress != address(0), "NOT_REGISTERED");
        modules[id].deprecated = true;
        modules[id].currentAddress = newAddr;
        modules[id].version = BaseModule(newAddr).getVersion();
        versionHistory[id].push(newAddr);
    }
}

5. Dependency Graph

MoneyMarketFund (core)
    ↑
    ├── TransferAgentModule (mints/burns shares)
    │   ├── depends on: ModuleRegistry
    │   ├── depends on: TokenRegistry
    │   └── depends on: AuthorizationModule (via ModuleRegistry)
    │
    ├── TransactionalModule (stores transactions)
    │   ├── depends on: ModuleRegistry
    │   ├── depends on: TokenRegistry
    │   └── depends on: AuthorizationModule (via ModuleRegistry)
    │
    └── AuthorizationModule (manages accounts)
        ├── depends on: ModuleRegistry
        └── depends on: TokenRegistry

5.4 Migration Checklist

• Create archive/v1/ directory

• Move contracts/XFT/ → archive/v1/contracts/XFT/

• Copy deployments/ → archive/v1/deployments/

• Create archive/v1/README.md with deprecation notes

• Create new contracts/XFT/ with flat structure

• Implement enhanced ModuleRegistry with version tracking

• Refactor modules to use explicit dependency injection

• Update deployment scripts for new structure

• Tag git: v1-archive and v2.0.0

This design improves clarity, maintainability, and upgradeability while preserving core functionality.