From 3a4ce57522f4d59cf491dcebed5086edcb588478 Mon Sep 17 00:00:00 2001 From: Ozgun Ozerk Date: Thu, 11 Sep 2025 16:29:24 +0300 Subject: [PATCH 1/9] rwa sep discussion --- RWA-SEP.md | 458 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 458 insertions(+) create mode 100644 RWA-SEP.md diff --git a/RWA-SEP.md b/RWA-SEP.md new file mode 100644 index 00000000..c01a796e --- /dev/null +++ b/RWA-SEP.md @@ -0,0 +1,458 @@ + +## Preamble +``` +SEP: 0051 +Title: Real World Asset (RWA) Tokens +Author: OpenZeppelin, Boyan Barakov <@brozorec>, Özgün Özerk <@ozgunozerk> +Status: Draft +Created: 2025-01-10 +Updated: 2025-01-10 +Version: 0.1.0 +Discussion: TBD +``` + +## Summary +This proposal defines a standard contract interface for Real World Asset (RWA) tokens on Stellar. RWA tokens represent tokenized real-world assets such as securities, bonds, real estate, or other regulated financial instruments that require compliance with regulatory frameworks. The interface is based on the T-REX (Token for Regulated Exchanges) standard and extends fungible token functionality with comprehensive regulatory compliance features. + +## Motivation +Real World Assets (RWAs) represent a significant opportunity for blockchain adoption, enabling the tokenization of traditional financial instruments and physical assets. However, unlike standard fungible tokens, RWAs must comply with complex regulatory requirements including but not limited to: + +- **Know Your Customer (KYC) and Anti-Money Laundering (AML)** compliance +- **Identity verification** and investor accreditation +- **Freezing capabilities** for regulatory enforcement +- **Recovery mechanisms** for lost or compromised wallets +- **Compliance hooks** for regulatory reporting + +The T-REX standard provides a comprehensive framework for compliant security tokens. This SEP adapts T-REX to the Stellar ecosystem, enabling: + +- **Modular compliance framework** with pluggable compliance rules +- **Flexible identity verification** supporting multiple approaches (claim-based, Merkle tree, zero-knowledge, etc.) +- **Sophisticated freezing mechanisms** at both address and token levels +- **Administrative controls** with role-based access control (RBAC) +- **Recovery systems** for institutional-grade wallet management +- **Compliance hooks** for regulatory reporting + +## Flexibility and Extensibility + +The RWA Token contract is designed to be flexible and extensible, allowing for easy integration with a variety of identity registry and compliance frameworks. This flexibility is achieved through a modular architecture with loose coupling between components: + +- **Identity Verification**: Supports multiple implementation approaches including Merkle-Tree based systems, Zero-Knowledge proof systems, claim-based verification, and custom approaches +- **Compliance Framework**: Pluggable compliance rules that can be customized based on regulatory requirements +- **Modular Design**: Clean separation between the core RWA token functionality and external compliance/identity contracts + +By establishing this standard, RWA tokens can interact seamlessly with DeFi protocols, custody solutions, and compliance infrastructure while maintaining full regulatory compliance. + +## Interface +The RWA token interface extends the standard fungible token functionality with regulatory compliance features. The interface is designed to be modular, allowing implementations to plug in different compliance rules, identity verification systems, and administrative controls based on specific regulatory requirements. + +### Architecture Overview + +The main RWA contract expects two key functions to be available from external contracts: + +- `fn can_transfer(e: &Env, from: Address, to: Address, amount: i128) -> bool;` for compliance validation +- `fn verify_identity(e: &Env, user_address: &Address);` for identity verification + +These functions are deliberately marked as implementation details to provide flexibility and allow for alternate approaches based on different business needs. The RWA Token interface provides setter and getter functions for these external contracts: + +**Compliance Contract:** +- `set_compliance(e: &Env, compliance: Address, operator: Address)` +- `compliance(e: &Env) -> Address` + +**Identity Verifier Contract:** +- `set_identity_verifier(e: &Env, identity_verifier: Address, operator: Address)` +- `identity_verifier(e: &Env) -> Address` + +```rust +use soroban_sdk::{Address, Env, String}; +use stellar_contract_utils::pausable::Pausable; +use crate::fungible::FungibleToken; + +/// Real World Asset Token Trait +/// +/// The `RWAToken` trait defines the core functionality for Real World Asset +/// tokens, implementing the T-REX standard for regulated securities. It +/// provides a comprehensive interface for managing compliant token transfers, +/// identity verification, compliance rules, and administrative controls. +/// +/// This trait extends basic fungible token functionality with regulatory +/// features required for security tokens. +pub trait RWAToken: Pausable + FungibleToken { + // ################## CORE TOKEN FUNCTIONS ################## + + /// Forces a transfer of tokens between two whitelisted wallets. + /// This function can only be called by the operator with necessary + /// privileges. RBAC checks are expected to be enforced on the + /// `operator`. + /// + /// # Arguments + /// + /// * `e` - Access to the Soroban environment. + /// * `from` - The address of the sender. + /// * `to` - The address of the receiver. + /// * `amount` - The number of tokens to transfer. + /// * `operator` - The address of the operator. + /// + /// # Events + /// + /// * topics - `["transfer", from: Address, to: Address]` + /// * data - `[amount: i128]` + fn forced_transfer(e: &Env, from: Address, to: Address, amount: i128, operator: Address); + + /// Mints tokens to a wallet. Tokens can only be minted to verified + /// addresses. This function can only be called by the operator with + /// necessary privileges. RBAC checks are expected to be enforced on the + /// `operator`. + /// + /// # Arguments + /// + /// * `e` - Access to the Soroban environment. + /// * `to` - Address to mint the tokens to. + /// * `amount` - Amount of tokens to mint. + /// * `operator` - The address of the operator. + /// + /// # Events + /// + /// * topics - `["mint", to: Address]` + /// * data - `[amount: i128]` + fn mint(e: &Env, to: Address, amount: i128, operator: Address); + + /// Burns tokens from a wallet. + /// This function can only be called by the operator with necessary + /// privileges. RBAC checks are expected to be enforced on the + /// `operator`. + /// + /// # Arguments + /// + /// * `e` - Access to the Soroban environment. + /// * `user_address` - Address to burn the tokens from. + /// * `amount` - Amount of tokens to burn. + /// * `operator` - The address of the operator. + /// + /// # Events + /// + /// * topics - `["burn", user_address: Address]` + /// * data - `[amount: i128]` + fn burn(e: &Env, user_address: Address, amount: i128, operator: Address); + + /// Recovery function used to force transfer tokens from a lost wallet + /// to a new wallet for an investor. + /// This function can only be called by the operator with necessary + /// privileges. RBAC checks are expected to be enforced on the + /// `operator`. + /// + /// # Arguments + /// + /// * `e` - Access to the Soroban environment. + /// * `lost_wallet` - The wallet that the investor lost. + /// * `new_wallet` - The newly provided wallet for token transfer. + /// * `investor_onchain_id` - The onchain ID of the investor asking for + /// recovery. + /// * `operator` - The address of the operator. + /// + /// # Events + /// + /// * topics - `["transfer", lost_wallet: Address, new_wallet: Address]` + /// * data - `[amount: i128]` + /// * topics - `["recovery", lost_wallet: Address, new_wallet: Address, + /// investor_onchain_id: Address]` + /// * data - `[]` + fn recovery_address( + e: &Env, + lost_wallet: Address, + new_wallet: Address, + investor_onchain_id: Address, + operator: Address, + ) -> bool; + + /// Sets the frozen status for an address. Frozen addresses cannot send or + /// receive tokens. This function can only be called by the operator + /// with necessary privileges. RBAC checks are expected to be enforced + /// on the `operator`. + /// + /// # Arguments + /// + /// * `e` - Access to the Soroban environment. + /// * `user_address` - The address for which to update frozen status. + /// * `freeze` - Frozen status of the address. + /// * `operator` - The address of the operator. + /// + /// # Events + /// + /// * topics - `["address_frozen", user_address: Address, is_frozen: bool, + /// operator: Address]` + /// * data - `[]` + fn set_address_frozen(e: &Env, user_address: Address, freeze: bool, operator: Address); + + /// Freezes a specified amount of tokens for a given address. + /// This function can only be called by the operator with necessary + /// privileges. RBAC checks are expected to be enforced on the + /// `operator`. + /// + /// # Arguments + /// + /// * `e` - Access to the Soroban environment. + /// * `user_address` - The address for which to freeze tokens. + /// * `amount` - Amount of tokens to be frozen. + /// * `operator` - The address of the operator. + /// + /// # Events + /// + /// * topics - `["tokens_frozen", user_address: Address]` + /// * data - `[amount: i128]` + fn freeze_partial_tokens(e: &Env, user_address: Address, amount: i128, operator: Address); + + /// Unfreezes a specified amount of tokens for a given address. + /// This function can only be called by the operator with necessary + /// privileges. RBAC checks are expected to be enforced on the + /// `operator`. + /// + /// # Arguments + /// + /// * `e` - Access to the Soroban environment. + /// * `user_address` - The address for which to unfreeze tokens. + /// * `amount` - Amount of tokens to be unfrozen. + /// * `operator` - The address of the operator. + /// + /// # Events + /// + /// * topics - `["tokens_unfrozen", user_address: Address]` + /// * data - `[amount: i128]` + fn unfreeze_partial_tokens(e: &Env, user_address: Address, amount: i128, operator: Address); + + /// Returns the freezing status of a wallet. + /// + /// # Arguments + /// + /// * `e` - Access to the Soroban environment. + /// * `user_address` - The address of the wallet to check. + fn is_frozen(e: &Env, user_address: Address) -> bool; + + /// Returns the amount of tokens that are partially frozen on a wallet. + /// + /// # Arguments + /// + /// * `e` - Access to the Soroban environment. + /// * `user_address` - The address of the wallet to check. + fn get_frozen_tokens(e: &Env, user_address: Address) -> i128; + + // ################## METADATA FUNCTIONS ################## + + /// Returns the version of the token (T-REX version). + fn version(e: &Env) -> String; + + /// Returns the address of the onchain ID of the token. + fn onchain_id(e: &Env) -> Address; + + // ################## COMPLIANCE AND IDENTITY FUNCTIONS ################## + + /// Sets the compliance contract of the token. + /// This function can only be called by the operator with necessary + /// privileges. RBAC checks are expected to be enforced on the + /// `operator`. + /// + /// # Arguments + /// + /// * `e` - Access to the Soroban environment. + /// * `compliance` - The address of the compliance contract to set. + /// * `operator` - The address of the operator. + /// + /// # Events + /// + /// * topics - `["compliance_set", compliance: Address]` + /// * data - `[]` + fn set_compliance(e: &Env, compliance: Address, operator: Address); + + /// Sets the identity verifier contract of the token. + /// + /// This function can only be called by the operator with necessary + /// privileges. RBAC checks are expected to be enforced on the + /// `operator`. + /// + /// # Arguments + /// + /// * `e` - Access to the Soroban environment. + /// * `identity_verifier` - The address of the identity verifier contract to + /// set. + /// * `operator` - The address of the operator. + /// + /// # Events + /// + /// * topics - `["identity_verifier_set", identity_verifier: Address]` + /// * data - `[]` + fn set_identity_verifier(e: &Env, identity_verifier: Address, operator: Address); + + /// Returns the Compliance contract linked to the token. + fn compliance(e: &Env) -> Address; + + /// Returns the Identity Verifier contract linked to the token. + fn identity_verifier(e: &Env) -> Address; +} +``` + +## Events + +### Transfer Event +The transfer event is emitted when RWA tokens are transferred from one address to another, including forced transfers and recovery operations. + +**Topics:** +- `Symbol` with value `"transfer"` +- `Address`: the address holding the tokens that were transferred +- `Address`: the address that received the tokens + +**Data:** +- `i128`: the amount of tokens transferred + +### Mint Event +The mint event is emitted when RWA tokens are minted to a verified address. + +**Topics:** +- `Symbol` with value `"mint"` +- `Address`: the address receiving the newly minted tokens + +**Data:** +- `i128`: the amount of tokens minted + +### Burn Event +The burn event is emitted when RWA tokens are burned from an address. + +**Topics:** +- `Symbol` with value `"burn"` +- `Address`: the address from which tokens were burned + +**Data:** +- `i128`: the amount of tokens burned + +### Recovery Event +The recovery event is emitted when tokens are successfully recovered from a lost wallet to a new wallet. + +**Topics:** +- `Symbol` with value `"recovery"` +- `Address`: the lost wallet address +- `Address`: the new wallet address +- `Address`: the investor's onchain ID + +**Data:** +- Empty array `[]` + +### Address Frozen Event +The address frozen event is emitted when an address is frozen or unfrozen. + +**Topics:** +- `Symbol` with value `"address_frozen"` +- `Address`: the address that was frozen/unfrozen +- `bool`: the frozen status (true for frozen, false for unfrozen) +- `Address`: the operator who performed the action + +**Data:** +- Empty array `[]` + +### Tokens Frozen Event +The tokens frozen event is emitted when a specific amount of tokens is frozen for an address. + +**Topics:** +- `Symbol` with value `"tokens_frozen"` +- `Address`: the address for which tokens were frozen + +**Data:** +- `i128`: the amount of tokens frozen + +### Tokens Unfrozen Event +The tokens unfrozen event is emitted when a specific amount of tokens is unfrozen for an address. + +**Topics:** +- `Symbol` with value `"tokens_unfrozen"` +- `Address`: the address for which tokens were unfrozen + +**Data:** +- `i128`: the amount of tokens unfrozen + +### Compliance Set Event +The compliance set event is emitted when the compliance contract is updated. + +**Topics:** +- `Symbol` with value `"compliance_set"` +- `Address`: the address of the new compliance contract + +**Data:** +- Empty array `[]` + +### Identity Verifier Set Event +The identity verifier set event is emitted when the identity verifier contract is updated. + +**Topics:** +- `Symbol` with value `"identity_verifier_set"` +- `Address`: the address of the new identity verifier contract + +**Data:** +- Empty array `[]` + +## Notes on Regulatory Compliance + +### Identity Verification +RWA tokens require robust identity verification mechanisms to ensure compliance with KYC/AML regulations. The identity verification system is designed to be flexible and support multiple implementation approaches. Below is an example of the Claim-Based Identity Verification + +#### Claim-Based Implementation +The suggested claim-based implementation uses external contracts: +- **Claim Topics and Issuers**: Manages trusted claim issuers and defines claim topics (e.g., KYC=1, AML=2, Accredited Investor=3) +- **Identity Registry Storage**: Maps wallet addresses to onchain identities (optional, not required for all approaches) +- **Identity Claims**: Validates cryptographic claims with support for multiple signature schemes (Ed25519, Secp256k1, Secp256r1) + +### Compliance Framework +The modular compliance framework allows for pluggable compliance rules that can be customized based on regulatory requirements: + +- **Transfer Validation**: Before any transfer, the compliance contract validates whether the transfer meets regulatory requirements +- **Mint Validation**: Before any issuing of new tokens, the compliance contract validates whether the mint operation meets regulatory requirements +- **Compliance Hooks**: The system provides hooks for `Transferred`, `Created`, and `Destroyed` events + + +### Freezing Mechanisms +RWA tokens support sophisticated freezing capabilities for regulatory enforcement: + +- **Address-Level Freezing**: Completely freeze an address, preventing all token operations +- **Partial Token Freezing**: Freeze specific amounts of tokens while allowing operations on unfrozen balances +- **Regulatory Enforcement**: Freezing can be triggered by regulatory requirements, suspicious activity, or legal proceedings + +### Recovery System +The recovery system enables institutional-grade wallet management: + +- **Identity-Based Recovery**: Recovery requires verification of the investor's onchain identity +- **Operator Authorization**: Recovery operations must be performed by authorized operators with proper RBAC permissions +- **Audit Trail**: All recovery operations are logged with comprehensive event emission for regulatory reporting + +## Notes on Role-Based Access Control (RBAC) + +RWA tokens implement comprehensive RBAC to ensure that sensitive operations are only performed by authorized entities: + +- **Operator Roles**: Different operator roles can be defined with specific permissions for minting, burning, freezing, recovery, and compliance management +- **Administrative Functions**: All administrative functions require proper operator authorization +- **Compliance Integration**: RBAC permissions can be integrated with compliance rules to ensure regulatory requirements are met + +## Notes on Integration with Fungible Tokens + +RWA tokens extend the standard fungible token interface while adding regulatory compliance features: + +- **Base Functionality**: All standard fungible token operations (transfer, approve, allowance) are available +- **Compliance Overrides**: Standard operations are enhanced with compliance checks and identity verification +- **Pausable Operations**: The entire token can be paused for emergency situations while maintaining compliance + +## Security Considerations + +### Access Control +- All administrative functions must implement proper RBAC checks +- Operator permissions should be carefully managed and regularly audited +- Multi-signature schemes should be considered for high-privilege operations + +### Identity Verification +- Identity claims must be cryptographically verified using trusted issuers +- Claim expiration and revocation mechanisms should be implemented +- Regular re-verification of investor identities may be required based on regulatory requirements + +### Compliance Validation +- All token operations should be validated against current compliance rules +- Compliance contracts should be upgradeable to adapt to changing regulations +- Emergency pause mechanisms should be available for regulatory compliance + +### Freezing and Recovery +- Freezing operations should be logged and auditable +- Recovery operations should require multiple levels of authorization +- Time-locked recovery mechanisms can provide additional security for high-value operations From 381da9a99ee340af88f94516d5e5ef19c086099e Mon Sep 17 00:00:00 2001 From: Ozgun Ozerk Date: Tue, 23 Sep 2025 15:58:42 +0300 Subject: [PATCH 2/9] rwa sep updated --- RWA-SEP.md | 410 ++++++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 342 insertions(+), 68 deletions(-) diff --git a/RWA-SEP.md b/RWA-SEP.md index c01a796e..929123ba 100644 --- a/RWA-SEP.md +++ b/RWA-SEP.md @@ -12,7 +12,9 @@ Discussion: TBD ``` ## Summary -This proposal defines a standard contract interface for Real World Asset (RWA) tokens on Stellar. RWA tokens represent tokenized real-world assets such as securities, bonds, real estate, or other regulated financial instruments that require compliance with regulatory frameworks. The interface is based on the T-REX (Token for Regulated Exchanges) standard and extends fungible token functionality with comprehensive regulatory compliance features. +This proposal defines a standard contract interface for Real World Asset (RWA) tokens on Stellar, developed through collaboration between OpenZeppelin, Tokeny, and Stellar. RWA tokens represent tokenized real-world assets such as securities, bonds, real estate, or other regulated financial instruments that require compliance with regulatory frameworks. + +This standard is based on the T-REX (Token for Regulated Exchanges) framework but introduces significant architectural improvements for flexibility and modularity. ## Motivation Real World Assets (RWAs) represent a significant opportunity for blockchain adoption, enabling the tokenization of traditional financial instruments and physical assets. However, unlike standard fungible tokens, RWAs must comply with complex regulatory requirements including but not limited to: @@ -32,35 +34,94 @@ The T-REX standard provides a comprehensive framework for compliant security tok - **Recovery systems** for institutional-grade wallet management - **Compliance hooks** for regulatory reporting -## Flexibility and Extensibility +## Architecture Overview + +Based on extensive research and collaboration with industry experts, this RWA standard introduces a fundamentally different approach to regulatory compliance in tokenized assets. The architecture is built around **loose coupling** and **implementation abstraction**, addressing key limitations identified in existing standards. + +### Core Design Principles + +1. **Separation of Concerns**: Core token functionality is cleanly separated from compliance and identity verification +2. **Implementation Flexibility**: Compliance and identity systems are treated as pluggable implementation details +3. **Shared Infrastructure**: Components can be shared across multiple token contracts to reduce deployment costs +4. **Regulatory Adaptability**: The system can adapt to different regulatory frameworks without core changes -The RWA Token contract is designed to be flexible and extensible, allowing for easy integration with a variety of identity registry and compliance frameworks. This flexibility is achieved through a modular architecture with loose coupling between components: +### Component Architecture -- **Identity Verification**: Supports multiple implementation approaches including Merkle-Tree based systems, Zero-Knowledge proof systems, claim-based verification, and custom approaches -- **Compliance Framework**: Pluggable compliance rules that can be customized based on regulatory requirements -- **Modular Design**: Clean separation between the core RWA token functionality and external compliance/identity contracts +The RWA ecosystem consists of several interconnected but loosely coupled components: + +``` +┌─────────────────┐ ┌──────────────────┐ ┌─────────────────────┐ +│ RWA Token │───▶│ Compliance │───▶│ Compliance Modules │ +│ (Core) │ │ Contract │ │ (Pluggable Rules) │ +└─────────────────┘ └──────────────────┘ └─────────────────────┘ + │ + ▼ +┌─────────────────┐ ┌──────────────────┐ ┌──────────────────┐ +│ Identity │───▶│ Claim Topics & │ │ Custom Identity │ +│ Verifier │ │ Issuers │───▶│ Registry │ +└─────────────────┘ └──────────────────┘ └──────────────────┘ +``` -By establishing this standard, RWA tokens can interact seamlessly with DeFi protocols, custody solutions, and compliance infrastructure while maintaining full regulatory compliance. +### Flexibility Through Abstraction + +The architecture supports multiple implementation strategies: + +- **Identity Verification**: Merkle trees, Zero-Knowledge proofs, claim-based systems, or custom approaches +- **Compliance Rules**: Modular hook-based system supporting diverse regulatory requirements +- **Access Control**: Integration with external RBAC systems + +This design enables the same core RWA interface to work with vastly different regulatory and technical requirements. ## Interface -The RWA token interface extends the standard fungible token functionality with regulatory compliance features. The interface is designed to be modular, allowing implementations to plug in different compliance rules, identity verification systems, and administrative controls based on specific regulatory requirements. + +The RWA token interface extends the **fungible token** functionality with regulatory compliance features. ### Architecture Overview -The main RWA contract expects two key functions to be available from external contracts: +The RWA Token contract requires only **two external functions** to operate: -- `fn can_transfer(e: &Env, from: Address, to: Address, amount: i128) -> bool;` for compliance validation -- `fn verify_identity(e: &Env, user_address: &Address);` for identity verification +```rust +// Compliance validation - returns true if transfer is allowed +fn can_transfer(e: &Env, from: Address, to: Address, amount: i128) -> bool; -These functions are deliberately marked as implementation details to provide flexibility and allow for alternate approaches based on different business needs. The RWA Token interface provides setter and getter functions for these external contracts: +// Identity verification - panics if user is not verified +fn verify_identity(e: &Env, user_address: &Address); +``` -**Compliance Contract:** -- `set_compliance(e: &Env, compliance: Address, operator: Address)` -- `compliance(e: &Env) -> Address` +- `can_transfer()` is expected to be exposed from a compliance contract. +- `verify_identity()` is expected to be exposed from an identity verifier contract. -**Identity Verifier Contract:** -- `set_identity_verifier(e: &Env, identity_verifier: Address, operator: Address)` -- `identity_verifier(e: &Env) -> Address` +These functions are **deliberately abstracted** as implementation details, enabling: +- **Regulatory Flexibility**: Different jurisdictions can implement different compliance logic +- **Technical Flexibility**: Various identity verification approaches (ZK, Merkle trees, claims) +- **Cost Optimization**: Shared contracts across multiple tokens +- **Future-Proofing**: New compliance approaches without interface changes + +In other words, the only thing required by this RWA token design, is that the RWA token should be able to call these expected functions made available by your compliance and identity verification contracts. + +### Contract Connection Interface + +The RWA Token provides simple setter/getter functions for external contracts: + +```rust +// Compliance Contract Management +fn set_compliance(e: &Env, compliance: Address, operator: Address); +fn compliance(e: &Env) -> Address; + +// Identity Verifier Contract Management +fn set_identity_verifier(e: &Env, identity_verifier: Address, operator: Address); +fn identity_verifier(e: &Env) -> Address; +``` + +### Integration Pattern + +To deploy a compliant RWA token: + +1. **Deploy Core RWA Token**: Implements the RWAToken trait +2. **Deploy/Connect Compliance Contract**: Implements compliance validation logic +3. **Deploy/Connect Identity Verifier**: Implements identity verification logic +4. **Configure Connections**: Use setter functions to link contracts +5. **Configure Rules**: Set up compliance modules and identity requirements ```rust use soroban_sdk::{Address, Env, String}; @@ -386,73 +447,286 @@ The identity verifier set event is emitted when the identity verifier contract i **Data:** - Empty array `[]` -## Notes on Regulatory Compliance +## Component Deep Dive + +### 1. Identity Verification System + +**Philosophy**: The entire identity stack is treated as an implementation detail, enabling maximum regulatory and technical flexibility. + +#### The IdentityVerifier Trait + +```rust +pub trait IdentityVerifier { + /// Core verification function - panics if user is not verified + fn verify_identity(e: &Env, user_address: &Address); + + // Setters and getters for the claim topics and issuers contract + fn set_claim_topics_and_issuers(e: &Env, contract: Address, operator: Address); + fn claim_topics_and_issuers(e: &Env) -> Address; +} +``` + +#### Implementation Strategies + +Different regulatory environments may require different approaches. Here are some examples: + +**1. Claim-Based Verification (Reference Implementation)** +- **Use Case**: Traditional KYC/AML with trusted issuers +- **Components**: ClaimTopicsAndIssuers + IdentityRegistryStorage + IdentityClaims +- **Benefits**: Familiar to regulators, rich metadata support + +**2. Merkle Tree Verification** +- **Use Case**: Privacy-focused compliance with efficient proofs +- **Components**: ClaimTopicsAndIssuers + Merkle root storage + proof validation +- **Benefits**: Minimal storage, efficient verification + +**3. Zero-Knowledge Verification** +- **Use Case**: Privacy-preserving compliance +- **Components**: ClaimTopicsAndIssuers + ZK circuit + proof verification +- **Benefits**: Maximum privacy, selective disclosure + +**4. Custom Approaches** +- **Use Case**: Jurisdiction-specific requirements +- **Components**: ClaimTopicsAndIssuers + Custom verification logic +- **Benefits**: Tailored to specific regulatory needs + +#### Reference Implementation Architecture + +Our claim-based reference implementation demonstrates the full complexity of traditional RWA compliance: + +``` +┌─────────────────────┐ +│ Identity Verifier │ +│ (Orchestrator) │ +│ │ +└─────────────────────┘ + │ + ├────▶┌───────────────────────────┐ + │ │ Claim Topics & Issuers │ + │ │ (Shared Registry) │ + │ └───────────────────────────┘ + │ + ├────▶┌───────────────────────────┐ + │ │ Identity Registry Storage │ + │ │ (User Profiles) │ + │ └───────────────────────────┘ + │ + ├────▶┌───────────────────────────┐ + │ │ Identity Claims │ + │ │ (Claim Validation) │ + │ └───────────────────────────┘ + │ + └────▶┌───────────────────────────┐ + │ Claim Issuer │ + │ (Signature Validation) │ + └───────────────────────────┘ +``` + +**Key Components:** + +- **ClaimTopicsAndIssuers**: Merged registry managing both trusted issuers and required claim types (KYC=1, AML=2, etc.) +- **IdentityRegistryStorage**: Component storing identity profiles with country relations and metadata +- **IdentityClaims**: Validates cryptographic claims using multiple signature schemes (Ed25519, Secp256k1, Secp256r1) +- **ClaimIssuer**: Builds and validates cryptographic claims about user attributes + +### 2. Compliance System + +Modular hook-based architecture supporting diverse regulatory requirements through pluggable compliance modules. + +#### The Compliance Trait + +```rust +pub trait Compliance { + // Module management + fn add_module_to(e: &Env, hook: ComplianceHook, module: Address, operator: Address); + fn remove_module_from(e: &Env, hook: ComplianceHook, module: Address, operator: Address); + + // Validation hooks (READ-only) + fn can_transfer(e: &Env, from: Address, to: Address, amount: i128) -> bool; + fn can_create(e: &Env, to: Address, amount: i128) -> bool; + + // State update hooks (called after successful operations) + fn transferred(e: &Env, from: Address, to: Address, amount: i128); + fn created(e: &Env, to: Address, amount: i128); + fn destroyed(e: &Env, from: Address, amount: i128); +} +``` + +#### Hook-Based Architecture + +The compliance system uses a sophisticated hook mechanism: -### Identity Verification -RWA tokens require robust identity verification mechanisms to ensure compliance with KYC/AML regulations. The identity verification system is designed to be flexible and support multiple implementation approaches. Below is an example of the Claim-Based Identity Verification +```rust +pub enum ComplianceHook { + CanTransfer, // Pre-validation: Check if transfer meets compliance rules + CanCreate, // Pre-validation: Check if mint operation is compliant + Transferred, // Post-event: Update state after successful transfer + Created, // Post-event: Update state after successful mint + Destroyed, // Post-event: Update state after successful burn +} +``` -#### Claim-Based Implementation -The suggested claim-based implementation uses external contracts: -- **Claim Topics and Issuers**: Manages trusted claim issuers and defines claim topics (e.g., KYC=1, AML=2, Accredited Investor=3) -- **Identity Registry Storage**: Maps wallet addresses to onchain identities (optional, not required for all approaches) -- **Identity Claims**: Validates cryptographic claims with support for multiple signature schemes (Ed25519, Secp256k1, Secp256r1) +#### Compliance Module Examples -### Compliance Framework -The modular compliance framework allows for pluggable compliance rules that can be customized based on regulatory requirements: +**Transfer Limits Module**: +- Hook: `CanTransfer` + `Transferred` +- Logic: Enforce daily/monthly transfer limits per user -- **Transfer Validation**: Before any transfer, the compliance contract validates whether the transfer meets regulatory requirements -- **Mint Validation**: Before any issuing of new tokens, the compliance contract validates whether the mint operation meets regulatory requirements -- **Compliance Hooks**: The system provides hooks for `Transferred`, `Created`, and `Destroyed` events +**Jurisdiction Restrictions Module**: +- Hook: `CanTransfer` +- Logic: Block transfers between incompatible jurisdictions +**Holding Period Module**: +- Hook: `CanTransfer` + `Created` +- Logic: Enforce minimum holding periods for newly minted tokens + +**Investor Accreditation Module**: +- Hook: `CanCreate` +- Logic: Verify investor accreditation before minting + +#### Shared Compliance Infrastructure + +Compliance contracts are designed to be **shared across multiple RWA tokens**, reducing deployment costs and ensuring consistent regulatory enforcement: + +``` +┌─────────────┐ ┌─────────────────────┐ ┌──────────────────┐ +│ RWA Token A │───▶│ │───▶│ Transfer Limits │ +├─────────────┤ │ Shared Compliance │ │ Module │ +│ RWA Token B │───▶│ Contract │───▶├──────────────────┤ +├─────────────┤ │ │ │ Jurisdiction │ +│ RWA Token C │───▶│ │ │ Module │ +└─────────────┘ └─────────────────────┘ └──────────────────┘ +``` -### Freezing Mechanisms -RWA tokens support sophisticated freezing capabilities for regulatory enforcement: -- **Address-Level Freezing**: Completely freeze an address, preventing all token operations -- **Partial Token Freezing**: Freeze specific amounts of tokens while allowing operations on unfrozen balances -- **Regulatory Enforcement**: Freezing can be triggered by regulatory requirements, suspicious activity, or legal proceedings +### 3. Advanced Token Controls -### Recovery System -The recovery system enables institutional-grade wallet management: +#### Freezing Mechanisms + +Based on regulatory requirements research, the system supports multiple freezing strategies: + +**Address-Level Freezing**: +```rust +fn set_address_frozen(e: &Env, user_address: Address, freeze: bool, operator: Address); +fn is_frozen(e: &Env, user_address: Address) -> bool; +``` +- **Use Case**: Complete account suspension for regulatory investigations +- **Effect**: Prevents all token operations (send/receive) + +**Partial Token Freezing**: +```rust +fn freeze_partial_tokens(e: &Env, user_address: Address, amount: i128, operator: Address); +fn unfreeze_partial_tokens(e: &Env, user_address: Address, amount: i128, operator: Address); +fn get_frozen_tokens(e: &Env, user_address: Address) -> i128; +``` +- **Use Case**: Escrow scenarios, disputed transactions +- **Effect**: Freezes specific token amounts while allowing operations on remaining balance + +#### Recovery System + +Institutional-grade wallet recovery for high-value securities: + +```rust +fn recovery_address( + e: &Env, + lost_wallet: Address, + new_wallet: Address, + investor_onchain_id: Address, + operator: Address +) -> bool; +``` -- **Identity-Based Recovery**: Recovery requires verification of the investor's onchain identity -- **Operator Authorization**: Recovery operations must be performed by authorized operators with proper RBAC permissions -- **Audit Trail**: All recovery operations are logged with comprehensive event emission for regulatory reporting +**Recovery Process**: +1. **Identity Verification**: Verify investor's onchain identity matches the lost wallet +2. **Authorization Check**: Ensure operator has recovery permissions +3. **Balance Transfer**: Move all tokens from lost wallet to new wallet +4. **Identity Update**: Update identity registry to map new wallet to existing identity +5. **Audit Trail**: Emit comprehensive events for regulatory reporting -## Notes on Role-Based Access Control (RBAC) +#### Forced Transfers + +For regulatory compliance (court orders, sanctions): + +```rust +fn forced_transfer(e: &Env, from: Address, to: Address, amount: i128, operator: Address); +``` + +- **Use Case**: Court-ordered asset transfers, regulatory seizures +- **Authorization**: Requires operator with forced transfer permissions +- **Compliance**: Bypasses normal compliance validation checks (operator responsibility) + +### 4. Access Control & Governance + +RWA tokens require proper access control to ensure that sensitive operations are only performed by authorized entities: + +- **Operator Authorization**: All administrative functions require proper operator authorization using Soroban's built-in authorization mechanisms +- **Flexible Access Control**: While the RWA interface itself doesn't prescribe a specific access control model, implementations can integrate with external access control systems as needed +- **Compliance Integration**: Access control permissions should be integrated with compliance rules to ensure regulatory requirements are met + +## Integration & Interoperability + +### Fungible Token Compatibility + +RWA tokens maintain full compatibility with standard fungible token interfaces: + +```rust +pub trait RWAToken: Pausable + FungibleToken { + // RWA-specific functions... +} +``` + +**Standard Operations Enhanced**: +- `transfer()`: Enhanced with compliance validation and identity verification +- `approve()`: Standard ERC-20 style approvals work unchanged +- `allowance()`: Full allowance system compatibility +- `balance()`: Standard balance queries + +**Emergency Controls**: +- `pause()`/`unpause()`: Emergency pause functionality +- Paused state blocks all operations except queries + +### Deployment Patterns + +**Single Token Deployment**: +``` +RWA Token ──▶ Dedicated Compliance +``` + +**Multi-Token Suite**: +``` +RWA Token A ──┐ +RWA Token B ──┼──▶ Shared Compliance +RWA Token C ──┘ +``` -RWA tokens implement comprehensive RBAC to ensure that sensitive operations are only performed by authorized entities: +## Research-Driven Design Decisions -- **Operator Roles**: Different operator roles can be defined with specific permissions for minting, burning, freezing, recovery, and compliance management -- **Administrative Functions**: All administrative functions require proper operator authorization -- **Compliance Integration**: RBAC permissions can be integrated with compliance rules to ensure regulatory requirements are met +### Addressing ERC-3643 Limitations -## Notes on Integration with Fungible Tokens +Through our (OpenZeppelin) collaboration with Tokeny, Stellar, we identified key limitations in existing RWA standards: -RWA tokens extend the standard fungible token interface while adding regulatory compliance features: +**1. Tight Coupling Issues** +- **Problem**: ERC-3643 tightly couples identity verification with specific contract structures +- **Solution**: Abstract identity verification as pluggable implementation detail -- **Base Functionality**: All standard fungible token operations (transfer, approve, allowance) are available -- **Compliance Overrides**: Standard operations are enhanced with compliance checks and identity verification -- **Pausable Operations**: The entire token can be paused for emergency situations while maintaining compliance +**2. Inflexible Identity Models** +- **Problem**: Hardcoded ERC-734/735 identity contracts don't translate to all blockchain architectures +- **Solution**: Support multiple identity verification approaches (Merkle, ZK, claims, custom) -## Security Considerations +**3. Redundant Contract Hierarchies** +- **Problem**: Complex IdentityRegistry ↔ IdentityRegistryStorage relationships +- **Solution**: Direct access patterns -### Access Control -- All administrative functions must implement proper RBAC checks -- Operator permissions should be carefully managed and regularly audited -- Multi-signature schemes should be considered for high-privilege operations +**4. Limited Compliance Flexibility** +- **Problem**: Monolithic compliance validation +- **Solution**: Modular hook-based compliance system -### Identity Verification -- Identity claims must be cryptographically verified using trusted issuers -- Claim expiration and revocation mechanisms should be implemented -- Regular re-verification of investor identities may be required based on regulatory requirements +### Upgrade and Migration Strategies -### Compliance Validation -- All token operations should be validated against current compliance rules -- Compliance contracts should be upgradeable to adapt to changing regulations -- Emergency pause mechanisms should be available for regulatory compliance +**Compliance Evolution**: +- Modular compliance system supports rule updates without token redeployment +- New compliance modules can be added for evolving regulations -### Freezing and Recovery -- Freezing operations should be logged and auditable -- Recovery operations should require multiple levels of authorization -- Time-locked recovery mechanisms can provide additional security for high-value operations +**Identity System Migration**: +- Abstract identity verification enables migration between verification approaches +- Gradual migration strategies for existing user bases From 2c448be83aca02333a2caf40e4dbcbcc90b8f83e Mon Sep 17 00:00:00 2001 From: Ozgun Ozerk Date: Mon, 29 Sep 2025 10:13:48 +0300 Subject: [PATCH 3/9] suggestions part 1 --- RWA-SEP.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/RWA-SEP.md b/RWA-SEP.md index 929123ba..70b9d170 100644 --- a/RWA-SEP.md +++ b/RWA-SEP.md @@ -12,7 +12,7 @@ Discussion: TBD ``` ## Summary -This proposal defines a standard contract interface for Real World Asset (RWA) tokens on Stellar, developed through collaboration between OpenZeppelin, Tokeny, and Stellar. RWA tokens represent tokenized real-world assets such as securities, bonds, real estate, or other regulated financial instruments that require compliance with regulatory frameworks. +This proposal defines a standard contract interface for Real World Asset (RWA) tokens on Stellar. RWA tokens represent tokenized real-world assets such as securities, bonds, real estate, or other regulated financial instruments that require compliance with regulatory frameworks. This standard is based on the T-REX (Token for Regulated Exchanges) framework but introduces significant architectural improvements for flexibility and modularity. @@ -36,18 +36,18 @@ The T-REX standard provides a comprehensive framework for compliant security tok ## Architecture Overview -Based on extensive research and collaboration with industry experts, this RWA standard introduces a fundamentally different approach to regulatory compliance in tokenized assets. The architecture is built around **loose coupling** and **implementation abstraction**, addressing key limitations identified in existing standards. +Based on extensive research and collaboration with industry experts, this RWA standard introduces an approach built around **loose coupling** and **implementation abstraction**, addressing key limitations identified in existing standards. ### Core Design Principles 1. **Separation of Concerns**: Core token functionality is cleanly separated from compliance and identity verification 2. **Implementation Flexibility**: Compliance and identity systems are treated as pluggable implementation details -3. **Shared Infrastructure**: Components can be shared across multiple token contracts to reduce deployment costs +3. **Shared Infrastructure**: Components can be shared across multiple token contracts to reduce deployment and management costs 4. **Regulatory Adaptability**: The system can adapt to different regulatory frameworks without core changes ### Component Architecture -The RWA ecosystem consists of several interconnected but loosely coupled components: +The Stellar T-REX consists of several interconnected but loosely coupled components: ``` ┌─────────────────┐ ┌──────────────────┐ ┌─────────────────────┐ @@ -97,7 +97,7 @@ These functions are **deliberately abstracted** as implementation details, enabl - **Cost Optimization**: Shared contracts across multiple tokens - **Future-Proofing**: New compliance approaches without interface changes -In other words, the only thing required by this RWA token design, is that the RWA token should be able to call these expected functions made available by your compliance and identity verification contracts. +In other words, the only thing required by this RWA token design, is that the RWA token should be able to call these expected functions made available by the compliance and identity verification contracts. ### Contract Connection Interface @@ -115,7 +115,7 @@ fn identity_verifier(e: &Env) -> Address; ### Integration Pattern -To deploy a compliant RWA token: +To deploy a compliant RWA token and make it functional: 1. **Deploy Core RWA Token**: Implements the RWAToken trait 2. **Deploy/Connect Compliance Contract**: Implements compliance validation logic From 64bc5b456652ba2eadcd6708a5ba337d71e1fba7 Mon Sep 17 00:00:00 2001 From: Ozgun Ozerk Date: Mon, 29 Sep 2025 10:28:10 +0300 Subject: [PATCH 4/9] suggestions part 2 --- RWA-SEP.md | 42 +++--------------------------------------- 1 file changed, 3 insertions(+), 39 deletions(-) diff --git a/RWA-SEP.md b/RWA-SEP.md index 70b9d170..05eb8f21 100644 --- a/RWA-SEP.md +++ b/RWA-SEP.md @@ -14,7 +14,7 @@ Discussion: TBD ## Summary This proposal defines a standard contract interface for Real World Asset (RWA) tokens on Stellar. RWA tokens represent tokenized real-world assets such as securities, bonds, real estate, or other regulated financial instruments that require compliance with regulatory frameworks. -This standard is based on the T-REX (Token for Regulated Exchanges) framework but introduces significant architectural improvements for flexibility and modularity. +This standard is based on the T-REX (Token for Regulated Exchanges) framework, as implemented in ERC-3643 (https://github.com/ERC-3643/ERC-3643), but introduces significant architectural improvements for flexibility and modularity. ## Motivation Real World Assets (RWAs) represent a significant opportunity for blockchain adoption, enabling the tokenization of traditional financial instruments and physical assets. However, unlike standard fungible tokens, RWAs must comply with complex regulatory requirements including but not limited to: @@ -526,7 +526,7 @@ Our claim-based reference implementation demonstrates the full complexity of tra - **ClaimTopicsAndIssuers**: Merged registry managing both trusted issuers and required claim types (KYC=1, AML=2, etc.) - **IdentityRegistryStorage**: Component storing identity profiles with country relations and metadata -- **IdentityClaims**: Validates cryptographic claims using multiple signature schemes (Ed25519, Secp256k1, Secp256r1) +- **IdentityClaims**: Validates cryptographic claims using multiple signature schemes (Ed25519, Secp256k1, Secp256r1), with an emphasis on interoperability with the evolving OnchainID specification (https://github.com/ERC-3643/ERCs/blob/erc-oid/ERCS/erc-xxxx.md). - **ClaimIssuer**: Builds and validates cryptographic claims about user attributes ### 2. Compliance System @@ -663,42 +663,6 @@ RWA tokens require proper access control to ensure that sensitive operations are - **Flexible Access Control**: While the RWA interface itself doesn't prescribe a specific access control model, implementations can integrate with external access control systems as needed - **Compliance Integration**: Access control permissions should be integrated with compliance rules to ensure regulatory requirements are met -## Integration & Interoperability - -### Fungible Token Compatibility - -RWA tokens maintain full compatibility with standard fungible token interfaces: - -```rust -pub trait RWAToken: Pausable + FungibleToken { - // RWA-specific functions... -} -``` - -**Standard Operations Enhanced**: -- `transfer()`: Enhanced with compliance validation and identity verification -- `approve()`: Standard ERC-20 style approvals work unchanged -- `allowance()`: Full allowance system compatibility -- `balance()`: Standard balance queries - -**Emergency Controls**: -- `pause()`/`unpause()`: Emergency pause functionality -- Paused state blocks all operations except queries - -### Deployment Patterns - -**Single Token Deployment**: -``` -RWA Token ──▶ Dedicated Compliance -``` - -**Multi-Token Suite**: -``` -RWA Token A ──┐ -RWA Token B ──┼──▶ Shared Compliance -RWA Token C ──┘ -``` - ## Research-Driven Design Decisions ### Addressing ERC-3643 Limitations @@ -721,7 +685,7 @@ Through our (OpenZeppelin) collaboration with Tokeny, Stellar, we identified key - **Problem**: Monolithic compliance validation - **Solution**: Modular hook-based compliance system -### Upgrade and Migration Strategies +## Upgrade and Migration Strategies **Compliance Evolution**: - Modular compliance system supports rule updates without token redeployment From ee9912ebaa65417457c89eecf4c89c406d2ace73 Mon Sep 17 00:00:00 2001 From: Ozgun Ozerk Date: Mon, 29 Sep 2025 10:38:55 +0300 Subject: [PATCH 5/9] suggestions part 3 --- RWA-SEP.md | 46 ++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 44 insertions(+), 2 deletions(-) diff --git a/RWA-SEP.md b/RWA-SEP.md index 05eb8f21..063bf684 100644 --- a/RWA-SEP.md +++ b/RWA-SEP.md @@ -74,7 +74,7 @@ This design enables the same core RWA interface to work with vastly different re ## Interface -The RWA token interface extends the **fungible token** functionality with regulatory compliance features. +The RWA token interface extends the **fungible token** ([SEP-41](https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0041.md)) functionality with regulatory compliance features. ### Architecture Overview @@ -137,9 +137,16 @@ use crate::fungible::FungibleToken; /// /// This trait extends basic fungible token functionality with regulatory /// features required for security tokens. -pub trait RWAToken: Pausable + FungibleToken { +pub trait RWAToken: TokenInterface { // ################## CORE TOKEN FUNCTIONS ################## + /// Returns the total amount of tokens in circulation. + /// + /// # Arguments + /// + /// * `e` - Access to the Soroban environment. + fn total_supply(e: &Env) -> i128; + /// Forces a transfer of tokens between two whitelisted wallets. /// This function can only be called by the operator with necessary /// privileges. RBAC checks are expected to be enforced on the @@ -299,9 +306,17 @@ pub trait RWAToken: Pausable + FungibleToken { // ################## METADATA FUNCTIONS ################## /// Returns the version of the token (T-REX version). + /// + /// # Arguments + /// + /// * `e` - Access to the Soroban environment. fn version(e: &Env) -> String; /// Returns the address of the onchain ID of the token. + /// + /// # Arguments + /// + /// * `e` - Access to the Soroban environment. fn onchain_id(e: &Env) -> Address; // ################## COMPLIANCE AND IDENTITY FUNCTIONS ################## @@ -343,10 +358,37 @@ pub trait RWAToken: Pausable + FungibleToken { fn set_identity_verifier(e: &Env, identity_verifier: Address, operator: Address); /// Returns the Compliance contract linked to the token. + /// + /// # Arguments + /// + /// * `e` - Access to the Soroban environment. fn compliance(e: &Env) -> Address; /// Returns the Identity Verifier contract linked to the token. + /// + /// # Arguments + /// + /// * `e` - Access to the Soroban environment. fn identity_verifier(e: &Env) -> Address; + + // ################## PAUSABLE FUNCTIONS ################## + + /// Returns true if the contract is paused, and false otherwise. + /// + /// # Arguments + /// + /// * `e` - Access to Soroban environment. + /// * `caller` - The address of the caller. + fn pause(e: &Env, caller: Address); + + /// Triggers `Unpaused` state. + /// + /// # Arguments + /// + /// * `e` - Access to Soroban environment. + /// * `caller` - The address of the caller. + fn unpause(e: &Env, caller: Address); + } ``` From e6294110d1dbcf7b7f3fea62a840a32865a8b602 Mon Sep 17 00:00:00 2001 From: Ozgun Ozerk Date: Tue, 4 Nov 2025 19:22:46 +0300 Subject: [PATCH 6/9] suggestion --- RWA-SEP.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/RWA-SEP.md b/RWA-SEP.md index 063bf684..27593025 100644 --- a/RWA-SEP.md +++ b/RWA-SEP.md @@ -117,11 +117,11 @@ fn identity_verifier(e: &Env) -> Address; To deploy a compliant RWA token and make it functional: -1. **Deploy Core RWA Token**: Implements the RWAToken trait -2. **Deploy/Connect Compliance Contract**: Implements compliance validation logic -3. **Deploy/Connect Identity Verifier**: Implements identity verification logic -4. **Configure Connections**: Use setter functions to link contracts -5. **Configure Rules**: Set up compliance modules and identity requirements +1. **Deploy Core RWA Token** +2. **Deploy/Connect Compliance Contract** +3. **Deploy/Connect Identity Verifier** +4. **Configure Connections** +5. **Configure Rules** (Set up compliance modules and identity requirements) ```rust use soroban_sdk::{Address, Env, String}; From ca983f285bb06c5c9ba1c4bdfac4e56536ecfa36 Mon Sep 17 00:00:00 2001 From: Ozgun Ozerk Date: Wed, 5 Nov 2025 11:50:00 +0300 Subject: [PATCH 7/9] suggestions addressed --- RWA-SEP.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/RWA-SEP.md b/RWA-SEP.md index 27593025..0a0c9fa0 100644 --- a/RWA-SEP.md +++ b/RWA-SEP.md @@ -120,8 +120,7 @@ To deploy a compliant RWA token and make it functional: 1. **Deploy Core RWA Token** 2. **Deploy/Connect Compliance Contract** 3. **Deploy/Connect Identity Verifier** -4. **Configure Connections** -5. **Configure Rules** (Set up compliance modules and identity requirements) +4. **Configure Connections**: Link the RWA token to its compliance and identity verifier contracts using `set_compliance()` and `set_identity_verifier()`. Additionally, configure internal connections within the compliance stack (e.g., linking compliance contract to compliance modules) and identity stack (e.g., linking identity verifier to claim topics/issuers or custom registries) as needed for your implementation. ```rust use soroban_sdk::{Address, Env, String}; @@ -736,3 +735,5 @@ Through our (OpenZeppelin) collaboration with Tokeny, Stellar, we identified key **Identity System Migration**: - Abstract identity verification enables migration between verification approaches - Gradual migration strategies for existing user bases + +For general contract upgrade patterns and best practices, refer to [SEP-49: Upgradeable Contracts](https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0049.md). From 038ae71644776a93062d9da62798d1b9664e2058 Mon Sep 17 00:00:00 2001 From: brozorec <9572072+brozorec@users.noreply.github.com> Date: Fri, 7 Nov 2025 12:27:35 +0100 Subject: [PATCH 8/9] review --- RWA-SEP.md | 111 ++++++++++++++++++++++------------------------------- 1 file changed, 45 insertions(+), 66 deletions(-) diff --git a/RWA-SEP.md b/RWA-SEP.md index 0a0c9fa0..9d66d515 100644 --- a/RWA-SEP.md +++ b/RWA-SEP.md @@ -12,7 +12,7 @@ Discussion: TBD ``` ## Summary -This proposal defines a standard contract interface for Real World Asset (RWA) tokens on Stellar. RWA tokens represent tokenized real-world assets such as securities, bonds, real estate, or other regulated financial instruments that require compliance with regulatory frameworks. +This proposal defines a standard contract interface for Real World Asset (RWA) tokens on Stellar. RWA tokens represent tokenized real-world assets such as securities, bonds, real estate, or other regulated financial instruments that require compliance with regulatory frameworks. RWA tokens are **permissioned tokens**, ensuring that only eligible investors can hold and transfer these tokens. This standard is based on the T-REX (Token for Regulated Exchanges) framework, as implemented in ERC-3643 (https://github.com/ERC-3643/ERC-3643), but introduces significant architectural improvements for flexibility and modularity. @@ -27,16 +27,14 @@ Real World Assets (RWAs) represent a significant opportunity for blockchain adop The T-REX standard provides a comprehensive framework for compliant security tokens. This SEP adapts T-REX to the Stellar ecosystem, enabling: -- **Modular compliance framework** with pluggable compliance rules +- **Modular hook-based compliance framework** with pluggable compliance rules - **Flexible identity verification** supporting multiple approaches (claim-based, Merkle tree, zero-knowledge, etc.) - **Sophisticated freezing mechanisms** at both address and token levels - **Administrative controls** with role-based access control (RBAC) -- **Recovery systems** for institutional-grade wallet management -- **Compliance hooks** for regulatory reporting ## Architecture Overview -Based on extensive research and collaboration with industry experts, this RWA standard introduces an approach built around **loose coupling** and **implementation abstraction**, addressing key limitations identified in existing standards. +This RWA standard introduces an approach built around **loose coupling** and **implementation abstraction**. ### Core Design Principles @@ -52,33 +50,25 @@ The Stellar T-REX consists of several interconnected but loosely coupled compone ``` ┌─────────────────┐ ┌──────────────────┐ ┌─────────────────────┐ │ RWA Token │───▶│ Compliance │───▶│ Compliance Modules │ -│ (Core) │ │ Contract │ │ (Pluggable Rules) │ +│ (Core) │ │ │ │ (Pluggable Rules) │ └─────────────────┘ └──────────────────┘ └─────────────────────┘ │ ▼ ┌─────────────────┐ ┌──────────────────┐ ┌──────────────────┐ -│ Identity │───▶│ Claim Topics & │ │ Custom Identity │ -│ Verifier │ │ Issuers │───▶│ Registry │ +│ Identity │───▶│ Claim Topics & │ │ Identity Registry│ +│ Verifier │ │ Issuers │───▶│ │ └─────────────────┘ └──────────────────┘ └──────────────────┘ ``` -### Flexibility Through Abstraction - -The architecture supports multiple implementation strategies: - -- **Identity Verification**: Merkle trees, Zero-Knowledge proofs, claim-based systems, or custom approaches -- **Compliance Rules**: Modular hook-based system supporting diverse regulatory requirements -- **Access Control**: Integration with external RBAC systems - -This design enables the same core RWA interface to work with vastly different regulatory and technical requirements. +This design enables the same core RWA token interface to work with vastly different regulatory and technical requirements for identity verification, such as Merkle trees, Zero-Knowledge proofs, claim-based systems, and others. Furthermore, the modular hook-based system supports diverse regulatory requirements through pluggable compliance rules. ## Interface -The RWA token interface extends the **fungible token** ([SEP-41](https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0041.md)) functionality with regulatory compliance features. +The RWA token interface extends the **fungible token** ([SEP-41](https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0041.md)) with regulatory required features: freezing, pausing and recovery. ### Architecture Overview -The RWA Token contract requires only **two external functions** to operate: +The RWA token contract requires only **two external functions** to operate: ```rust // Compliance validation - returns true if transfer is allowed @@ -88,8 +78,8 @@ fn can_transfer(e: &Env, from: Address, to: Address, amount: i128) -> bool; 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. +- `can_transfer()` is expected to be exposed from a "Compliance" contract. +- `verify_identity()` is expected to be exposed from an "Identity Verifier" contract. These functions are **deliberately abstracted** as implementation details, enabling: - **Regulatory Flexibility**: Different jurisdictions can implement different compliance logic @@ -101,7 +91,7 @@ In other words, the only thing required by this RWA token design, is that the RW ### Contract Connection Interface -The RWA Token provides simple setter/getter functions for external contracts: +The RWA token provides simple setter/getter functions for external contracts: ```rust // Compliance Contract Management @@ -201,8 +191,8 @@ pub trait RWAToken: TokenInterface { /// * data - `[amount: i128]` fn burn(e: &Env, user_address: Address, amount: i128, operator: Address); - /// Recovery function used to force transfer tokens from a lost wallet - /// to a new wallet for an investor. + /// Recovery function used to force transfer tokens from a old account + /// to a new account for an investor. /// This function can only be called by the operator with necessary /// privileges. RBAC checks are expected to be enforced on the /// `operator`. @@ -210,24 +200,21 @@ pub trait RWAToken: TokenInterface { /// # Arguments /// /// * `e` - Access to the Soroban environment. - /// * `lost_wallet` - The wallet that the investor lost. - /// * `new_wallet` - The newly provided wallet for token transfer. - /// * `investor_onchain_id` - The onchain ID of the investor asking for - /// recovery. + /// * `old_account` - The wallet that the investor lost. + /// * `new_account` - The newly provided wallet for token transfer. /// * `operator` - The address of the operator. /// /// # Events /// - /// * topics - `["transfer", lost_wallet: Address, new_wallet: Address]` + /// * topics - `["transfer", old_account: Address, new_account: Address]` /// * data - `[amount: i128]` - /// * topics - `["recovery", lost_wallet: Address, new_wallet: Address, + /// * topics - `["recovery", old_account: Address, new_account: Address, /// investor_onchain_id: Address]` /// * data - `[]` - fn recovery_address( + fn recover_balance( e: &Env, - lost_wallet: Address, - new_wallet: Address, - investor_onchain_id: Address, + old_account: Address, + new_account: Address, operator: Address, ) -> bool; @@ -429,9 +416,8 @@ The recovery event is emitted when tokens are successfully recovered from a lost **Topics:** - `Symbol` with value `"recovery"` -- `Address`: the lost wallet address -- `Address`: the new wallet address -- `Address`: the investor's onchain ID +- `Address`: the old account address +- `Address`: the new account address **Data:** - Empty array `[]` @@ -488,7 +474,7 @@ The identity verifier set event is emitted when the identity verifier contract i **Data:** - Empty array `[]` -## Component Deep Dive +## Reference Implementation: Component Deep Dive ### 1. Identity Verification System @@ -549,26 +535,26 @@ Our claim-based reference implementation demonstrates the full complexity of tra │ ├────▶┌───────────────────────────┐ │ │ Identity Registry Storage │ - │ │ (User Profiles) │ + │ │ (Investor Profiles) │ │ └───────────────────────────┘ │ ├────▶┌───────────────────────────┐ │ │ Identity Claims │ - │ │ (Claim Validation) │ + │ │ (Investor Claims Storage) │ │ └───────────────────────────┘ │ └────▶┌───────────────────────────┐ │ Claim Issuer │ - │ (Signature Validation) │ + │ (Claims Validation) │ └───────────────────────────┘ ``` **Key Components:** -- **ClaimTopicsAndIssuers**: Merged registry managing both trusted issuers and required claim types (KYC=1, AML=2, etc.) -- **IdentityRegistryStorage**: Component storing identity profiles with country relations and metadata -- **IdentityClaims**: Validates cryptographic claims using multiple signature schemes (Ed25519, Secp256k1, Secp256r1), with an emphasis on interoperability with the evolving OnchainID specification (https://github.com/ERC-3643/ERCs/blob/erc-oid/ERCS/erc-xxxx.md). -- **ClaimIssuer**: Builds and validates cryptographic claims about user attributes +- **ClaimTopicsAndIssuers**: Registry contract managing both trusted issuers and required claim types (KYC=1, AML=2, etc.). +- **IdentityRegistryStorage**: Component storing investors identity profiles with country relations and metadata. +- **IdentityClaims**: Required for every investor as a separate contract or as an extension to existing identity management systems. Its goal is to store cryptographic claims issued to that investor by trusted claim issuers. This component is under investor's control. Its structure mirrors the evolving OnchainID specification (https://github.com/ERC-3643/ERCs/blob/erc-oid/ERCS/erc-xxxx.md). +- **ClaimIssuer**: Conracts belonging to trusted 3rd parties to validate cryptographic claims about investors' attributes by ususing multiple signature schemes (Ed25519, Secp256k1, Secp256r1). ### 2. Compliance System @@ -615,7 +601,7 @@ pub enum ComplianceHook { **Jurisdiction Restrictions Module**: - Hook: `CanTransfer` -- Logic: Block transfers between incompatible jurisdictions +- Logic: Restrict transfers to blocked jurisdictions **Holding Period Module**: - Hook: `CanTransfer` + `Created` @@ -644,7 +630,7 @@ Compliance contracts are designed to be **shared across multiple RWA tokens**, r #### Freezing Mechanisms -Based on regulatory requirements research, the system supports multiple freezing strategies: +The system supports multiple freezing strategies to accomodate for different regulatory requirements: **Address-Level Freezing**: ```rust @@ -665,24 +651,19 @@ fn get_frozen_tokens(e: &Env, user_address: Address) -> i128; #### Recovery System -Institutional-grade wallet recovery for high-value securities: +Two distinct recovery flows are supported: + +1. Identity Recovery: Managed in the Identity Stack (Identity Registry Storage), transfers the identity contract reference and profile (including country data) from old account to new account, and creates a recovery mapping. ```rust -fn recovery_address( - e: &Env, - lost_wallet: Address, - new_wallet: Address, - investor_onchain_id: Address, - operator: Address -) -> bool; +fn recover_identity(e: &Env, old_account: Address, new_account: Address, operator: Address); ``` -**Recovery Process**: -1. **Identity Verification**: Verify investor's onchain identity matches the lost wallet -2. **Authorization Check**: Ensure operator has recovery permissions -3. **Balance Transfer**: Move all tokens from lost wallet to new wallet -4. **Identity Update**: Update identity registry to map new wallet to existing identity -5. **Audit Trail**: Emit comprehensive events for regulatory reporting +2. Balance Recovery: Managed by the RWA token, transfers tokens from old to new account after verifying the identity recovery mapping exists + +```rust +fn recover_balance(e: &Env, old_account: Address, new_account: Address, operator: Address) -> bool; +``` #### Forced Transfers @@ -700,15 +681,13 @@ fn forced_transfer(e: &Env, from: Address, to: Address, amount: i128, operator: RWA tokens require proper access control to ensure that sensitive operations are only performed by authorized entities: -- **Operator Authorization**: All administrative functions require proper operator authorization using Soroban's built-in authorization mechanisms +- **Operator Authorization**: All administrative functions require `operator` authorization - **Flexible Access Control**: While the RWA interface itself doesn't prescribe a specific access control model, implementations can integrate with external access control systems as needed - **Compliance Integration**: Access control permissions should be integrated with compliance rules to ensure regulatory requirements are met -## Research-Driven Design Decisions - -### Addressing ERC-3643 Limitations +### Deviations from ERC-3643 -Through our (OpenZeppelin) collaboration with Tokeny, Stellar, we identified key limitations in existing RWA standards: +Several limitations in the original ERC-3643 standard and its reference implementation were identified and respectively addressed: **1. Tight Coupling Issues** - **Problem**: ERC-3643 tightly couples identity verification with specific contract structures From 29c1eeec841a0efc8fb3ee4484e99ce7f1033bef Mon Sep 17 00:00:00 2001 From: brozorec <9572072+brozorec@users.noreply.github.com> Date: Fri, 7 Nov 2025 12:30:30 +0100 Subject: [PATCH 9/9] typo --- RWA-SEP.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/RWA-SEP.md b/RWA-SEP.md index 9d66d515..7cb7b3c9 100644 --- a/RWA-SEP.md +++ b/RWA-SEP.md @@ -630,7 +630,7 @@ Compliance contracts are designed to be **shared across multiple RWA tokens**, r #### Freezing Mechanisms -The system supports multiple freezing strategies to accomodate for different regulatory requirements: +The system supports multiple freezing strategies to accommodate for different regulatory requirements: **Address-Level Freezing**: ```rust