ERC-1450: RTA-Controlled Security Token

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;

interface IERC20 {
    function totalSupply() external view returns (uint256);
    function balanceOf(address account) external view returns (uint256);
    function transfer(address to, uint256 amount) external returns (bool);
    function allowance(address owner, address spender) external view returns (uint256);
    function transferFrom(address from, address to, uint256 amount) external returns (bool);
    function approve(address spender, uint256 amount) external returns (bool);

    event Transfer(address indexed from, address indexed to, uint256 value);
    event Approval(address indexed owner, address indexed spender, uint256 value);
}

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;

interface IERC165 {
    /**
     * @notice Query if a contract implements an interface
     * @param interfaceId The interface identifier, as specified in [ERC-165](/EIPS/eip-165)
     * @return bool True if the contract implements `interfaceId`
     */
    function supportsInterface(bytes4 interfaceId) external view returns (bool);
}

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;

/**
 * @title ERC-1450: RTA-Controlled Security Token (Restricted ERC-20 Interface)
 * @notice Facilitates compliance with Securities Act Regulations CF, D, and A
 * @dev This standard extends ERC-20 with RTA-controlled transfer restrictions
 *
 * Key Features:
 * - RTA (Registered Transfer Agent) exclusive control over transfers
 * - Direct value movement disabled (transfer, approve functions always revert)
 * - Holder-initiated transfer requests permitted via requestTransferWithFee (requires RTA execution)
 * - Built-in recovery mechanisms for lost tokens
 * - Support for court-ordered transfers
 * - Restricted ERC-20 interface for read operations and ecosystem integration
 * - ERC-6093 compliant error messages for tooling interoperability
 */
interface IERC1450 is IERC20, IERC165 {
    // ============ ERC-6093 Standard Errors ============
    // Using standard errors from ERC-6093 for consistent tooling support

    // Standard ERC-20 errors (from ERC-6093)
    error ERC20InsufficientBalance(address sender, uint256 balance, uint256 needed);
    error ERC20InvalidSender(address sender);
    error ERC20InvalidReceiver(address receiver);
    error ERC20InvalidApprover(address approver);
    error ERC20InvalidSpender(address spender);
    error ERC20InsufficientAllowance(address spender, uint256 allowance, uint256 needed);

    // Standard Access Control errors (from ERC-6093)
    // NOTE: We retain OpenZeppelin error names for tooling compatibility, but semantics differ:
    // - "Owner" in ERC-1450 means "Issuer" (the entity that created the token)
    // - Unlike OpenZeppelin's Ownable, only the RTA can change the issuer, not the issuer themselves
    error OwnableUnauthorizedAccount(address account);  // Non-issuer attempts issuer-only operation
    error OwnableInvalidOwner(address owner);  // Invalid issuer address (e.g., zero address)

    // ============ ERC-1450 Specific Errors ============
    // Custom errors only when ERC-6093 standard errors are insufficient

    error ERC1450TransferDisabled();  // For disabled transfer/approve functions
    error ERC1450OnlyRTA();  // Operation restricted to RTA only
    error ERC1450TransferAgentLocked();  // RTA proxy is locked from changes
    error ERC1450ComplianceCheckFailed(address from, address to);  // KYC/AML failure

    // Events
    event IssuerChanged(address indexed previousIssuer, address indexed newIssuer);
    event TransferAgentUpdated(address indexed previousAgent, address indexed newAgent);

    /**
     * @notice Emitted when tokens are minted with regulation tracking
     * @param to Recipient of the minted tokens
     * @param amount Number of tokens minted
     * @param regulationType Regulation under which tokens were issued
     * @param issuanceDate Original share issuance date
     * @param tokenizationDate When tokenized on blockchain (block.timestamp)
     * @dev MUST be emitted for every mint operation
     *      Allows reconstruction of entire cap table from events
     *      Critical for regulatory reporting and audit trails
     */
    event TokensMinted(
        address indexed to,
        uint256 amount,
        uint16 indexed regulationType,
        uint256 issuanceDate,
        uint256 tokenizationDate
    );

    /**
     * @notice Emitted when tokens are burned with regulation tracking
     * @param from Address from which tokens were burned
     * @param amount Number of tokens burned
     * @param regulationType Regulation type of burned tokens
     * @param issuanceDate Original issuance date of burned tokens
     * @dev MUST be emitted for every burn operation
     *      Critical for maintaining accurate cap table and regulatory reporting
     */
    event TokensBurned(
        address indexed from,
        uint256 amount,
        uint16 indexed regulationType,
        uint256 issuanceDate
    );

    /**
     * @notice Emitted when tokens are transferred with specific regulation tracking
     * @param from Source address
     * @param to Destination address
     * @param amount Number of tokens transferred
     * @param regulationType Regulation type of the transferred tokens
     * @param issuanceDate Original issuance date of the transferred tokens
     * @dev Provides complete traceability of regulated token movements
     *      Essential for compliance reporting and audit trails
     */
    event RegulatedTransfer(
        address indexed from,
        address indexed to,
        uint256 amount,
        uint16 indexed regulationType,
        uint256 issuanceDate
    );

    // Core RTA Functions

    /**
     * @notice Change the issuer (owner) of the token contract
     * @param newIssuer Address of the new issuer
     * @dev Only callable by the RTA. Must be restricted with onlyTransferAgent modifier.
     *      Emits IssuerChanged event (not OwnershipTransferred)
     *
     *      IMPORTANT: This differs from OpenZeppelin's Ownable pattern:
     *      - In Ownable: owner can transfer ownership themselves
     *      - In ERC-1450: ONLY the RTA can change the issuer
     *      - Terminology: "Issuer" = the token creator/owner, not the controller
     *      - This prevents compromised issuer keys from hijacking the token
     *
     *      The issuer maintains rights to:
     *      - Receive proceeds from offerings
     *      - Update corporate documents (via ERC-1643)
     *      - Make business decisions
     *      But CANNOT control token transfers or change the RTA
     */
    function changeIssuer(address newIssuer) external;

    /**
     * @notice Update the transfer agent address (one-time use or RTA-only after initial setup)
     * @param newTransferAgent Address of the new transfer agent (should be RTAProxy contract)
     * @dev After initial setup to RTAProxy, only the RTA can rotate itself via the proxy.
     *      This prevents compromised issuers from changing the RTA.
     */
    function setTransferAgent(address newTransferAgent) external;

    /**
     * @notice Check if an address is the current transfer agent
     * @param account Address to check
     * @return bool True if the address is the current transfer agent
     */
    function isTransferAgent(address account) external view returns (bool);

    // ERC-20 Overrides (Restricted Functions)

    /**
     * @notice Transfer tokens - DISABLED for security tokens
     * @dev Must always revert with ERC1450TransferDisabled()
     *      Uses specific error for disabled functionality per [ERC-6093](/EIPS/eip-6093) guidelines
     */
    function transfer(address to, uint256 amount) external override returns (bool);

    /**
     * @notice Approve spending - DISABLED for security tokens
     * @dev Must always revert with ERC1450TransferDisabled()
     *      Uses specific error for disabled functionality per [ERC-6093](/EIPS/eip-6093) guidelines
     */
    function approve(address spender, uint256 amount) external override returns (bool);

    /**
     * @notice Get spending allowance - DISABLED for security tokens
     * @dev Must always return 0
     */
    function allowance(address owner, address spender) external view override returns (uint256);

    /**
     * @notice Transfer tokens - DISABLED for security tokens
     * @dev Must always revert with ERC1450TransferDisabled()
     *      Uses specific error for disabled functionality per [ERC-6093](/EIPS/eip-6093) guidelines
     *      Use transferFromRegulated() for actual transfers with regulation tracking
     */
    function transferFrom(address from, address to, uint256 amount) external override returns (bool);

    // RTA-Controlled Functions

    /**
     * @notice Transfer tokens between accounts with regulation tracking (RTA only)
     * @param from Source address
     * @param to Destination address
     * @param amount Number of tokens to transfer
     * @param regulationType Type of regulation for the transferred tokens
     * @param issuanceDate Original issuance date of the transferred tokens
     * @dev Only callable by the registered transfer agent
     *      The regulation type and issuance date specify which tokens to transfer
     *      MUST revert if sender has insufficient tokens of the specified regulation/issuance
     *      Callers SHOULD first check holdings via getHolderRegulations() or getDetailedBatchInfo()
     *      This enables precise control over which token batches are moved
     *      The RTA determines the transfer strategy (FIFO, LIFO, tax optimization, etc.)
     */
    function transferFromRegulated(address from, address to, uint256 amount, uint16 regulationType, uint256 issuanceDate) external returns (bool);

