feat: add ITIP1028Escrow interface and TIP-1028 receive policy support (#108)

* feat: add ITIP1028Escrow interface and TIP-1028 receive policy support

Adds the TIP-1028 escrow interface (ITIP1028Escrow) with:
- InboundKind enum, ClaimReceiptV1 struct
- blockedReceiptBalance and claim functions
- TransferBlocked and BlockedReceiptClaimed events
- Error types: UnauthorizedClaimer, InvalidReceiptClaim, InsufficientEscrowBalance,
  EscrowAddressReserved, InvalidClaimAddress, InvalidToken

Updates ITIP403Registry with TIP-1028 receive policy members:
- BlockedReason enum (NONE, TOKEN_FILTER, RECEIVE_POLICY)
- receivePolicy view, validateReceivePolicy view, setReceivePolicy mutator
- ReceivePolicyUpdated event
- InvalidReceivePolicyType and InvalidRecoveryAuthority errors

Wires escrow into StdPrecompiles (0xE5c0...0000) and Tempo base contract.

---------

Co-authored-by: Centaur AI <ai@centaur.local>
Co-authored-by: 0xrusowsky <0xrusowsky@proton.me>

Author: 3 people

src/StdPrecompiles.sol

@@ -6,6 +6,7 @@ import {IAddressRegistry} from "./interfaces/IAddressRegistry.sol";
 import {IFeeManager} from "./interfaces/IFeeManager.sol";
 import {ISignatureVerifier} from "./interfaces/ISignatureVerifier.sol";
 import {ITIP403Registry} from "./interfaces/ITIP403Registry.sol";
+import {ITIP1028Escrow} from "./interfaces/ITIP1028Escrow.sol";
 import {ITIP20Factory} from "./interfaces/ITIP20Factory.sol";
 import {IStablecoinDEX} from "./interfaces/IStablecoinDEX.sol";
 import {IValidatorConfig} from "./interfaces/IValidatorConfig.sol";
@@ -26,6 +27,7 @@ library StdPrecompiles {
     address internal constant VALIDATOR_CONFIG_V2_ADDRESS = 0xCcCCCCcC00000000000000000000000000000001;
     address internal constant ADDRESS_REGISTRY_ADDRESS = 0xfDC0000000000000000000000000000000000000;
     address internal constant SIGNATURE_VERIFIER_ADDRESS = 0x5165300000000000000000000000000000000000;
+    address internal constant ESCROW_ADDRESS = 0xE5c0000000000000000000000000000000000000;
 
     IFeeManager internal constant TIP_FEE_MANAGER = IFeeManager(TIP_FEE_MANAGER_ADDRESS);
     ITIP403Registry internal constant TIP403_REGISTRY = ITIP403Registry(TIP403_REGISTRY_ADDRESS);
@@ -37,4 +39,5 @@ library StdPrecompiles {
     IValidatorConfigV2 internal constant VALIDATOR_CONFIG_V2 = IValidatorConfigV2(VALIDATOR_CONFIG_V2_ADDRESS);
     IAddressRegistry internal constant ADDRESS_REGISTRY = IAddressRegistry(ADDRESS_REGISTRY_ADDRESS);
     ISignatureVerifier internal constant SIGNATURE_VERIFIER = ISignatureVerifier(SIGNATURE_VERIFIER_ADDRESS);
+    ITIP1028Escrow internal constant TIP1028_ESCROW = ITIP1028Escrow(ESCROW_ADDRESS);
 }

src/Tempo.sol

@@ -12,6 +12,7 @@ import {IStablecoinDEX} from "./interfaces/IStablecoinDEX.sol";
 import {ITIP20} from "./interfaces/ITIP20.sol";
 import {ITIP20Factory} from "./interfaces/ITIP20Factory.sol";
 import {ITIP403Registry} from "./interfaces/ITIP403Registry.sol";
+import {ITIP1028Escrow} from "./interfaces/ITIP1028Escrow.sol";
 import {IValidatorConfig} from "./interfaces/IValidatorConfig.sol";
 import {IValidatorConfigV2} from "./interfaces/IValidatorConfigV2.sol";
 
@@ -48,6 +49,10 @@ abstract contract Tempo {
     ITIP403Registry public constant tip403Registry = StdPrecompiles.TIP403_REGISTRY;
     address public constant TIP403_REGISTRY = StdPrecompiles.TIP403_REGISTRY_ADDRESS;
 
+    // TIP-1028 escrow precompile
+    ITIP1028Escrow public constant escrow = StdPrecompiles.TIP1028_ESCROW;
+    address public constant ESCROW = StdPrecompiles.ESCROW_ADDRESS;
+
     // Address registry precompile
     IAddressRegistry public constant addrRegistry = StdPrecompiles.ADDRESS_REGISTRY;
     address public constant ADDRESS_REGISTRY = StdPrecompiles.ADDRESS_REGISTRY_ADDRESS;

src/interfaces/ITIP1028Escrow.sol

@@ -0,0 +1,126 @@
+// SPDX-License-Identifier: MIT OR Apache-2.0
+pragma solidity >=0.8.13 <0.9.0;
+
+import {ITIP403Registry} from "./ITIP403Registry.sol";
+
+/// @title The interface for TIP-1028 escrow
+/// @notice Escrow holding blocked inbound TIP-20 transfers and mints until claimed
+interface ITIP1028Escrow {
+    /// @notice The kind of inbound operation that was blocked
+    /// @param TRANSFER A regular TIP-20 transfer
+    /// @param MINT A TIP-20 mint
+    enum InboundKind {
+        TRANSFER,
+        MINT
+    }
+
+    /// @notice V1 claim receipt encoding for a blocked inbound
+    /// @param originator The original sender (transfer) or issuer (mint)
+    /// @param recipient The intended recipient of the blocked inbound
+    /// @param blockedAt The block number at which the inbound was blocked
+    /// @param blockedNonce The escrow-scoped nonce assigned to this blocked receipt
+    /// @param blockedReason The reason the inbound was blocked
+    /// @param kind Whether the blocked inbound was a transfer or mint
+    /// @param memo Application-specific memo attached to the inbound
+    struct ClaimReceiptV1 {
+        address originator;
+        address recipient;
+        uint64 blockedAt;
+        uint64 blockedNonce;
+        ITIP403Registry.BlockedReason blockedReason;
+        InboundKind kind;
+        bytes32 memo;
+    }
+
+    /// @notice Returns the escrowed balance for a specific blocked receipt
+    /// @param token The TIP-20 token address
+    /// @param recoveryAuthority The recovery authority that was assigned to the blocked receipt
+    /// @param receiptVersion The version of the claim receipt encoding
+    /// @param receipt The ABI-encoded claim receipt
+    /// @return amount The escrowed balance for the receipt
+    function blockedReceiptBalance(
+        address token,
+        address recoveryAuthority,
+        uint8 receiptVersion,
+        bytes calldata receipt
+    ) external view returns (uint256 amount);
+
+    /// @notice Claims a blocked receipt, releasing escrowed funds to the specified address
+    /// @param token The TIP-20 token address
+    /// @param recoveryAuthority The recovery authority that was assigned to the blocked receipt
+    /// @param receiptVersion The version of the claim receipt encoding
+    /// @param receipt The ABI-encoded claim receipt
+    /// @param to The address to release the escrowed funds to
+    function claim(address token, address recoveryAuthority, uint8 receiptVersion, bytes calldata receipt, address to)
+        external;
+
+    /// @notice Emitted when an inbound transfer or mint is blocked by a receive policy
+    /// @param token The TIP-20 token address
+    /// @param from The sender of the blocked inbound
+    /// @param receiver The receiver whose receive policy blocked the inbound
+    /// @param receiptVersion The version of the claim receipt encoding
+    /// @param blockedNonce The escrow-scoped nonce assigned to this blocked receipt
+    /// @param blockedAt The block number at which the inbound was blocked
+    /// @param recipient The intended recipient of the blocked inbound
+    /// @param amount The amount of tokens blocked
+    /// @param blockedReason The reason the inbound was blocked
+    /// @param recoveryAuthority The recovery authority assigned to the blocked receipt
+    /// @param memo Application-specific memo attached to the inbound
+    event TransferBlocked(
+        address indexed token,
+        address indexed from,
+        address indexed receiver,
+        uint8 receiptVersion,
+        uint64 blockedNonce,
+        uint64 blockedAt,
+        address recipient,
+        uint256 amount,
+        ITIP403Registry.BlockedReason blockedReason,
+        address recoveryAuthority,
+        bytes32 memo
+    );
+
+    /// @notice Emitted when a blocked receipt is claimed
+    /// @param token The TIP-20 token address
+    /// @param receiver The receiver whose escrow held the blocked funds
+    /// @param receiptVersion The version of the claim receipt encoding
+    /// @param blockedNonce The escrow-scoped nonce of the claimed receipt
+    /// @param blockedAt The block number at which the inbound was originally blocked
+    /// @param originator The original sender of the blocked inbound
+    /// @param recipient The intended recipient of the blocked inbound
+    /// @param recoveryAuthority The recovery authority that authorized the claim
+    /// @param caller The address that called claim
+    /// @param to The address that received the released funds
+    /// @param amount The amount of tokens released
+    event BlockedReceiptClaimed(
+        address indexed token,
+        address indexed receiver,
+        uint8 receiptVersion,
+        uint64 indexed blockedNonce,
+        uint64 blockedAt,
+        address originator,
+        address recipient,
+        address recoveryAuthority,
+        address caller,
+        address to,
+        uint256 amount
+    );
+
+    /// @notice Error when the caller is not authorized to claim the blocked receipt
+    error UnauthorizedClaimer();
+
+    /// @notice Error when the claim receipt is invalid or does not match any blocked receipt
+    error InvalidReceiptClaim();
+
+    /// @notice Error when the escrow balance is insufficient (already claimed or zero)
+    error InsufficientEscrowBalance();
+
+    /// @notice Error when the escrow address itself is used where it should not be
+    error EscrowAddressReserved();
+
+    /// @notice Error when the claim destination address is invalid
+    error InvalidClaimAddress();
+
+    /// @notice Error when the token address is invalid
+    error InvalidToken();
+}

src/interfaces/ITIP403Registry.sol

@@ -14,6 +14,16 @@ interface ITIP403Registry {
         COMPOUND
     }
 
+    /// @notice Reasons an inbound transfer can be blocked by a receive policy
+    /// @param NONE The transfer is not blocked
+    /// @param TOKEN_FILTER The token is not allowed by the token filter policy
+    /// @param RECEIVE_POLICY The sender is not allowed by the receive policy
+    enum BlockedReason {
+        NONE,
+        TOKEN_FILTER,
+        RECEIVE_POLICY
+    }
+
     /// @notice Data structure containing policy configuration
     /// @param policyType The type of policy (whitelist or blacklist)
     /// @param admin The address authorized to modify this policy
@@ -40,6 +50,12 @@ interface ITIP403Registry {
     /// @notice TIP-1022 virtual addresses cannot be used as literal policy members
     error VirtualAddressNotAllowed();
 
+    /// @notice Error when a receive policy references an incompatible policy type
+    error InvalidReceivePolicyType();
+
+    /// @notice Error when the recovery authority address is invalid
+    error InvalidRecoveryAuthority();
+
     /// @notice Emitted when a policy's admin is updated
     /// @param policyId The ID of the policy that was updated
     /// @param updater The address that performed the update
@@ -132,6 +148,15 @@ interface ITIP403Registry {
         uint64 mintRecipientPolicyId
     );
 
+    /// @notice Emitted when an account's receive policy is updated
+    /// @param account The account whose receive policy was updated
+    /// @param senderPolicyId The sender policy ID for the receive policy
+    /// @param tokenFilterId The token filter policy ID for the receive policy
+    /// @param recoveryAuthority The recovery authority address for blocked receipts
+    event ReceivePolicyUpdated(
+        address indexed account, uint64 senderPolicyId, uint64 tokenFilterId, address recoveryAuthority
+    );
+
     /// @notice TIP-1015: Creates a new immutable compound policy
     /// @param senderPolicyId Policy ID to check for transfer senders
     /// @param recipientPolicyId Policy ID to check for transfer recipients
@@ -168,4 +193,45 @@ interface ITIP403Registry {
         external
         view
         returns (uint64 senderPolicyId, uint64 recipientPolicyId, uint64 mintRecipientPolicyId);
+
+    // =========================================================================
+    //                      TIP-1028: Receive Policies
+    // =========================================================================
+
+    /// @notice Returns the receive policy configuration for an account
+    /// @param account The account to query
+    /// @return hasReceivePolicy Whether the account has a receive policy set
+    /// @return senderPolicyId The sender policy ID for inbound transfer authorization
+    /// @return senderPolicyType The type of the sender policy
+    /// @return tokenFilterId The token filter policy ID
+    /// @return tokenFilterType The type of the token filter policy
+    /// @return recoveryAuthority The recovery authority address for blocked receipts
+    function receivePolicy(address account)
+        external
+        view
+        returns (
+            bool hasReceivePolicy,
+            uint64 senderPolicyId,
+            PolicyType senderPolicyType,
+            uint64 tokenFilterId,
+            PolicyType tokenFilterType,
+            address recoveryAuthority
+        );
+
+    /// @notice Validates an inbound transfer against the receiver's receive policy
+    /// @param token The TIP-20 token being transferred
+    /// @param sender The sender of the transfer
+    /// @param receiver The receiver of the transfer
+    /// @return authorized Whether the transfer is authorized
+    /// @return blockedReason The reason the transfer was blocked (NONE if authorized)
+    function validateReceivePolicy(address token, address sender, address receiver)
+        external
+        view
+        returns (bool authorized, BlockedReason blockedReason);
+
+    /// @notice Sets the caller's receive policy for inbound transfers
+    /// @param senderPolicyId The sender policy ID to use for inbound transfer authorization
+    /// @param tokenFilterId The token filter policy ID
+    /// @param recoveryAuthority The recovery authority address for blocked receipts
+    function setReceivePolicy(uint64 senderPolicyId, uint64 tokenFilterId, address recoveryAuthority) external;
 }