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.html)
     * @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.html) 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.html) 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.html) 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.html))
     * @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.html), 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.10.1")
     * @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.html) 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.html) interface ID
     *      - 0xXXXXXXXX: IERC1450 interface ID (see Interface Detection section for calculation)
     *
     *      MUST return false for:
     *      - 0x36372b07: [ERC-20](/eips/eip-20.html) interface ID
     *
     *      Returning false for [ERC-20](/eips/eip-20.html) prevents wallets from assuming standard transfer behavior.
     *      While we are ABI-compatible with [ERC-20](/eips/eip-20.html), 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.html) 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.html) 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.html)
     *      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.html) 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.html) 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.html) 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.html) 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);
}

1. Deploy RTAProxy with initial signers and threshold (e.g., 3 signers, 2-of-3)
2. Deploy ERC-1450 token with transferAgent = RTAProxy address
3. Token's setTransferAgent is locked after RTAProxy is set
4. RTA operations flow: Signer → submitOperation → confirmOperation → auto-execute
5. Signer changes require multi-sig approval through submitOperation
6. All operations emit events for regulatory audit trail

// 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);

When an issuer legitimately needs to change RTA providers:
1. Issuer contracts with new RTA provider
2. Current RTA validates the change request (legal docs, verification)
3. Current RTA transfers records to new RTA
4. Current RTA adds new RTA signers via multi-sig: submitOperation(addSigner(newSigner))
5. Current RTA removes old signers via multi-sig: submitOperation(removeSigner(oldSigner))
6. New RTA now controls all token operations
7. Process is logged on-chain for regulatory compliance

RTA → registers → Broker EOA/Multisig

RTA → registers → BrokerProxy → controls → Operator Multisig

/**
 * @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

// Get the fee token and amount
const feeToken = await token.getFeeToken();
const feeAmount = await token.getTransferFee(from, to, amount);

// Get token info for display
const tokenInfo = await getTokenInfo(feeToken);
const formattedFee = formatUnits(feeAmount, tokenInfo.decimals);

// Display to user: "Transfer fee: 10.00 USDC"
console.log(`Transfer fee: ${formattedFee} ${tokenInfo.symbol}`);

// Ensure user has approved fee token spending
await feeTokenContract.approve(token.address, feeAmount);

// Submit transfer request with fee
const requestId = await token.requestTransferWithFee(from, to, amount, feeAmount);

// 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.10.1"

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