    /**
     * @notice Mint new tokens with regulation tracking (RTA only)
     * @param to Address to receive the minted tokens
     * @param amount Number of tokens to mint
     * @param regulationType Type of regulation under which shares were issued (uint16 for global compatibility)
     * @param issuanceDate Unix timestamp when shares were originally issued (not tokenization date)
     * @dev Only callable by the registered transfer agent
     *      Every security MUST specify a regulation type - there are no "unregulated" securities
     *      For tokenizing existing securities, issuanceDate should be when investor originally purchased
     *      For new issuances, issuanceDate would typically be block.timestamp
     *      RTA uses issuanceDate to calculate holding periods for regulatory compliance
     */
    function mint(address to, uint256 amount, uint16 regulationType, uint256 issuanceDate) external returns (bool);

    /**
     * @notice Batch mint tokens with regulation tracking (RTA only)
     * @param recipients Array of addresses to receive the minted tokens
     * @param amounts Array of token amounts to mint for each recipient
     * @param regulationTypes Array of regulation types for each mint
     * @param issuanceDates Array of issuance timestamps for each mint
     * @dev Only callable by the registered transfer agent
     *      All arrays MUST be the same length
     *      Each mint operation follows the same rules as individual mint()
     *      Reverts if any single mint would fail
     *      Emits TokensMinted event for each successful mint
     *      Enables efficient bulk issuance while maintaining compliance tracking
     */
    function batchMint(
        address[] calldata recipients,
        uint256[] calldata amounts,
        uint16[] calldata regulationTypes,
        uint256[] calldata issuanceDates
    ) external returns (bool);

    /**
     * @notice Burn tokens from an account (RTA only) - Uses RTA's chosen strategy
     * @param from Address from which to burn tokens
     * @param amount Number of tokens to burn
     * @dev Only callable by the registered transfer agent
     *      The RTA determines which tokens to burn based on their strategy (FIFO, LIFO, tax optimization, etc.)
     *      Use burnFromRegulated() to burn specific regulation/issuance tokens
     */
    function burnFrom(address from, uint256 amount) external returns (bool);

    /**
     * @notice Burn tokens from an account with regulation tracking (RTA only)
     * @param from Address from which to burn tokens
     * @param amount Number of tokens to burn
     * @param regulationType Type of regulation for the tokens to burn
     * @param issuanceDate Original issuance date of the tokens to burn
     * @dev Only callable by the registered transfer agent
     *      Burns specific tokens identified by regulation type and issuance date
     *      MUST revert if holder has insufficient tokens of the specified regulation/issuance
     *      Callers SHOULD first check holdings via getHolderRegulations() or getDetailedBatchInfo()
     *      MUST emit TokensBurned event with the specific regulation details
     */
    function burnFromRegulated(address from, uint256 amount, uint16 regulationType, uint256 issuanceDate) external returns (bool);

    /**
     * @notice Burn tokens of a specific regulation type (RTA only)
     * @param from Address from which to burn tokens
     * @param amount Number of tokens to burn
     * @param regulationType Specific regulation type to burn
     * @dev Only callable by the registered transfer agent
     *      Useful for partial redemptions, buybacks, or regulation-specific corporate actions
     *      Reverts if holder has insufficient tokens of the specified regulation type
     *      MUST emit TokensBurned event with the specific regulation details
     */
    function burnFromRegulation(address from, uint256 amount, uint16 regulationType) external returns (bool);

    /**
     * @notice Get token decimals (OPTIONAL per [EIP-20](/EIPS/eip-20))
     * @return uint8 The number of decimal places (0-18)
     * @dev Set at deployment based on security type:
     *      - 0 for traditional indivisible shares
     *      - Greater than 0 for fractional shares (mutual funds, REITs, fractional trading)
     *      - Must be immutable after deployment
     *
     *      NOTE: Per [EIP-20](/EIPS/eip-20), name(), symbol(), and decimals() are OPTIONAL
     *      Implementations SHOULD provide these for better UX
     *      Wallets MUST NOT assume these functions exist
     */
    function decimals() external view returns (uint8);

    // Introspection for Restricted ERC-20 Interface Detection

    /**
     * @notice Check if this is a security token with restricted transfers
     * @return bool Always returns true for ERC-1450 tokens
     * @dev Critical for wallets/DEXs to detect restricted tokens and handle appropriately.
     *      Prevents users from attempting transfers that will always fail.
     */
    function isSecurityToken() external pure returns (bool);

    /**
     * @notice Returns the contract implementation version
     * @return string Semantic version string (e.g., "1.17.0")
     * @dev Enables upgrade detection for UUPS-upgradeable contracts.
     *      Version SHOULD match the reference implementation package version.
     *      Useful for:
     *      - Detecting available upgrades by comparing deployed vs local version
     *      - Audit trails showing which version was deployed
     *      - Debugging and support by identifying exact implementation
     */
    function version() external pure returns (string memory);

    /**
     * @notice [EIP-165](/EIPS/eip-165) support for interface detection
     * @param interfaceId The interface identifier to check
     * @return bool True if the contract implements the interface
     * @dev MUST return true for:
     *      - 0x01ffc9a7: [ERC-165](/EIPS/eip-165) interface ID
     *      - 0xXXXXXXXX: IERC1450 interface ID (see Interface Detection section for calculation)
     *
     *      MUST return false for:
     *      - 0x36372b07: [ERC-20](/EIPS/eip-20) interface ID
     *
     *      Returning false for [ERC-20](/EIPS/eip-20) prevents wallets from assuming standard transfer behavior.
     *      While we are ABI-compatible with [ERC-20](/EIPS/eip-20), we are not behaviorally compatible
     *      since transfer() and approve() always revert.
     */
    function supportsInterface(bytes4 interfaceId) external view returns (bool);

    // KYC/AML Status Check (OPTIONAL)

    /**
     * @notice Check if an address has been KYC verified (OPTIONAL)
     * @param account Address to check
     * @return verified Whether the address is linked to a verified person
     * @return expiryDate When the KYC verification expires (0 if not verified)
     * @dev This is a view function that queries the RTA's off-chain database
     *      Never returns actual identity information, only verification status
     *      Implementations MAY choose to implement this for transparency
     *      Returns false for addresses that have never been verified
     */
    function isKYCVerified(address account) external view returns (bool verified, uint256 expiryDate);

    // Regulation Tracking Query Functions

    /**
     * @notice Get regulation information for tokens held by an address
     * @param holder Address to query
     * @return regulationTypes Array of regulation types for holder's tokens
     * @return amounts Array of token amounts per regulation type
     * @return issuanceDates Array of original issuance dates
     * @dev MUST return arrays of equal length representing holder's token composition
     *      Implementation MUST store this data persistently on-chain
     *      RTA uses this for transfer calculations and compliance checks
     */
    function getHolderRegulations(address holder) external view returns (
        uint16[] memory regulationTypes,
        uint256[] memory amounts,
        uint256[] memory issuanceDates
    );

    /**
     * @notice Get total tokens minted under a specific regulation
     * @param regulationType The regulation type to query
     * @return totalSupply Total tokens minted under this regulation
     * @dev Useful for regulatory reporting and tracking offering limits
     */
    function getRegulationSupply(uint16 regulationType) external view returns (uint256 totalSupply);

    /**
     * @notice Get detailed batch information for a holder's tokens
     * @param holder Address to query
     * @return count Number of unique batches the holder has
     * @return regulationTypes Array of regulation types for each batch
     * @return issuanceDates Array of issuance dates for each batch
     * @return amounts Array of token amounts for each batch
     * @dev Returns comprehensive batch-level details for a holder
     *      Useful for detailed cap table management and regulatory reporting
     *      Each index represents a unique batch of tokens with specific regulation/issuance
     */
    function getDetailedBatchInfo(address holder) external view returns (
        uint256 count,
        uint16[] memory regulationTypes,
        uint256[] memory issuanceDates,
        uint256[] memory amounts
    );

    // Batch Operations for Gas Efficiency

