suggestions

Author: ozgunozerk

ecosystem/sep-0057.md

@@ -96,7 +96,12 @@ with regulatory required features: freezing, pausing and recovery.
 
 ### Architecture Overview
 
-The T-REX token contract requires only **two external functions** to operate:
+The T-REX token integrates with **two external contracts** — a Compliance
+contract and an Identity Verifier contract — through a small set of hooks. The
+token calls these hooks during transfers, minting, burning, and recovery; the
+contracts behind them encapsulate all regulatory logic.
+
+For example, the two most visible hooks are:
 
 ```rust
 // Compliance validation - returns true if transfer is allowed
@@ -106,11 +111,20 @@ fn can_transfer(e: &Env, from: Address, to: Address, amount: i128, token: Addres
 fn verify_identity(e: &Env, user_address: &Address);
 ```
 
-- `can_transfer()` is expected to be exposed from a "Compliance" contract.
-- `verify_identity()` is expected to be exposed from an "Identity Verifier"
-  contract.
+The full hook set is specified later in this document:
+
+- The **Compliance** contract exposes pre-validation hooks (`can_transfer`,
+  `can_create`) and post-event state-update hooks (`transferred`, `created`,
+  `destroyed`). Pre-validation hooks default to `true` and post-event hooks
+  default to no-ops when no compliance modules are registered, so a token with
+  no modules behaves as if compliance is permissive. See the
+  [Compliance Trait](#the-compliance-trait) section for the complete interface.
+- The **Identity Verifier** contract exposes `verify_identity` and
+  `recovery_target` (the latter is consumed by `recover_balance`). See the
+  [IdentityVerifier Trait](#the-identityverifier-trait) section for the
+  complete interface.
 
-These functions are **deliberately abstracted** as implementation details,
+These hooks are **deliberately abstracted** as implementation details,
 enabling:
 
 - **Regulatory Flexibility**: Different jurisdictions can implement different
@@ -120,9 +134,9 @@ enabling:
 - **Cost Optimization**: Shared contracts across multiple tokens
 - **Future-Proofing**: New compliance approaches without interface changes
 
-In other words, the only thing required by this T-REX design, is that the token
-should be able to call these expected functions made available by the
-compliance and identity verification contracts.
+In other words, the only thing required by this T-REX design is that the token
+be able to call the hooks exposed by the compliance and identity verification
+contracts.
 
 ### Contract Connection Interface
 
@@ -249,7 +263,7 @@ pub trait RWAToken: TokenInterface {
     ///
     /// * topics - `["transfer", old_account: Address, new_account: Address]`
     /// * data - `[amount: i128]`
-    /// * topics - `["recovery", old_account: Address, new_account: Address]`
+    /// * topics - `["recovery_success", old_account: Address, new_account: Address]`
     /// * data - `[]`
     fn recover_balance(
         e: &Env,
@@ -272,8 +286,7 @@ pub trait RWAToken: TokenInterface {
     ///
     /// # Events
     ///
-    /// * topics - `["address_frozen", user_address: Address, is_frozen: bool,
-    ///   operator: Address]`
+    /// * topics - `["address_frozen", user_address: Address, is_frozen: bool]`
     /// * data - `[]`
     fn set_address_frozen(e: &Env, user_address: Address, freeze: bool, operator: Address);
 
@@ -704,6 +717,24 @@ token contract. This allows a single compliance contract to serve multiple
 tokens while maintaining per-token state and applying token-specific business
 logic (e.g., per-token transfer limits, per-token balance tracking).
 
+**Validity requirements for state-update hooks:**
+
+Because `transferred`, `created`, and `destroyed` mutate per-token state, they
+MUST be protected against caller spoofing of the `token` parameter. Concretely,
+implementations MUST:
+
+1. Require authorization from `token` (e.g., `token.require_auth()`), so the
+   call can only originate from the token contract whose state is being
+   updated.
+2. Reject calls where `token` is not bound to the compliance contract.
+
+Without both checks, an attacker could call a state-update hook directly with a
+`token` they do not control and corrupt that token's per-module state (e.g.,
+transfer counters, holding-period trackers). Read-only hooks (`can_transfer`,
+`can_create`) cannot corrupt state, but implementations SHOULD apply the same
+checks for consistency and to avoid leaking module-internal decisions to
+untrusted callers.
+
 #### Hook-Based Architecture
 
 The compliance system uses a sophisticated hook mechanism: