ERC-8232: Onchain Agency for Represented RWAs

# pragma version 0.4.0
"""
@title ERC-8232: On-Chain Agency for Represented RWAs
@author @secondfrontman
@notice Execution-oriented agency interface complementing RAMS (compliance delegation) 
        and ERC-8183 (agentic commerce) for active management of represented RWAs
@dev Composable with ERC-8004 (agent identity), ERC-8183 (jobs), ERC-3643/7943 (RWA compliance)
"""

interface IERC8232:
    # =============================================================
    # Events
    # =============================================================
    event AgencyAuthorized:
        owner: indexed(address)
        agent: indexed(address)
        rwa_token: indexed(address)
        permissions: uint256          # bitmask for allowed actions
        expiration: uint256           # 0 = indefinite

    event AgencyRevoked:
        owner: indexed(address)
        agent: indexed(address)
        rwa_token: indexed(address)

    event AgencyActionPerformed:
        owner: indexed(address)
        agent: indexed(address)
        rwa_token: indexed(address)
        action_type: uint256
        payload: Bytes[1024]             # optional calldata / reason hash
        success: bool

    # =============================================================
    # View functions
    # =============================================================
    def isValidAgency(owner: address, agent: address, rwa_token: address) -> bool:
        """
        @notice Check if agent is currently authorized to represent owner for this RWA
        @dev Should verify: (1) owner has valid ONCHAINID claims if integrated,
             (2) mandate not expired, (3) not revoked
        """
        ...

    def getAgencyPermissions(owner: address, agent: address, rwa_token: address) -> uint256:
        """
        @notice Return current permission bitmask for this owner-agent-RWA triplet
        """
        ...

    def getAgencyExpiration(owner: address, agent: address, rwa_token: address) -> uint256:
        """
        @notice Return expiration timestamp for this delegation (0 = indefinite)
        """
        ...

    def getRepresentedOwner(agent: address, rwa_token: address) -> address:
        """
        @notice Convenience: return owner this agent represents for given RWA (or zero)
        """
        ...

    # =============================================================
    # State-changing functions (called by owner or via ERC-1271 signature)
    # =============================================================
    def authorizeAgency(
        agent: address,
        rwa_token: address,
        permissions: uint256,
        expiration: uint256
    ) -> bool:
        """
        @notice Owner authorizes agent (ERC-8004 identity) to act on their behalf for RWA
        @dev Recommend supporting ERC-1271 signatures for cold wallet approval
        @param permissions Bitmask of allowed actions (see constants below)
        @param expiration Unix timestamp; 0 = indefinite delegation
        """
        ...

    def revokeAgency(agent: address, rwa_token: address) -> bool:
        """
        @notice Revoke all permissions for this agent on this RWA (instant, owner-only)
        """
        ...

    # =============================================================
    # Action execution (called by the agent)
    # =============================================================
    def performAgencyAction(
        rwa_token: address,
        action_type: uint256,
        call: Bytes[1024]
    ) -> Bytes[1024]:
        """
        @notice Agent executes a compliant action on behalf of represented owner
        @dev Internal checks:
             1. isValidAgency(owner, msg.sender, rwa_token)
             2. action_type permitted in bitmask
             3. Optional: RAMS mandate validity + ERC-7943/3643 canTransact
             4. Execute calldata against rwa_token (via delegatecall or interface)
             5. Emit AgencyActionPerformed for audit + ERC-8004 reputation feed
        @return result Bytes from the executed call (or empty if void)
        """
        ...

# =============================================================
# Permission bitmask constants (suggested, can be extended)
# =============================================================
TRANSFER: constant(uint256)   = 1 << 0   # Execute token transfers
VOTE: constant(uint256)       = 1 << 1   # Cast governance votes
REBALANCE: constant(uint256)  = 1 << 2   # Rebalance positions across pools
MINT_BURN: constant(uint256)  = 1 << 3   # If issuer allows via Agent role
FREEZE: constant(uint256)     = 1 << 4   # Trigger compliance freezes (ERC-3643)
YIELD_STRATEGY: constant(uint256) = 1 << 5  # Execute yield-optimizing actions