    /**
     * @notice Batch transfer tokens between multiple address pairs with regulation tracking (RTA only)
     * @param froms Array of source addresses
     * @param tos Array of destination addresses
     * @param amounts Array of token amounts to transfer
     * @param regulationTypes Array of regulation types for each transfer
     * @param issuanceDates Array of issuance dates for each transfer
     * @return bool True if all transfers succeed
     * @dev All arrays must have equal length. Reverts if any transfer fails.
     *      Only callable by the registered transfer agent.
     *      MUST revert if any sender has insufficient tokens of the specified regulation/issuance
     *      The RTA determines the transfer strategy for each transfer
     *      Useful for dividend distributions, corporate actions, etc.
     */
    function batchTransferFrom(
        address[] calldata froms,
        address[] calldata tos,
        uint256[] calldata amounts,
        uint16[] calldata regulationTypes,
        uint256[] calldata issuanceDates
    ) external returns (bool);

    /**
     * @notice Batch burn tokens from multiple addresses with regulation tracking (RTA only)
     * @param froms Array of addresses from which to burn tokens
     * @param amounts Array of token amounts to burn from each address
     * @param regulationTypes Array of regulation types for each burn
     * @param issuanceDates Array of issuance dates for each burn
     * @return bool True if all burns succeed
     * @dev All arrays must have equal length. Reverts if any burn fails.
     *      Only callable by the registered transfer agent.
     *      MUST revert if any holder has insufficient tokens of the specified regulation/issuance
     *      Useful for redemptions, corporate buybacks, etc.
     */
    function batchBurnFrom(
        address[] calldata froms,
        uint256[] calldata amounts,
        uint16[] calldata regulationTypes,
        uint256[] calldata issuanceDates
    ) external returns (bool);

    // Fee Collection Mechanism

    /**
     * @notice Register or deregister a broker for this token (RTA only)
     * @param broker Address of the broker to register/deregister
     * @param isApproved Whether to approve or revoke broker status
     * @dev Only callable by RTA after due diligence. Brokers must:
     *      1. Apply off-chain to the RTA
     *      2. Pass KYC/AML and regulatory checks
     *      3. Sign broker agreement
     *      4. Be approved by RTA compliance team
     *
     *      RECOMMENDED: Brokers SHOULD use a proxy pattern similar to RTAProxy
     *      for key management and operational security. This allows:
     *      - Secure key rotation without re-registration
     *      - Multi-signature controls for broker operations
     *      - Business continuity during personnel changes
     *      - Protection against individual key compromise
     *
     *      The broker address registered here MAY be:
     *      - Direct broker-controlled address (simple but less secure)
     *      - BrokerProxy contract address (recommended for production)
     */
    function setBrokerStatus(address broker, bool isApproved) external;

    /**
     * @notice Check if an address is a registered broker
     * @param broker Address to check
     * @return bool True if the address is an approved broker
     */
    function isRegisteredBroker(address broker) external view returns (bool);

    /**
     * @notice Request a transfer with fee payment
     * @param from Source address for the transfer
     * @param to Destination address for the transfer
     * @param amount Number of tokens to transfer
     * @param feeAmount Amount of fee being paid (in the configured fee token)
     * @return requestId Unique identifier for this request (for idempotency and tracking)
     * @dev Creates a new transfer request with initial status: RequestStatus.Requested
     *
     *      Fee payment:
     *      - Fee MUST be paid in the configured fee token (see getFeeToken())
     *      - Caller MUST have approved the token contract to spend feeAmount
     *      - Fee is transferred via safeTransferFrom from msg.sender
     *
     *      Fee payment responsibility:
     *      - Holder-initiated (msg.sender == from): Holder pays the fee
     *      - Broker-initiated (msg.sender != from): Broker pays fee on behalf of client
     *      - Settlement failures: Fees are NOT automatically refunded (RTA discretion)
     *
     *      Request lifecycle:
     *      1. Request created with unique requestId (status: Requested)
     *      2. RTA reviews request (status: UnderReview - optional)
     *      3. RTA approves/rejects (status: Approved or Rejected)
     *      4. If approved, RTA executes transfer (status: Executed)
     *      5. Optional: Request expires after timeout (status: Expired)
     *
     *      Idempotency guarantee:
     *      - Each requestId is unique and can only be executed ONCE
     *      - Duplicate execution attempts MUST revert
     *      - Clients can safely retry requests with new requestId if needed
     *
     *      Authorization requirements:
     *      - If msg.sender == from: Token holder requesting their own transfer
     *      - If msg.sender != from: Must be a registered broker (via setBrokerStatus)
     *      - Reverts if neither condition is met
     *
     *      Implementation MUST:
     *      - Verify fee token is configured (revert if not)
     *      - Generate unique requestId for each request
     *      - Emit TransferRequested event
     *      - Store request details for later processing
     *      - Prevent double-spending by tracking request status
     */
    function requestTransferWithFee(
        address from,
        address to,
        uint256 amount,
        uint256 feeAmount
    ) external returns (uint256 requestId);

    /**
     * @notice Request transfer with [EIP-2612](/EIPS/eip-2612) permit for gasless fee approval (OPTIONAL)
     * @param from Source address for the transfer
     * @param to Destination address for the transfer
     * @param amount Number of tokens to transfer
     * @param feeAmount Amount of fee being paid (in the configured fee token)
     * @param deadline Permit signature deadline
     * @param v ECDSA signature v parameter
     * @param r ECDSA signature r parameter
     * @param s ECDSA signature s parameter
     * @return requestId Unique identifier for this transfer request
     * @dev OPTIONAL: Allows fee payment without prior approve() transaction
     *      Uses [EIP-2612](/EIPS/eip-2612) permit for gasless approval of fee token
     *      Particularly useful for first-time users who don't have fee token approvals
     *      MUST revert if the configured fee token doesn't support [EIP-2612](/EIPS/eip-2612)
     *      Example: USDC, DAI, and other modern stablecoins support permit
     *
     *      Implementation:
     *      1. Call permit on the configured fee token with the provided signature
     *      2. Then execute the same logic as requestTransferWithFee
     *      3. This avoids users needing a separate approve transaction for fees
     */
    function requestTransferWithPermit(
        address from,
        address to,
        uint256 amount,
        uint256 feeAmount,
        uint256 deadline,
        uint8 v,
        bytes32 r,
        bytes32 s
    ) external returns (uint256 requestId);

    /**
     * @notice Get current fee for a transfer
     * @param from Source address
     * @param to Destination address
     * @param amount Transfer amount
     * @return feeAmount Required fee amount in the configured fee token
     * @dev Allows dynamic fee calculation based on transfer parameters
     *      Fee is always denominated in the configured fee token (see getFeeToken())
     *      Fee type determines calculation:
     *      - Type 0 (flat): Returns feeValue directly
     *      - Type 1 (percentage): Returns (amount * feeValue) / 10000
     */
    function getTransferFee(address from, address to, uint256 amount)
        external view returns (uint256 feeAmount);

    /**
     * @notice Get the configured fee token address
     * @return token The [ERC-20](/EIPS/eip-20) token used for fee payments
     * @dev Returns address(0) if no fee token is configured yet
     *      RTA MUST configure a fee token before transfers can be requested
     *      Common choices: USDC, USDT, or other stablecoins
     */
    function getFeeToken() external view returns (address token);

    /**
     * @notice Set the fee token (RTA only)
     * @param newFeeToken Address of the [ERC-20](/EIPS/eip-20) token to use for fees
     * @dev Only callable by RTA to configure or change the fee token
     *      MUST emit FeeTokenUpdated event
     *      MUST NOT accept address(0) - use a stablecoin like USDC
     *      Changing fee token does not affect pending transfer requests
     */
    function setFeeToken(address newFeeToken) external;

    /**
     * @notice Set fee parameters (RTA only)
     * @param feeType Type of fee structure (0: flat, 1: percentage in basis points)
     * @param feeValue Fee amount or percentage basis points
     * @dev Only callable by RTA to update fee structure
     *      MUST emit FeeParametersUpdated event
     *      For percentage fees, feeValue is in basis points (100 = 1%)
     */
    function setFeeParameters(uint8 feeType, uint256 feeValue) external;

    /**
     * @notice Withdraw collected fees (RTA only)
     * @param amount Amount to withdraw (in the configured fee token)
     * @param recipient Recipient address for fees
     * @dev Only callable by RTA to collect accumulated fees
     *      Withdraws from the configured fee token balance
     *      MUST revert if insufficient collected fees
     */
    function withdrawFees(uint256 amount, address recipient) external;

    /**
     * @notice Process pending transfer request (RTA only)
     * @param requestId ID of the transfer request
     * @param approved Whether to approve or reject the transfer
     * @dev RTA reviews and processes transfer requests after compliance checks
     *      MUST transition request through proper lifecycle states
     *      MUST emit events for each state transition
     */
    function processTransferRequest(uint256 requestId, bool approved) external;

    /**
     * @notice Reject transfer request with specific reason code (RTA only)
     * @param requestId ID of the transfer request to reject
     * @param reasonCode Rejection reason code (see Reason Codes section)
     * @param refundFee Whether to refund the fee to the requester
     * @dev Convenience function for rejections with detailed reason tracking
     *      MUST transition request status to Rejected
     *      MUST emit TransferRejected event with reasonCode and refundFee flag
     *      If refundFee is true, MUST return the fee to the original payer
     *      Alternative to processTransferRequest(requestId, false) with more detail
     */
    function rejectTransferRequest(uint256 requestId, uint16 reasonCode, bool refundFee) external;

    // Transfer Request Lifecycle Management

    /**
     * @notice Request lifecycle states
     * @dev Requests MUST follow this state machine:
     *      Requested → UnderReview → (Approved | Rejected) → Executed
     *
     *      State transitions:
     *      - Requested: Initial state when requestTransferWithFee is called
     *      - UnderReview: RTA begins compliance checks (optional intermediate state)
     *      - Approved: RTA approves after compliance checks pass
     *      - Rejected: RTA rejects for compliance or other reasons
     *      - Executed: Transfer completed and tokens moved
     *      - Expired: Request timed out without processing (if timeouts implemented)
     *
     *      Idempotency: Each requestId MUST be unique and can only be executed ONCE
     */
    enum RequestStatus {
        Requested,    // 0: Initial state
        UnderReview,  // 1: RTA is reviewing
        Approved,     // 2: Approved, awaiting execution
        Rejected,     // 3: Rejected, terminal state
        Executed,     // 4: Successfully executed, terminal state
        Expired       // 5: Timed out, terminal state
    }

    /**
     * @notice Get current status of a transfer request (OPTIONAL)
     * @param requestId The transfer request ID
     * @dev OPTIONAL: Implementations MAY instead expose equivalent request data
     *      through other read methods (e.g., a public storage mapping).
     * @return status Current RequestStatus
     * @return from Source address
     * @return to Destination address
     * @return amount Transfer amount
     * @return requestedAt Timestamp when request was created
     * @return processedAt Timestamp when request was processed (0 if pending)
     */
    function getRequestStatus(uint256 requestId) external view returns (
        RequestStatus status,
        address from,
        address to,
        uint256 amount,
        uint256 requestedAt,
        uint256 processedAt
    );

    /**
     * @notice Update request status (RTA only)
     * @param requestId The transfer request ID
     * @param newStatus New status to transition to
     * @dev MUST validate state transitions according to lifecycle rules
     *      MUST emit RequestStatusChanged event
     *      Invalid transitions MUST revert
     */
    function updateRequestStatus(uint256 requestId, RequestStatus newStatus) external;

    // Events for transfer request lifecycle
    event TransferRequested(
        uint256 indexed requestId,
        address indexed from,
        address indexed to,
        uint256 amount,
        uint256 feePaid,
        address requestedBy  // holder or broker
    );

    event RequestStatusChanged(
        uint256 indexed requestId,
        RequestStatus indexed oldStatus,
        RequestStatus indexed newStatus,
        uint256 timestamp
    );

    event TransferExecuted(
        uint256 indexed requestId,
        address indexed from,
        address indexed to,
        uint256 amount
    );

    event TransferRejected(
        uint256 indexed requestId,
        uint16 reasonCode,  // Gas-efficient reason codes (see Reason Codes section)
        bool feeRefunded    // Whether fee was refunded
    );

    event TransferExpired(
        uint256 indexed requestId,
        uint256 expiredAt
    );

    // Fee-related events
    event FeeParametersUpdated(uint8 feeType, uint256 feeValue);
    event FeeTokenUpdated(address indexed previousToken, address indexed newToken);
    event FeesWithdrawn(uint256 amount, address indexed recipient);
    event BrokerStatusUpdated(address indexed broker, bool isApproved, address indexed updatedBy);

    // Account restriction events
    event AccountFrozen(address indexed account, bool frozen, address indexed frozenBy);

    // Reason Codes for Transfer Rejection
    // Gas-efficient uint16 codes instead of strings
    uint16 constant REASON_COMPLIANCE_FAILED = 1;        // KYC/AML check failed
    uint16 constant REASON_INSUFFICIENT_BALANCE = 2;     // Sender lacks tokens
    uint16 constant REASON_RESTRICTED_ACCOUNT = 3;       // Account is frozen/restricted
    uint16 constant REASON_TRANSFER_WINDOW_CLOSED = 4;   // Outside allowed transfer window
    uint16 constant REASON_EXCEEDS_HOLDING_LIMIT = 5;    // Would exceed max holding
    uint16 constant REASON_REGULATORY_HALT = 6;          // Trading halted by regulator
    uint16 constant REASON_COURT_ORDER = 7;              // Blocked by court order
    uint16 constant REASON_INVALID_RECIPIENT = 8;        // Recipient not whitelisted
    uint16 constant REASON_LOCK_PERIOD = 9;              // Tokens are locked
    uint16 constant REASON_RECIPIENT_NOT_VERIFIED = 10;  // Recipient hasn't completed KYC/AML
    uint16 constant REASON_ADDRESS_NOT_LINKED = 11;      // Address not linked to verified identity
    uint16 constant REASON_SENDER_VERIFICATION_EXPIRED = 12; // Sender's KYC expired
    uint16 constant REASON_JURISDICTION_BLOCKED = 13;    // Recipient in restricted jurisdiction
    uint16 constant REASON_ACCREDITATION_REQUIRED = 14;  // Recipient not accredited (Reg D)
    uint16 constant REASON_OTHER = 999;                  // Other/unspecified reason

    // Fee Refund Policy
    /**
     * @notice Fee refund policy for rejected/expired transfers
     * @dev Implementations MUST clearly document their refund policy:
     *      Option 1: AUTO_REFUND - Fees automatically refunded on rejection/expiry
     *      Option 2: NO_REFUND - Fees retained for processing costs
     *      Option 3: CONDITIONAL_REFUND - Refund based on reason code
     *
     *      The refund policy SHOULD be:
     *      - Clearly documented in the contract
     *      - Communicated to users before fee payment
     *      - Consistently applied across all transfers
     *      - Emit TransferRejected event with feeRefunded flag
     */

    // Optional: Off-chain Compliance Pre-check (EIP-3668 CCIP-Read)

    /**
     * @notice Pre-check transfer compliance off-chain (OPTIONAL)
     * @param from Source address for the transfer
     * @param to Destination address for the transfer
     * @param amount Number of tokens to transfer
     * @return bool True if transfer would likely pass compliance
     * @dev OPTIONAL: Implements EIP-3668 (CCIP-Read) for off-chain compliance checks
     *
     *      This check SHOULD verify:
     *      1. Sender KYC/AML status is current (not expired)
     *      2. Recipient has passed KYC/AML verification
     *      3. Recipient address ownership is verified and linked to identity
     *      4. Transfer doesn't violate jurisdiction restrictions
     *      5. Accreditation requirements are met (if applicable for Reg D/Reg A)
     *
     *      This function MAY revert with OffchainLookup error containing:
     *      - URLs for off-chain compliance services
     *      - Callback function to process off-chain response
     *
     *      Purpose: Allow wallets to pre-screen transfers before users pay gas
     *      Benefits:
     *      - Show specific compliance failure reasons upfront
     *      - Improve UX by preventing failed transactions
     *      - Reduce wasted gas on non-compliant transfers
     *
     *      IMPORTANT: This check is ADVISORY ONLY and NOT BINDING
     *      - The actual transfer still requires RTA approval
     *      - Compliance status may change between pre-check and execution
     *      - RTA has final authority on all transfers
     *
     *      Example implementation:
     *      ```solidity
     *      error OffchainLookup(address sender, string[] urls, bytes callData,
     *                          bytes4 callbackFunction, bytes extraData);
     *
     *      function preCheckCompliance(address from, address to, uint256 amount)
     *          external view returns (bool) {
     *          revert OffchainLookup(
     *              address(this),
     *              urls,  // RTA's compliance API endpoints
     *              abi.encodeWithSignature("checkCompliance(address,address,uint256)", from, to, amount),
     *              this.preCheckComplianceCallback.selector,
     *              ""
     *          );
     *      }
     *      ```
     *
     *      Wallets supporting [EIP-3668](/EIPS/eip-3668) will:
     *      1. Catch the OffchainLookup error
     *      2. Query the specified URLs with the provided callData
     *      3. Call the callback function with response and UNMODIFIED extraData
     *      4. Display compliance status to user based on callback result
     *      5. Allow/prevent transfer request submission accordingly
     */
    function preCheckCompliance(address from, address to, uint256 amount)
        external view returns (bool);

    /**
     * @notice Callback for processing off-chain compliance response (OPTIONAL)
     * @param response Encoded response from off-chain compliance service
     * @param extraData Additional data from original request (passed through unmodified)
     * @return bool Compliance check result
     * @dev Only called by wallets supporting EIP-3668
     *      Validates and interprets off-chain compliance service response
     *
     *      Per [EIP-3668](/EIPS/eip-3668) specification:
     *      - Clients MUST pass extraData unmodified from the OffchainLookup error
     *      - The callback signature MUST match EIP-3668's standard format
     *      - This enables stateless operation and future extensibility
     *
     *      Example client implementation:
     *      1. Catch OffchainLookup(sender, urls, callData, callbackFunction, extraData)
     *      2. Query off-chain service with callData
     *      3. Call callbackFunction(response, extraData) with UNMODIFIED extraData
     */
    function preCheckComplianceCallback(bytes calldata response, bytes calldata extraData)
        external pure returns (bool);

    // ============ ERC-1643 Document Management Interface (OPTIONAL) ============
    // Implementations MAY support on-chain anchoring of document references.
    // RTAs already maintain authoritative books and records off-chain per their
    // regulatory obligations; on-chain anchoring is an optional transparency
    // enhancement, not a compliance requirement.

    /**
     * @notice Set a document for the token (RTA only) (OPTIONAL)
     * @param _name Document name (unique identifier)
     * @param _uri Document location (IPFS hash or HTTPS URL)
     * @param _documentHash Hash of the document for verification
     * @dev Part of ERC-1643 standard. Only callable by RTA.
     *      Used for storing references to legal documents, compliance certificates,
     *      court orders, recovery evidence, physical addresses, etc.
     *      Never store PII directly on-chain - use document URIs and hashes only.
     *
     *      Common document names:
     *      - "PHYSICAL_ADDRESS": Issuer's registered address
     *      - "PROSPECTUS": Offering documents
     *      - "COURT_ORDER": Legal judgments
     *      - "RECOVERY_EVIDENCE": Lost wallet documentation
     *
     *      Implementations providing this function MUST emit DocumentUpdated.
     */
    function setDocument(
        bytes32 _name,
        string calldata _uri,
        bytes32 _documentHash
    ) external;

    /**
     * @notice Get a specific document's details (OPTIONAL)
     * @param _name Document name to retrieve
     * @return documentUri Document location
     * @return documentHash Document hash for verification
     * @return timestamp When document was last updated
     * @dev Part of ERC-1643 standard. Publicly accessible.
     */
    function getDocument(bytes32 _name)
        external view
        returns (
            string memory documentUri,
            bytes32 documentHash,
            uint256 timestamp
        );

    /**
     * @notice Remove a document (RTA only) (OPTIONAL)
     * @param _name Document name to remove
     * @dev Part of ERC-1643 standard. Only callable by RTA.
     *      Implementations providing this function MUST emit DocumentRemoved.
     */
    function removeDocument(bytes32 _name) external;

    /**
     * @notice Get all document names (OPTIONAL)
     * @return Array of all document names that have been set
     * @dev Part of ERC-1643 standard. Publicly accessible.
     *      Allows discovery of all documents associated with the token.
     */
    function getAllDocuments() external view returns (bytes32[] memory);

    // ============ Recovery Workflow for Lost/Compromised Wallets (OPTIONAL) ============
    // Uses ERC-1643 for document management and aligns with ERC-1644 for controller operations.
    // OPTIONAL: This structured, time-locked workflow is an extension. The REQUIRED
    // baseline for recovery is controllerTransfer — the RTA verifies the investor's
    // identity through its existing off-chain KYC records and executes the transfer.
    // The structured workflow adds public evidence anchoring and a dispute window
    // for deployments that want on-chain transparency of recovery operations.

    /**
     * @notice Initiate recovery process for lost wallet (RTA only) (OPTIONAL)
     * @param lostWallet Address that has lost access
     * @param newWallet Proposed replacement address
     * @param documentName Name/type of the supporting document (ERC-1643 compatible)
     * @param uri URI pointing to the evidence document (IPFS/HTTPS)
     * @param documentHash Hash of the document for integrity verification
     * @return recoveryId Unique identifier for the recovery request
     * @dev Creates a time-locked recovery request requiring multi-step verification:
     *      1. Identity verification of the claiming party
     *      2. Proof of ownership (off-chain documentation)
     *      3. Time delay for potential disputes (e.g., 30 days)
     *      4. Final execution after time lock expires
     *
     *      Following ERC-1643 document management standards:
     *      - documentName: Type of evidence (e.g., "RECOVERY_AFFIDAVIT", "DEATH_CERTIFICATE")
     *      - uri: Link to encrypted document storage (never store PII on-chain)
     *      - documentHash: Cryptographic hash for document integrity
     *
     *      Implementations providing this function MUST emit DocumentUpdated
     *      per ERC-1643 when evidence is submitted
     */
    function initiateRecovery(
        address lostWallet,
        address newWallet,
        bytes32 documentName,
        string calldata uri,
        bytes32 documentHash
    ) external returns (uint256 recoveryId);

    /**
     * @notice Cancel a pending recovery request (RTA only) (OPTIONAL)
     * @param recoveryId The recovery request to cancel
     * @dev Can be called if:
     *      - Original wallet owner proves they still have access
     *      - Evidence is found to be fraudulent
     *      - Court order requires cancellation
     */
    function cancelRecovery(uint256 recoveryId) external;

    /**
     * @notice Execute recovery after time lock expires (RTA only) (OPTIONAL)
     * @param recoveryId The recovery request to execute
     * @dev Transfers all tokens from lost wallet to new wallet
     *      Can only be executed after time lock period (e.g., 30 days)
     *      Implementations providing this function MUST emit ControllerTransfer
     *      per ERC-1644
     */
    function executeRecovery(uint256 recoveryId) external;

    /**
     * @notice Controller transfer for court orders (RTA only) - ERC-1644 compatible
     * @param from Source address
     * @param to Destination address
     * @param amount Number of tokens
     * @param data Encoded data containing document references
     * @param operatorData Encoded document information per ERC-1643:
     *        - documentName: Type (e.g., "COURT_ORDER", "REGULATORY_ACTION")
     *        - uri: Link to encrypted document storage
     *        - documentHash: Cryptographic hash for integrity
     * @dev Immediate transfer without time lock for:
     *      - Court-ordered transfers (divorce, judgments)
     *      - Regulatory enforcement actions
     *      - Estate distributions with proper documentation
     *
     *      Following ERC-1644 controller operation standards:
     *      - MUST emit ControllerTransfer event
     *      - Uses standard function name for tooling compatibility
     *
     *      Following ERC-1643 document management:
     *      - MUST emit DocumentUpdated event when court order is attached
     *      - Never store PII on-chain, only document URIs and hashes
     */
    function controllerTransfer(
        address from,
        address to,
        uint256 amount,
        bytes calldata data,
        bytes calldata operatorData
    ) external;

    // ============ Account Freezing ============

    /**
     * @notice Freeze or unfreeze an account (RTA only)
     * @param account Address to freeze/unfreeze
     * @param frozen True to freeze, false to unfreeze
     * @dev Frozen accounts cannot send or receive tokens
     *      Used for compliance holds, regulatory actions, or suspicious activity
     *      Only RTA can freeze/unfreeze accounts
     *      MUST emit AccountFrozen event
     */
    function setAccountFrozen(address account, bool frozen) external;

    /**
     * @notice Check if an account is frozen
     * @param account Address to check
     * @return bool True if the account is frozen
     * @dev Publicly accessible for transparency
     *      Wallets and exchanges can check before attempting transfers
     */
    function isAccountFrozen(address account) external view returns (bool);

    // ============ Recovery System (OPTIONAL) ============

    /**
     * @notice Get recovery request details (OPTIONAL)
     * @param recoveryId The recovery request ID
     * @return lostWallet The wallet being recovered
     * @return newWallet The replacement wallet
     * @return documentName The type of evidence document (ERC-1643)
     * @return documentUri The URI of the evidence document
     * @return documentHash The hash of the evidence document
     * @return initiatedAt Timestamp when recovery was initiated
     * @return status Current status (pending/executed/cancelled)
     */
    function getRecoveryDetails(uint256 recoveryId)
        external view returns (
            address lostWallet,
            address newWallet,
            bytes32 documentName,
            string memory documentUri,
            bytes32 documentHash,
            uint256 initiatedAt,
            uint8 status
        );

    /**
     * @notice Check if a wallet has a pending recovery
     * @param wallet Address to check
     * @return bool True if wallet has pending recovery
     * @return uint256 Recovery ID if exists, 0 otherwise
     */
    function hasPendingRecovery(address wallet)
        external view returns (bool, uint256);

    // Standard Events from ERC-1644 (Controller Operations)
    event ControllerTransfer(
        address indexed controller,
        address indexed from,
        address indexed to,
        uint256 value,
        bytes data,
        bytes operatorData
    );

    event ControllerRedemption(
        address indexed controller,
        address indexed tokenHolder,
        uint256 value,
        bytes data,
        bytes operatorData
    );

    // ERC-1643 Standard Events (Document Management — OPTIONAL, required if
    // the document management extension is implemented)
    event DocumentUpdated(
        bytes32 indexed _name,
        string _uri,
        bytes32 _documentHash
    );
    event DocumentRemoved(
        bytes32 indexed _name,
        string _uri,
        bytes32 _documentHash
    );

    // Recovery-specific Events (OPTIONAL, required if the recovery workflow
    // extension is implemented)
    event RecoveryInitiated(
        uint256 indexed recoveryId,
        address indexed lostWallet,
        address indexed newWallet,
        uint256 timelock
    );
    event RecoveryCancelled(uint256 indexed recoveryId, address cancelledBy);
    // RecoveryExecuted is replaced by ControllerTransfer event per ERC-1644
}

// IERC1450 unique functions (not in ERC-20):
bytes4 constant private CHANGEISSUER = bytes4(keccak256("changeIssuer(address)"));
bytes4 constant private SETTRANSFERAGENT = bytes4(keccak256("setTransferAgent(address)"));
bytes4 constant private ISTRANSFERAGENT = bytes4(keccak256("isTransferAgent(address)"));
bytes4 constant private ISSECURITYTOKEN = bytes4(keccak256("isSecurityToken()"));
bytes4 constant private MINT = bytes4(keccak256("mint(address,uint256,uint16,uint256)"));
bytes4 constant private BURNFROM = bytes4(keccak256("burnFrom(address,uint256)"));
bytes4 constant private BURNFROMREGULATION = bytes4(keccak256("burnFromRegulation(address,uint256,uint16)"));
bytes4 constant private GETHOLDERREGULATIONS = bytes4(keccak256("getHolderRegulations(address)"));
bytes4 constant private GETREGULATIONSUPPLY = bytes4(keccak256("getRegulationSupply(uint16)"));
// ... additional IERC1450-specific functions

// The computed interface ID:
bytes4 constant public IERC1450_INTERFACE_ID = CHANGEISSUER ^ SETTRANSFERAGENT ^ ISTRANSFERAGENT ^ ISSECURITYTOKEN ^ MINT ^ BURNFROM ^ BURNFROMREGULATION ^ GETHOLDERREGULATIONS ^ GETREGULATIONSUPPLY /* ^ ... */;
// Actual value from reference implementation:
bytes4 constant public IERC1450_INTERFACE_ID = 0xaf175dee;

/**
 * @title RTAProxy
 * @notice Multi-signature proxy contract for RTA operations
 * @dev Deployed once and set as the permanent transferAgent in ERC-1450 tokens
 *
 * The RTAProxy pattern provides:
 * - Protection against single key compromise via M-of-N multi-signature
 * - Generic operation execution (can call any function on any target)
 * - Signer management through multi-sig consensus
 * - Complete audit trail of all RTA actions
 *
 * SECURITY REQUIREMENTS:
 * - MUST use multiple signers (recommended: 2-of-3 or 3-of-5)
 * - Signers SHOULD use hardware wallets or institutional custody
 * - All operations MUST emit events for audit trail
 */
interface IRTAProxy {
    // ============ Events ============

    event SignerAdded(address indexed signer);
    event SignerRemoved(address indexed signer);
    event RequiredSignaturesUpdated(uint256 oldRequired, uint256 newRequired);
    event OperationSubmitted(uint256 indexed operationId, address indexed submitter);
    event OperationConfirmed(uint256 indexed operationId, address indexed signer);
    event OperationExecuted(uint256 indexed operationId);
    event OperationRevoked(uint256 indexed operationId, address indexed signer);

    // ============ Errors ============

    error NotASigner();
    error AlreadyASigner();
    error AlreadyConfirmed();
    error NotConfirmed();
    error InsufficientConfirmations();
    error OperationAlreadyExecuted();
    error InvalidSignerCount();

    // ============ Multi-Sig Operations ============

    /**
     * @notice Submit a new operation for multi-sig approval
     * @param target The contract to call (e.g., ERC-1450 token address)
     * @param data The encoded function call (e.g., abi.encodeWithSignature("mint(...)"))
     * @param value ETH value to send (usually 0)
     * @return operationId The ID of the submitted operation
     * @dev Submitter automatically confirms the operation
     *      Operation auto-executes if submitter's confirmation meets threshold
     */
    function submitOperation(
        address target,
        bytes memory data,
        uint256 value
    ) external returns (uint256 operationId);

    /**
     * @notice Confirm a pending operation
     * @param operationId The operation to confirm
     * @dev Auto-executes when confirmation threshold is met
     */
    function confirmOperation(uint256 operationId) external;

    /**
     * @notice Revoke a previously given confirmation
     * @param operationId The operation to revoke confirmation from
     */
    function revokeConfirmation(uint256 operationId) external;

    /**
     * @notice Manually execute an operation that has enough confirmations
     * @param operationId The operation to execute
     */
    function executeOperation(uint256 operationId) external;

    // ============ Signer Management (via multi-sig) ============

    /**
     * @notice Add a new signer (requires multi-sig approval)
     * @param signer Address of the new signer
     * @dev MUST be called through submitOperation (msg.sender == address(this))
     */
    function addSigner(address signer) external;

    /**
     * @notice Remove a signer (requires multi-sig approval)
     * @param signer Address of the signer to remove
     * @dev MUST be called through submitOperation
     *      MUST NOT reduce signers below requiredSignatures
     */
    function removeSigner(address signer) external;

    /**
     * @notice Update required signature threshold (requires multi-sig approval)
     * @param newRequiredSignatures New threshold
     * @dev MUST be called through submitOperation
     *      MUST be > 0 and <= signers.length
     */
    function updateRequiredSignatures(uint256 newRequiredSignatures) external;

    // ============ View Functions ============

    /**
     * @notice Get the list of current signers
     * @return Array of signer addresses
     */
    function getSigners() external view returns (address[] memory);

    /**
     * @notice Check if an address has confirmed an operation
     * @param operationId The operation ID
     * @param signer The signer address
     * @return bool True if the signer has confirmed
     */
    function hasConfirmed(uint256 operationId, address signer) external view returns (bool);

    /**
     * @notice Get operation details
     * @param operationId The operation ID
     * @return target The target contract
     * @return data The encoded function call
     * @return value The ETH value
     * @return confirmations Number of confirmations
     * @return executed Whether the operation has been executed
     * @return timestamp When the operation was submitted
     */
    function getOperation(uint256 operationId) external view returns (
        address target,
        bytes memory data,
        uint256 value,
        uint256 confirmations,
        bool executed,
        uint256 timestamp
    );

    /**
     * @notice Returns the contract implementation version
     * @return string Semantic version string (e.g., "1.13.0")
     */
    function version() external pure returns (string memory);
}

// Signer 1 submits mint operation
bytes memory mintData = abi.encodeWithSignature(
    "mint(address,uint256,uint16,uint256)",
    investor,
    1000,
    0x0006,  // REG_US_CF
    block.timestamp
);
uint256 opId = rtaProxy.submitOperation(tokenAddress, mintData, 0);

// Signer 2 confirms (auto-executes if 2-of-3)
rtaProxy.confirmOperation(opId);

/**
 * @title IBrokerProxy
 * @notice Optional proxy pattern for registered brokers
 * @dev While not required like RTAProxy, this pattern is RECOMMENDED for:
 *      - Professional broker-dealers with multiple traders
 *      - High-volume brokers needing key rotation
 *      - Brokers using institutional custody solutions
 */
interface IBrokerProxy {
    // Events
    event OperatorRotated(address indexed previousOperator, address indexed newOperator);
    event RequestSubmitted(uint256 indexed requestId, address from, address to, uint256 amount);

    /**
     * @notice Submit transfer request on behalf of client
     * @dev Only callable by authorized operators of this broker
     */
    function submitTransferRequest(
        address token,
        address from,
        address to,
        uint256 amount,
        address feeToken,
        uint256 feeAmount
    ) external payable returns (uint256 requestId);

    /**
     * @notice Rotate broker operator (multi-sig required)
     * @param newOperator New operator address (should be multi-sig)
     */
    function rotateOperator(address newOperator) external;

    /**
     * @notice Check if address is authorized operator
     */
    function isOperator(address account) external view returns (bool);
}

// Get the configured fee token
address feeToken = token.getFeeToken();
// Returns: 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48 (USDC on mainnet)

// Get the fee amount for a transfer
uint256 feeAmount = token.getTransferFee(from, to, amount);
// Returns: 10000000 (10 USDC with 6 decimals) for flat fee
// OR calculated percentage for percentage-based fees

// Set the fee token (typically USDC or another stablecoin)
token.setFeeToken(USDC_ADDRESS);

// Set fee parameters
// Type 0: Flat fee (feeValue is the exact amount in fee token units)
token.setFeeParameters(0, 10000000); // 10 USDC flat fee

// Type 1: Percentage fee (feeValue is basis points, 100 = 1%)
token.setFeeParameters(1, 50); // 0.5% fee

// Example encoding (not part of the standard, implementations may vary):
// Format: 0xCCRR where CC = country code, RR = regulation code

// US Regulations (0x00XX)
uint16 constant REG_US_S1 = 0x0001;           // S-1 Registration (IPO)
uint16 constant REG_US_D_504 = 0x0002;        // Regulation D Rule 504 ($10M)
uint16 constant REG_US_A_TIER_1 = 0x0004;     // Regulation A Tier I ($20M)
uint16 constant REG_US_A_TIER_2 = 0x0005;     // Regulation A Tier II ($75M)
uint16 constant REG_US_CF = 0x0006;           // Regulation Crowdfunding ($5M)
uint16 constant REG_US_D_506B = 0x0007;       // Regulation D 506(b) (no general solicitation)
uint16 constant REG_US_D_506C = 0x0008;       // Regulation D 506(c) (accredited only)
uint16 constant REG_US_S = 0x0009;            // Regulation S (offshore offerings)

// EU Regulations (0x01XX)
uint16 constant REG_EU_PROSPECTUS = 0x0101;   // EU Prospectus Regulation

// Canadian Regulations (0x02XX)
uint16 constant REG_CA_OM = 0x0201;           // Offering Memorandum

struct TokenBatch {
    uint256 amount;
    uint16 regulationType;
    uint256 issuanceDate;  // Original share issuance, not tokenization
}

mapping(address => TokenBatch[]) private holderBatches;

// At mint time (tokenizing shares from March 2023 offering)
mint(investor, 1000, 0x0006, 1677628800); // REG_US_CF, March 1, 2023

// Transfer request in November 2024
// RTA calculates: Nov 2024 - March 2023 = 20 months (> 12 months)
// Result: Shares have matured, transfer allowed to any eligible investor

// Transfer request if it had been May 2023
// RTA calculates: May 2023 - March 2023 = 2 months (< 12 months)
// Result: Transfer blocked with REASON_LOCK_PERIOD

// Holder has:
// - 100 tokens: Reg CF, issued March 2023
// - 200 tokens: Reg D, issued June 2023
// - 50 tokens: Reg A, issued September 2023

// Transfer request for 150 tokens - RTA chooses strategy:
// Option A (FIFO): transferFromRegulated(..., 100, REG_CF, March2023)
//                  transferFromRegulated(..., 50, REG_D, June2023)
// Option B (LIFO): transferFromRegulated(..., 50, REG_A, Sept2023)
//                  transferFromRegulated(..., 100, REG_D, June2023)
// Option C (Tax Optimized): Transfer specific lots for best tax outcome
// Option D (Regulatory): Transfer only matured/unrestricted batches

// Using burnFrom(address, amount) - RTA determines strategy
// Using burnFromRegulated(address, amount, regulation, date) - Precise control
// Using burnFromRegulation(address, amount, regulation) - Regulation-specific

// RTA can optimize based on:
// - Tax implications (short vs long-term gains)
// - Regulatory maturity (expired lockups first)
// - Holder preferences (specific lot selection)
// - Corporate actions (specific share class redemption)

// 2-for-1 split implementation pattern
function executeSplit(uint256 splitRatio) external onlyRTA {
    address[] memory holders = getAllHolders(); // Off-chain tracked
    for (uint i = 0; i < holders.length; i++) {
        uint256 currentBalance = balanceOf(holders[i]);
        uint256 additionalShares = currentBalance * (splitRatio - 1);

        // Mint additional shares
        _mint(holders[i], additionalShares);
        // Emit canonical events for indexers
        emit Transfer(address(0), holders[i], additionalShares);
    }
}

// RTA takes snapshot at record date
mapping(address => uint256) recordDateBalances;

// Off-chain: Calculate pro-rata distributions
// Execute stablecoin transfers via separate contract or traditional rails

contract DividendClaim {
    IERC20 public paymentToken; // e.g., USDC
    mapping(address => uint256) public claimableAmounts;
    uint256 public recordDate;

    function claim() external {
        require(rtaContract.isKYCVerified(msg.sender), "KYC required");
        uint256 amount = claimableAmounts[msg.sender];
        claimableAmounts[msg.sender] = 0;
        paymentToken.transfer(msg.sender, amount);
    }
}

function executeMandatoryRedemption(
    address holder,
    uint256 amount,
    uint256 pricePerShare,
    string calldata reason
) external onlyRTA {
    // Force transfer to redemption pool
    _transferFrom(holder, redemptionPool, amount);

    // Record redemption terms
    emit Redemption(holder, amount, pricePerShare, reason);

    // Payment handled via separate mechanism
    // (stablecoin transfer, wire, check)
}

contract TenderOffer {
    uint256 public offerPrice;
    uint256 public offerExpiry;
    address public offeror;

    function acceptOffer(uint256 amount) external {
        require(block.timestamp < offerExpiry, "Offer expired");
        require(rtaContract.isKYCVerified(msg.sender), "KYC required");

        // Transfer shares to offeror
        token.requestTransferWithFee(msg.sender, offeror, amount, fee);

        // Payment handled separately
        emit OfferAccepted(msg.sender, amount, offerPrice);
    }
}

contract MergerExchange {
    IERC1450 public oldToken;
    IERC1450 public newToken;
    uint256 public exchangeRatio; // e.g., 100 = 1:1, 150 = 1.5:1

    function exchangeTokens(uint256 amount) external {
        require(rtaContract.isKYCVerified(msg.sender), "KYC required");

        // Burn old tokens
        oldToken.requestTransferWithFee(msg.sender, address(0), amount, 0);

        // Mint new tokens at exchange ratio
        uint256 newAmount = (amount * exchangeRatio) / 100;
        newToken.mint(msg.sender, newAmount);
    }
}

// RTA maintains historical balances in database
// Query: SELECT balance FROM holdings WHERE address = ? AND timestamp <= ?
// This provides complete flexibility without on-chain gas costs

// Use existing snapshot solutions like OpenZeppelin's ERC20Snapshot
// or deploy a separate SnapshotManager contract
interface ISnapshotManager {
    function takeSnapshot() external returns (uint256 snapshotId);
    function balanceOfAt(address account, uint256 snapshotId) external view returns (uint256);
}

// For simple needs, just record block numbers
mapping(uint256 => uint256) public recordDates; // actionId => blockNumber

// Off-chain services can reconstruct balances at any block
// using historical blockchain data

// Store proxy voting rules via ERC-1643 document management
rtaContract.setDocument(
    "PROXY_RULES_2024",
    "ipfs://QmProxyVotingRulesHash",
    block.timestamp
);

contract VotingRegistry {
    struct ProxyVote {
        uint256 recordDate;
        uint256 votingDeadline;
        string proposalUri; // IPFS link to proposal details
        mapping(address => bool) hasVoted;
        mapping(uint256 => uint256) votes; // optionId => voteCount
    }

    // RTA records votes submitted through traditional proxy channels
    function recordVote(
        uint256 voteId,
        address shareholder,
        uint256 optionId,
        uint256 shares
    ) external onlyRTA {
        require(rtaContract.balanceOfAt(shareholder, recordDate) >= shares);
        require(!hasVoted[shareholder], "Already voted");

        votes[optionId] += shares;
        hasVoted[shareholder] = true;

        emit VoteRecorded(voteId, shareholder, optionId, shares);
    }
}

contract MeetingQuorum {
    uint256 public quorumPercentage = 5000; // 50% in basis points

    function calculateQuorum(uint256 recordDate) external view returns (uint256) {
        uint256 totalSupply = token.totalSupply();
        return (totalSupply * quorumPercentage) / 10000;
    }

    function isQuorumMet(uint256 voteId) external view returns (bool) {
        uint256 totalVoted = getTotalVotes(voteId);
        uint256 required = calculateQuorum(votes[voteId].recordDate);
        return totalVoted >= required;
    }
}

// Complete voting lifecycle example
contract ShareholderGovernance {
    IERC1450 public token;
    ISnapshotManager public snapshots;

    function initiateVote(
        string memory proposalUri,
        uint256 votingPeriodDays
    ) external onlyRTA returns (uint256 voteId) {
        // 1. Take snapshot for record date
        uint256 snapshotId = snapshots.takeSnapshot();

        // 2. Store proposal details via ERC-1643
        token.setDocument(
            string(abi.encodePacked("PROPOSAL_", voteId)),
            proposalUri,
            block.timestamp
        );

        // 3. Set voting deadline
        uint256 deadline = block.timestamp + (votingPeriodDays * 1 days);

        // 4. Emit event for indexers and shareholders
        emit VoteInitiated(voteId, snapshotId, deadline, proposalUri);

        return voteId;
    }
}

// Store encrypted reference to tax documentation
rtaContract.setDocument(
    "TAX_DOCS_2024",
    "ipfs://QmTaxDocumentationHash", // Encrypted off-chain storage
    block.timestamp
);

// Example: Dividend payment with withholding (off-chain calculation)
struct DividendPayment {
    address recipient;
    uint256 grossAmount;
    uint256 withholdingRate; // e.g., 3000 = 30%
    uint256 netAmount;       // grossAmount - withholding
}

// RTA calculates withholding based on:
// - Investor tax status (US vs. non-US)
// - Security type (equity vs. debt)
// - Tax treaty benefits
// - Dividend type (ordinary vs. qualified)

// Annual tax reporting references
rtaContract.setDocument(
    "1099_FORMS_2024",
    "encrypted://tax-reports/2024/1099",
    block.timestamp
);

rtaContract.setDocument(
    "1042S_FORMS_2024",
    "encrypted://tax-reports/2024/1042s",
    block.timestamp
);

// Off-chain tax compliance system interfaces with on-chain token
interface ITaxCompliance {
    // All functions are off-chain, shown here for documentation

    function collectW9(address investor) external;
    function collectW8(address investor, W8Type formType) external;
    function calculateWithholding(address investor, uint256 amount) external view returns (uint256);
    function generate1099(address investor, uint256 year) external;
    function generate1042S(address investor, uint256 year) external;

    // On-chain reference only
    function updateTaxDocumentHash(string memory docType, string memory uri) external;
}

// Existing events that ATSs can monitor
event TransferRequested(
    address indexed from,
    address indexed to,
    uint256 value,
    uint256 fee
);

event TransferApproved(
    address indexed from,
    address indexed to,
    uint256 value
);

event TransferRejected(
    address indexed from,
    address indexed to,
    uint256 value,
    uint16 reason
);

// ATS monitors TransferRequested events to understand market interest
// Can display pending transfer requests as "indications of interest"
// Note: Actual execution still requires RTA approval

// ATS matches buyers and sellers off-chain
// Submits transfer via registered broker
function submitMatchedTrade(
    address buyer,
    address seller,
    uint256 shares
) external {
    require(registeredBrokers[msg.sender], "Must be registered broker");

    // Route through standard transfer request
    token.requestTransferWithFee(seller, buyer, shares, brokerFee);
}

// ATS monitors TransferRejected events with reason codes
// Uses this data to:
// - Pre-filter non-compliant trades
// - Understand liquidity constraints
// - Improve matching algorithms

if (reasonCode == REASON_RECIPIENT_NOT_VERIFIED) {
    // Don't match with this buyer until KYC complete
} else if (reasonCode == REASON_INSUFFICIENT_BALANCE) {
    // Seller doesn't have shares available
}

contract ATSAdapter {
    IERC1450 public token;
    address public rtaAddress;

    // Track pending orders
    struct Order {
        address trader;
        bool isBuy;
        uint256 shares;
        uint256 price;
        bool isActive;
    }

    mapping(uint256 => Order) public orders;

    // Submit matched trades to RTA
    function executeTrade(
        uint256 buyOrderId,
        uint256 sellOrderId,
        uint256 shares
    ) external onlyATS {
        Order memory buyOrder = orders[buyOrderId];
        Order memory sellOrder = orders[sellOrderId];

        require(buyOrder.isBuy && !sellOrder.isBuy, "Invalid order types");
        require(buyOrder.isActive && sellOrder.isActive, "Orders not active");

        // Pre-verify compliance
        require(token.isKYCVerified(buyOrder.trader), "Buyer not KYC'd");
        require(token.isKYCVerified(sellOrder.trader), "Seller not KYC'd");

        // Submit transfer through registered broker
        token.requestTransferWithFee(
            sellOrder.trader,
            buyOrder.trader,
            shares,
            calculateFee(shares)
        );

        // Mark orders as pending execution
        orders[buyOrderId].isActive = false;
        orders[sellOrderId].isActive = false;
    }

    // Monitor rejection reasons to update order book
    function handleRejection(
        address from,
        address to,
        uint16 reasonCode
    ) external {
        // Update order book based on rejection reason
        if (reasonCode == 10) { // REASON_RECIPIENT_NOT_VERIFIED
            // Remove buy orders from this recipient
            cancelOrdersForTrader(to);
        }
    }
}

// 1. Check if it's a security token (quickest check)
if (token.isSecurityToken()) {
    // This is ERC-1450, disable transfer/approve UI
    return handleSecurityToken();
}

// 2. Alternative: Check via ERC-165
bytes4 IERC1450_ID = 0x[computed_interface_id];
if (token.supportsInterface(IERC1450_ID)) {
    // This is ERC-1450, handle accordingly
    return handleSecurityToken();
}

// 3. For maximum compatibility, also check:
bytes4 IERC20_ID = 0x36372b07;
bool isERC20 = token.supportsInterface(IERC20_ID);
bool isSecure = token.isSecurityToken();
if (isERC20 && isSecure) {
    // Restricted ERC-20 interface detected
    showRestrictedTokenUI();
}

// Optional ERC-1820 registration
bytes32 constant private IERC1450_HASH = keccak256("IERC1450Token");
registry.setInterfaceImplementer(address(this), IERC1450_HASH, address(this));

// Query version from deployed contract
string memory deployedVersion = token.version();  // Returns "1.17.0"

// Compare with local artifacts to detect upgrades
if (keccak256(bytes(deployedVersion)) != keccak256(bytes(localVersion))) {
    // Upgrade available
}