From 6e86162ec5cce1d6af73ecc450db29e0e0fea2e2 Mon Sep 17 00:00:00 2001 From: Ozgun Ozerk Date: Tue, 21 Oct 2025 15:31:37 +0300 Subject: [PATCH 01/16] rwa docs --- content/stellar-contracts/tokens/rwa/rwa.mdx | 324 +++++++++++++++++++ 1 file changed, 324 insertions(+) create mode 100644 content/stellar-contracts/tokens/rwa/rwa.mdx diff --git a/content/stellar-contracts/tokens/rwa/rwa.mdx b/content/stellar-contracts/tokens/rwa/rwa.mdx new file mode 100644 index 00000000..47b4280c --- /dev/null +++ b/content/stellar-contracts/tokens/rwa/rwa.mdx @@ -0,0 +1,324 @@ +--- +title: Real World Asset (RWA) Token +--- + +[Source Code](https://github.com/OpenZeppelin/stellar-contracts/tree/main/packages/tokens/src/rwa) + +Real World Asset (RWA) tokens are security tokens that represent ownership or rights to real-world assets +such as real estate, commodities, securities, or other regulated financial instruments. +These tokens must comply with various regulatory requirements including KYC/AML verification, transfer restrictions, +and compliance rules. The RWA module provides a comprehensive framework based on the T-REX +(Token for Regulated Exchanges) standard. + +## Overview + +The [RWA](https://github.com/OpenZeppelin/stellar-contracts/tree/main/packages/tokens/src/rwa) module provides a complete implementation of regulated security tokens with built-in compliance, +identity verification, and administrative controls. The module is designed to be flexible and extensible, +allowing integration with various identity registry and compliance frameworks. + +The RWA token extends the standard fungible token functionality with regulatory features required for +security tokens, including: + +- **Identity Management**: Integration with identity registries for KYC/AML compliance +- **Compliance Framework**: Modular compliance rules and validation for transfers and minting +- **Transfer Controls**: Sophisticated transfer restrictions and validations +- **Freezing Mechanisms**: Address-level and partial token freezing capabilities +- **Recovery System**: Lost/old account recovery for verified investors +- **Pausable Operations**: Emergency pause functionality for the entire token +- **Role-Based Access Control (RBAC)**: Flexible privilege management for administrative functions + +## Architecture + +The RWA module follows a modular architecture that separates concerns and allows for flexible integration: + +### Core Components + +1. **RWA Token Contract**: The main token contract implementing the `RWAToken` trait, which extends both +`FungibleToken` and `Pausable` traits. + +2. **Identity Verifier**: A separate contract responsible for verifying user identities. +The RWA token expects the following function to be available: +- `fn verify_identity(e: &Env, account: &Address);` + +3. **Compliance Contract**: A separate contract that validates transfers, minting, and burning operations. +The RWA token expects the following functions to be available: +- `fn can_transfer(e: &Env, from: Address, to: Address, amount: i128, token: Address) -> bool;` +- `fn can_create(e: &Env, to: Address, amount: i128, token: Address) -> bool;` +- `fn created(e: &Env, to: Address, amount: i128, token: Address);` +- `fn destroyed(e: &Env, from: Address, amount: i128, token: Address);` +- `fn transferred(e: &Env, from: Address, to: Address, amount: i128, token: Address);` + +This loose coupling between the RWA token and the modules allows the following: +- Share identity verifier and compliance contracts across multiple RWA tokens +- Implement custom identity verification approaches (Merkle trees, zero-knowledge proofs, claim-based, etc.) +- Create modular compliance rules that can be composed and reused + +### Supporting Modules + +The module provides default implementations for common use cases: + +- **Claim Topics and Issuers**: Manages trusted claim issuers and claim types (e.g., KYC=1, AML=2) +- **Identity Claims**: Integration with identity registries for cryptographic claim validation +- **Identity Registry Storage**: Registry for storing identity information and country relations +- **Claim Issuer**: Validates cryptographic claims with multiple signature schemes (Ed25519, Secp256k1, Secp256r1) +- **Compliance**: Modular compliance framework with hook-based architecture + +## Usage + +We'll create a regulated security token for tokenized real estate shares. The token requires KYC verification, +implements transfer restrictions, and provides administrative controls for compliance. + +Here's what a basic RWA token contract might look like (only the base token contract, not the modules): + +```rust +use soroban_sdk::{contract, contractimpl, symbol_short, Address, Env, String}; +use stellar_access::access_control::{self as access_control, AccessControl}; +use stellar_macros::default_impl; +use stellar_tokens::{ + fungible::{Base, FungibleToken}, + rwa::{RWAToken, RWA}, +}; + +#[contract] +pub struct RealEstateToken; + +#[contractimpl] +impl RealEstateToken { + pub fn __constructor(e: &Env, admin: Address, manager: Address, initial_supply: i128) { + // Set token metadata + Base::set_metadata( + e, + 18, // 18 decimals + String::from_str(e, "Real Estate Token"), + String::from_str(e, "REST"), + ); + + // Set up access control + access_control::set_admin(e, &admin); + + // Create a "manager" role and grant it to the manager address + access_control::grant_role_no_auth(e, &admin, &manager, &symbol_short!("manager")); + + // Mint initial supply to the admin (must be a verified identity) + RWA::mint(e, &admin, initial_supply); + } +} + +// Implement the FungibleToken trait with RWA contract type +#[default_impl] +#[contractimpl] +impl FungibleToken for RealEstateToken { + type ContractType = RWA; +} + +// Implement the RWAToken trait for regulatory features +#[default_impl] +#[contractimpl] +impl RWAToken for RealEstateToken {} + +// Implement AccessControl for role-based permissions +#[default_impl] +#[contractimpl] +impl AccessControl for RealEstateToken {} +``` + +## Key Features + +### Identity Verification + +Identity Verification is handled on a separate contract as a module. + +All token recipients must have verified identities before receiving tokens. The RWA token integrates +with an identity verifier contract that validates user identities against cryptographic claims. + +```rust +// Minting requires identity verification +RWA::mint(e, &verified_investor, amount); + +// Transfers automatically verify recipient identity +RWA::transfer(e, &from, &verified_recipient, amount); + +// Wallet recovery for lost/old accounts +RWA::recover_balance(e, &old_account, &new_account, &operator); +``` + +### Compliance Validation + +Compliance Validation is handled on a separate contract as a module. + +The compliance framework allows you to implement custom transfer and minting rules through a modular hook system: + +- **CanTransfer**: Validates if a transfer should be allowed +- **CanCreate**: Validates if a mint operation should be allowed +- **Transferred**: Updates state after a successful transfer +- **Created**: Updates state after a successful mint +- **Destroyed**: Updates state after a successful burn + +### Freezing Mechanisms + +Freezing Mechanisms are handled on the RWA token contract. + +RWA tokens support two types of freezing: + +1. **Address-level freezing**: Completely freeze an address from sending or receiving tokens +2. **Partial token freezing**: Freeze a specific amount of tokens for an address + +```rust +// Freeze an entire address +RWA::set_address_frozen(e, &user_address, bool, &operator); + +// Freeze a specific amount of tokens +RWA::freeze_partial_tokens(e, &user_address, amount, &operator); + +// Unfreeze tokens +RWA::unfreeze_partial_tokens(e, &user_address, amount, &operator); +``` + +### Recovery System + +Balance Recovery System is handled on the RWA token contract, whereas Identity Recovery System is handled +on a separate contract as a module (may be a part of the Identity Registry contract). + +The recovery system allows authorized operators to transfer tokens from a lost/old account to a +new account for the same verified investor: + +```rust +// Recover tokens from old account to new account +RWA::recover_balance(e, &old_account, &new_account, &operator); +``` + +### Forced Transfers + +Forced Transfers are handled on the RWA token contract. + +Authorized operators can force transfers between verified wallets for regulatory compliance: + +```rust +// Force a transfer for regulatory reasons +RWA::forced_transfer(e, &from, &to, amount, &operator); +``` + +## Modules + +The RWA package includes several supporting modules that work together to provide comprehensive regulatory compliance: + +### - Compliance +[Source Code](https://github.com/OpenZeppelin/stellar-contracts/tree/main/packages/tokens/src/rwa/compliance) + +This is a mandatory module, since RWA token contract expects the compliance checks and hooks to be available. + +The compliance module provides a modular framework for implementing custom compliance rules. +It uses a hook-based architecture where compliance modules can be registered for specific events: + +- **Transferred**: Called after tokens are successfully transferred +- **Created**: Called after tokens are successfully minted +- **Destroyed**: Called after tokens are successfully burned +- **CanTransfer**: Called during transfer validation (read-only) +- **CanCreate**: Called during mint validation (read-only) + +The compliance contract is designed to be shared across multiple RWA tokens, with each hook function accepting a `token` parameter to identify the calling token. + +### - Identity Verifier +[Source Code](https://github.com/OpenZeppelin/stellar-contracts/tree/main/packages/tokens/src/rwa/identity_verifier) + +This is a mandatory module, since RWA token contract expects `verify_identity(e: &Env, address: Address)` function to be available. + +The identity verifier module provides the interface for verifying user identities. +It also supports custom implementation approaches: + +- **Claim-based**: Cryptographic claims from trusted issuers (default implementation) +- **Merkle Tree**: Efficient verification using merkle proofs +- **Zero-Knowledge**: Privacy-preserving verification with custom ZK circuits +- **Custom approaches**: Any implementation that satisfies the `verify_identity` interface + +The default claim-based implementation integrates with the Claim Topics and Issuers module and Identity Registry Storage. + +### - Claim Topics and Issuers +[Source Code](https://github.com/OpenZeppelin/stellar-contracts/tree/main/packages/tokens/src/rwa/claim_topics_and_issuers) + +This module is an implementation detail. It is provided as the suggested implementation for the `Claim-based` approach. + +Manages trusted claim issuers and claim topics (e.g., KYC=1, AML=2, Accredited Investor=3). This module: + +- Maintains a registry of trusted claim issuers +- Defines which claim topics are required for token participation +- Maps issuers to the claim topics they are authorized to issue +- Can be shared across multiple RWA tokens + +### - Identity Registry Storage +[Source Code](https://github.com/OpenZeppelin/stellar-contracts/tree/main/packages/tokens/src/rwa/identity_registry_storage) + +This module is an implementation detail. It is provided as the suggested implementation for the `Claim-based` approach. + +Stores identity information for verified investors, including: + +- Mapping of wallet addresses to onchain identity contracts +- Country information for regulatory compliance +- Support for both individual and organizational identities +- Recovery account mappings for lost wallet scenarios + +### - Identity Claims +[Source Code](https://github.com/OpenZeppelin/stellar-contracts/tree/main/packages/tokens/src/rwa/identity_claims) + +This module is an implementation detail. It is provided as the suggested implementation for the `Claim-based` approach. + +Manages on-chain identity claims with cryptographic signatures. Claims are issued by trusted authorities and contain: + +- Claim topic (e.g., KYC, AML) +- Claim data (encrypted or hashed information) +- Cryptographic signature +- Issuer information + +### - Claim Issuer +[Source Code](https://github.com/OpenZeppelin/stellar-contracts/tree/main/packages/tokens/src/rwa/claim_issuer) + +This module is an implementation detail. It is provided as the suggested implementation for the `Claim-based` approach. + +Validates cryptographic claims with support for multiple signature schemes: + +- Ed25519 (Stellar native) +- Secp256k1 (Ethereum compatible) +- Secp256r1 (Enterprise PKI compatible) + +## Extensions + +The following optional extensions are provided: + +### - Document Manager +[Source Code](https://github.com/OpenZeppelin/stellar-contracts/tree/main/packages/tokens/src/rwa/extensions/doc_manager) + +This module is not mandatory. + +The `DocumentManager` trait extends the `RWAToken` trait to provide document management capabilities following the ERC-1643 standard. This extension allows contracts to: + +- Attach documents with URI, hash, and timestamp +- Update existing document metadata +- Remove documents from the contract +- Retrieve individual or all documents + +This is useful for attaching legal documents, prospectuses, or other regulatory disclosures to the token contract. + +## Utility Modules + +### - Token Binder +[Source Code](https://github.com/OpenZeppelin/stellar-contracts/tree/main/packages/tokens/src/rwa/utils/token_binder) + +The `TokenBinder` trait provides a standardized interface for linking tokens to periphery contracts such as identity registries and compliance contracts. This allows a single periphery contract to serve multiple RWA tokens. + +Features: +- Bind/unbind tokens to periphery services +- Query all linked tokens +- Efficient storage with bucket-based architecture (supports up to 10,000 tokens) +- Swap-remove pattern for compact storage + +## Security Considerations + +When implementing RWA tokens, consider the following security aspects: + +1. **Authorization**: All administrative functions expect RBAC checks to be enforced on the `operator` parameter +2. **Identity Verification**: Always verify identities before allowing token operations +3. **Compliance Validation**: Ensure compliance rules are properly configured before enabling transfers +4. **Freezing**: Use freezing mechanisms carefully as they can lock user funds +5. **Recovery**: Recovery operations should have strict authorization and verification +6. **Pausability**: The pause mechanism should only be accessible to authorized administrators +7. **Contract Upgrades**: Consider using immutable periphery contracts or implementing upgrade mechanisms carefully From 091b53b618c7241eec11c13412ef3929f15b980c Mon Sep 17 00:00:00 2001 From: Ozgun Ozerk Date: Tue, 21 Oct 2025 16:18:50 +0300 Subject: [PATCH 02/16] added link to rwa in the index page --- content/stellar-contracts/index.mdx | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/content/stellar-contracts/index.mdx b/content/stellar-contracts/index.mdx index cf775fa2..7ce86d79 100644 --- a/content/stellar-contracts/index.mdx +++ b/content/stellar-contracts/index.mdx @@ -2,12 +2,15 @@ title: Stellar Smart Contracts Suite --- -Explore our comprehensive suite of secure and scalable smart contract utilities for Stellar Soroban. Our libraries provide robust implementations for fungible and non-fungible tokens, along with powerful tools for access control and contract management. +Explore our comprehensive suite of secure and scalable smart contract utilities for Stellar Soroban. +Our libraries provide robust implementations for fungible and non-fungible tokens, along with powerful tools +for access control and contract management. ## Tokens * **[Fungible Tokens](/stellar-contracts/tokens/fungible/fungible)**: Digital assets representing a fixed or dynamic supply of identical units. * **[Non-Fungible Tokens (NFTs)](/stellar-contracts/tokens/non-fungible/non-fungible)**: Unique digital assets with verifiable ownership. +* **[Real World Assets (RWAs)](/stellar-contracts/tokens/rwa/rwa)**: Digital assets representing real-world assets. ## Access Control From 970212267fbc5a00817daea4a10e31a74c79eef6 Mon Sep 17 00:00:00 2001 From: Ozgun Ozerk Date: Fri, 31 Oct 2025 17:46:58 +0300 Subject: [PATCH 03/16] suggestions part 1 --- content/stellar-contracts/tokens/rwa/rwa.mdx | 61 +++++++++++--------- src/navigation/stellar.json | 5 ++ 2 files changed, 38 insertions(+), 28 deletions(-) diff --git a/content/stellar-contracts/tokens/rwa/rwa.mdx b/content/stellar-contracts/tokens/rwa/rwa.mdx index 47b4280c..d9975145 100644 --- a/content/stellar-contracts/tokens/rwa/rwa.mdx +++ b/content/stellar-contracts/tokens/rwa/rwa.mdx @@ -4,15 +4,16 @@ title: Real World Asset (RWA) Token [Source Code](https://github.com/OpenZeppelin/stellar-contracts/tree/main/packages/tokens/src/rwa) -Real World Asset (RWA) tokens are security tokens that represent ownership or rights to real-world assets -such as real estate, commodities, securities, or other regulated financial instruments. -These tokens must comply with various regulatory requirements including KYC/AML verification, transfer restrictions, -and compliance rules. The RWA module provides a comprehensive framework based on the T-REX -(Token for Regulated Exchanges) standard. +Real World Asset (RWA) tokens are security tokens that represent ownership or rights to real-world assets such as +real estate, commodities, securities, or other regulated financial instruments. These tokens must comply with various +regulatory requirements including KYC/AML verification, transfer restrictions, and compliance rules. The RWA module +provides a comprehensive framework based on the T-REX (Token for Regulated Exchanges) standard, +which implements the [ERC-3643](https://docs.erc3643.org/erc-3643) specification. ## Overview -The [RWA](https://github.com/OpenZeppelin/stellar-contracts/tree/main/packages/tokens/src/rwa) module provides a complete implementation of regulated security tokens with built-in compliance, +The [RWA](https://github.com/OpenZeppelin/stellar-contracts/tree/main/packages/tokens/src/rwa) module +provides a complete implementation of regulated security tokens with built-in compliance, identity verification, and administrative controls. The module is designed to be flexible and extensible, allowing integration with various identity registry and compliance frameworks. @@ -37,16 +38,15 @@ The RWA module follows a modular architecture that separates concerns and allows `FungibleToken` and `Pausable` traits. 2. **Identity Verifier**: A separate contract responsible for verifying user identities. -The RWA token expects the following function to be available: -- `fn verify_identity(e: &Env, account: &Address);` +The RWA token expects the following function to be available: `fn verify_identity(e: &Env, account: &Address);`. 3. **Compliance Contract**: A separate contract that validates transfers, minting, and burning operations. The RWA token expects the following functions to be available: -- `fn can_transfer(e: &Env, from: Address, to: Address, amount: i128, token: Address) -> bool;` -- `fn can_create(e: &Env, to: Address, amount: i128, token: Address) -> bool;` -- `fn created(e: &Env, to: Address, amount: i128, token: Address);` -- `fn destroyed(e: &Env, from: Address, amount: i128, token: Address);` -- `fn transferred(e: &Env, from: Address, to: Address, amount: i128, token: Address);` + - `fn can_transfer(e: &Env, from: Address, to: Address, amount: i128, token: Address) -> bool;` + - `fn can_create(e: &Env, to: Address, amount: i128, token: Address) -> bool;` + - `fn created(e: &Env, to: Address, amount: i128, token: Address);` + - `fn destroyed(e: &Env, from: Address, amount: i128, token: Address);` + - `fn transferred(e: &Env, from: Address, to: Address, amount: i128, token: Address);` This loose coupling between the RWA token and the modules allows the following: - Share identity verifier and compliance contracts across multiple RWA tokens @@ -176,12 +176,12 @@ RWA::unfreeze_partial_tokens(e, &user_address, amount, &operator); ### Recovery System -Balance Recovery System is handled on the RWA token contract, whereas Identity Recovery System is handled -on a separate contract as a module (may be a part of the Identity Registry contract). - The recovery system allows authorized operators to transfer tokens from a lost/old account to a new account for the same verified investor: +Balance Recovery System is handled on the RWA token contract, whereas Identity Recovery System is handled +on a separate contract as a module (may be a part of the Identity Registry contract). + ```rust // Recover tokens from old account to new account RWA::recover_balance(e, &old_account, &new_account, &operator); @@ -216,27 +216,30 @@ It uses a hook-based architecture where compliance modules can be registered for - **CanTransfer**: Called during transfer validation (read-only) - **CanCreate**: Called during mint validation (read-only) -The compliance contract is designed to be shared across multiple RWA tokens, with each hook function accepting a `token` parameter to identify the calling token. +The compliance contract is designed to be shared across multiple RWA tokens, with each hook function accepting a +`token` parameter to identify the calling token. ### - Identity Verifier [Source Code](https://github.com/OpenZeppelin/stellar-contracts/tree/main/packages/tokens/src/rwa/identity_verifier) -This is a mandatory module, since RWA token contract expects `verify_identity(e: &Env, address: Address)` function to be available. +This is a mandatory module, since RWA token contract expects `verify_identity(e: &Env, address: Address)` +function to be available. The identity verifier module provides the interface for verifying user identities. -It also supports custom implementation approaches: +It can also support possible custom implementation approaches: -- **Claim-based**: Cryptographic claims from trusted issuers (default implementation) +- **Claim-based**: Cryptographic claims from trusted issuers (provided default implementation) - **Merkle Tree**: Efficient verification using merkle proofs - **Zero-Knowledge**: Privacy-preserving verification with custom ZK circuits -- **Custom approaches**: Any implementation that satisfies the `verify_identity` interface +- **Other custom approaches**: Any implementation that satisfies the `verify_identity` interface -The default claim-based implementation integrates with the Claim Topics and Issuers module and Identity Registry Storage. +The default claim-based implementation integrates with the Claim Topics and Issuers module and +Identity Registry Storage. ### - Claim Topics and Issuers [Source Code](https://github.com/OpenZeppelin/stellar-contracts/tree/main/packages/tokens/src/rwa/claim_topics_and_issuers) -This module is an implementation detail. It is provided as the suggested implementation for the `Claim-based` approach. +This module is an implementation detail. It is provided as the suggested implementation for the **Claim-based** approach. Manages trusted claim issuers and claim topics (e.g., KYC=1, AML=2, Accredited Investor=3). This module: @@ -248,7 +251,7 @@ Manages trusted claim issuers and claim topics (e.g., KYC=1, AML=2, Accredited I ### - Identity Registry Storage [Source Code](https://github.com/OpenZeppelin/stellar-contracts/tree/main/packages/tokens/src/rwa/identity_registry_storage) -This module is an implementation detail. It is provided as the suggested implementation for the `Claim-based` approach. +This module is an implementation detail. It is provided as the suggested implementation for the **Claim-based** approach. Stores identity information for verified investors, including: @@ -260,7 +263,7 @@ Stores identity information for verified investors, including: ### - Identity Claims [Source Code](https://github.com/OpenZeppelin/stellar-contracts/tree/main/packages/tokens/src/rwa/identity_claims) -This module is an implementation detail. It is provided as the suggested implementation for the `Claim-based` approach. +This module is an implementation detail. It is provided as the suggested implementation for the **Claim-based** approach. Manages on-chain identity claims with cryptographic signatures. Claims are issued by trusted authorities and contain: @@ -272,7 +275,7 @@ Manages on-chain identity claims with cryptographic signatures. Claims are issue ### - Claim Issuer [Source Code](https://github.com/OpenZeppelin/stellar-contracts/tree/main/packages/tokens/src/rwa/claim_issuer) -This module is an implementation detail. It is provided as the suggested implementation for the `Claim-based` approach. +This module is an implementation detail. It is provided as the suggested implementation for the **Claim-based** approach. Validates cryptographic claims with support for multiple signature schemes: @@ -289,7 +292,8 @@ The following optional extensions are provided: This module is not mandatory. -The `DocumentManager` trait extends the `RWAToken` trait to provide document management capabilities following the ERC-1643 standard. This extension allows contracts to: +The `DocumentManager` trait extends the `RWAToken` trait to provide document management capabilities following the +ERC-1643 standard. This extension allows contracts to: - Attach documents with URI, hash, and timestamp - Update existing document metadata @@ -303,7 +307,8 @@ This is useful for attaching legal documents, prospectuses, or other regulatory ### - Token Binder [Source Code](https://github.com/OpenZeppelin/stellar-contracts/tree/main/packages/tokens/src/rwa/utils/token_binder) -The `TokenBinder` trait provides a standardized interface for linking tokens to periphery contracts such as identity registries and compliance contracts. This allows a single periphery contract to serve multiple RWA tokens. +The `TokenBinder` trait provides a standardized interface for linking tokens to periphery contracts such as identity +registries and compliance contracts. This allows a single periphery contract to serve multiple RWA tokens. Features: - Bind/unbind tokens to periphery services diff --git a/src/navigation/stellar.json b/src/navigation/stellar.json index 0a7dcb1c..63c69899 100644 --- a/src/navigation/stellar.json +++ b/src/navigation/stellar.json @@ -26,6 +26,11 @@ "type": "page", "name": "Non-Fungible", "url": "/stellar-contracts/tokens/non-fungible/non-fungible" + }, + { + "type": "page", + "name": "RWA", + "url": "/stellar-contracts/tokens/rwa/rwa" } ] }, From 06f988cd5fbad81a197ec666980bbe0cde1bfab1 Mon Sep 17 00:00:00 2001 From: Ozgun Ozerk Date: Fri, 31 Oct 2025 18:45:00 +0300 Subject: [PATCH 04/16] suggestions part 2 --- content/stellar-contracts/tokens/rwa/rwa.mdx | 134 ++++++++++++++++--- 1 file changed, 112 insertions(+), 22 deletions(-) diff --git a/content/stellar-contracts/tokens/rwa/rwa.mdx b/content/stellar-contracts/tokens/rwa/rwa.mdx index d9975145..b88372cc 100644 --- a/content/stellar-contracts/tokens/rwa/rwa.mdx +++ b/content/stellar-contracts/tokens/rwa/rwa.mdx @@ -6,15 +6,15 @@ title: Real World Asset (RWA) Token Real World Asset (RWA) tokens are security tokens that represent ownership or rights to real-world assets such as real estate, commodities, securities, or other regulated financial instruments. These tokens must comply with various -regulatory requirements including KYC/AML verification, transfer restrictions, and compliance rules. The RWA module +regulatory requirements including KYC/AML verification, transfer restrictions, and compliance rules. The RWA suite provides a comprehensive framework based on the T-REX (Token for Regulated Exchanges) standard, which implements the [ERC-3643](https://docs.erc3643.org/erc-3643) specification. ## Overview -The [RWA](https://github.com/OpenZeppelin/stellar-contracts/tree/main/packages/tokens/src/rwa) module +The [RWA](https://github.com/OpenZeppelin/stellar-contracts/tree/main/packages/tokens/src/rwa) suite provides a complete implementation of regulated security tokens with built-in compliance, -identity verification, and administrative controls. The module is designed to be flexible and extensible, +identity verification, and administrative controls. The suite is designed to be flexible and extensible, allowing integration with various identity registry and compliance frameworks. The RWA token extends the standard fungible token functionality with regulatory features required for @@ -30,7 +30,7 @@ security tokens, including: ## Architecture -The RWA module follows a modular architecture that separates concerns and allows for flexible integration: +The RWA suite follows a modular architecture that separates concerns and allows for flexible integration: ### Core Components @@ -84,7 +84,14 @@ pub struct RealEstateToken; #[contractimpl] impl RealEstateToken { - pub fn __constructor(e: &Env, admin: Address, manager: Address, initial_supply: i128) { + pub fn __constructor( + e: &Env, + admin: Address, + manager: Address, + compliance: Address, + identity_verifier: Address, + initial_supply: i128, + ) { // Set token metadata Base::set_metadata( e, @@ -93,6 +100,10 @@ impl RealEstateToken { String::from_str(e, "REST"), ); + // Set compliance and identity verifier contracts + RWA::set_compliance(e, &compliance); + RWA::set_identity_verifier(e, &identity_verifier); + // Set up access control access_control::set_admin(e, &admin); @@ -131,17 +142,37 @@ Identity Verification is handled on a separate contract as a module. All token recipients must have verified identities before receiving tokens. The RWA token integrates with an identity verifier contract that validates user identities against cryptographic claims. -```rust -// Minting requires identity verification -RWA::mint(e, &verified_investor, amount); - -// Transfers automatically verify recipient identity -RWA::transfer(e, &from, &verified_recipient, amount); +Every token operation that involves receiving tokens (mint, transfer, recovery) automatically calls the +identity verifier contract to ensure the recipient has a valid identity with the required claims (KYC, AML, etc.). -// Wallet recovery for lost/old accounts +```rust +// Example: Minting tokens +// Internally calls: identity_verifier.verify_identity(&recipient) +// Then calls: compliance.can_create(&recipient, &amount) +// Finally calls: compliance.created(&recipient, &amount) after minting +RWA::mint(e, &recipient, amount); + +// Example: Transferring tokens +// Internally calls: identity_verifier.verify_identity(&from) +// Then calls: identity_verifier.verify_identity(&to) +// Then calls: compliance.can_transfer(&from, &to, &amount) +// Finally calls: compliance.transferred(&from, &to, &amount) after transfer +RWA::transfer(e, &from, &to, amount); + +// Example: Wallet recovery for lost/old accounts +// Internally calls: identity_verifier.verify_identity(&new_account) +// Then calls: identity_verifier.recovery_target(&old_account) to verify the new account +// is the authorized recovery target for the old account +// Transfers all tokens and preserves frozen status RWA::recover_balance(e, &old_account, &new_account, &operator); ``` +**Identity Verification Flow:** +1. The RWA token calls `identity_verifier.verify_identity(&address)` +2. The identity verifier checks if the address has a registered identity +3. The identity verifier validates that the identity has all required claims from trusted issuers +4. If verification fails, the entire operation reverts with `IdentityVerificationFailed` error + ### Compliance Validation Compliance Validation is handled on a separate contract as a module. @@ -207,8 +238,8 @@ The RWA package includes several supporting modules that work together to provid This is a mandatory module, since RWA token contract expects the compliance checks and hooks to be available. -The compliance module provides a modular framework for implementing custom compliance rules. -It uses a hook-based architecture where compliance modules can be registered for specific events: +Provides a modular framework for implementing custom compliance rules. +[Compliance Contract](https://github.com/OpenZeppelin/stellar-contracts/blob/main/packages/tokens/src/rwa/compliance/mod.rs#L67) uses a hook-based architecture where multiple [compliance modules](https://github.com/OpenZeppelin/stellar-contracts/blob/main/packages/tokens/src/rwa/compliance/mod.rs#L327) can be registered for specific events: - **Transferred**: Called after tokens are successfully transferred - **Created**: Called after tokens are successfully minted @@ -225,7 +256,7 @@ The compliance contract is designed to be shared across multiple RWA tokens, wit This is a mandatory module, since RWA token contract expects `verify_identity(e: &Env, address: Address)` function to be available. -The identity verifier module provides the interface for verifying user identities. +The **Identity Verifier Module** provides the interface for verifying user identities. It can also support possible custom implementation approaches: - **Claim-based**: Cryptographic claims from trusted issuers (provided default implementation) @@ -233,7 +264,7 @@ It can also support possible custom implementation approaches: - **Zero-Knowledge**: Privacy-preserving verification with custom ZK circuits - **Other custom approaches**: Any implementation that satisfies the `verify_identity` interface -The default claim-based implementation integrates with the Claim Topics and Issuers module and +The default claim-based implementation integrates with the **Claim Topics and Issuers Module** and Identity Registry Storage. ### - Claim Topics and Issuers @@ -241,12 +272,63 @@ Identity Registry Storage. This module is an implementation detail. It is provided as the suggested implementation for the **Claim-based** approach. -Manages trusted claim issuers and claim topics (e.g., KYC=1, AML=2, Accredited Investor=3). This module: +Acts as the trust registry that defines which claim topics are required and which issuers are authorized to provide those claims. + +Key features/responsibilities of the **Claim Topics and Issuers Module** are: + - **Claim Topic Registry**: Defines which types of claims are required for token participation (e.g., KYC=1, AML=2, Accredited Investor=3) + - **Trusted Issuer Registry**: Maintains a list of authorized claim issuers (e.g., KYC providers, compliance firms) + - **Authorization Mapping**: Maps each trusted issuer to the specific claim topics they are authorized to issue + - Example: Issuer A can issue KYC and AML claims, but not Accreditation claims + - Example: Issuer B can only issue Accreditation claims + - **Multi-Token Support**: Can be shared across multiple RWA tokens, reducing deployment costs + +**Configuration Example:** +```rust +// Add claim topics +add_claim_topic(e, 1, operator); // KYC +add_claim_topic(e, 2, operator); // AML +add_claim_topic(e, 3, operator); // Accredited Investor + +// Add trusted issuer with authorized topics +add_trusted_issuer(e, issuer_a, vec![1, 2], operator); // Can issue KYC and AML +add_trusted_issuer(e, issuer_b, vec![3], operator); // Can only issue Accreditation +``` + +#### Understanding Claims + +**What is a Claim?** + +A claim is a cryptographically signed attestation made by a trusted authority (claim issuer) about a specific aspect +of an identity. Think of it as a digital certificate that proves something about an investor. + +**Claim Structure:** + +Each claim contains: +- **Topic**: A numeric identifier for what the claim attests to (e.g., KYC=1, AML=2, Accredited Investor=3) +- **Issuer**: The address of the trusted authority that issued the claim +- **Signature**: Cryptographic proof that the issuer created this claim +- **Data**: The actual claim information (can include expiration dates, metadata) +- **Scheme**: The signature algorithm used (Ed25519, Secp256k1, Secp256r1) + +**How Claims Work:** + +1. **Issuance**: A trusted authority (e.g., KYC provider) verifies an investor's identity off-chain +2. **Signing**: The authority creates a cryptographic signature over the claim data using their private key +3. **Storage**: The claim is stored on-chain in the investor's identity contract +4. **Verification**: When the investor tries to receive tokens, the RWA contract: + - Retrieves the required claims from the identity contract + - Validates the cryptographic signatures using the issuer's public key + - Checks that the claims haven't expired or been revoked + - Ensures the issuer is trusted and authorized for those claim topics + +**Example Flow:** +``` +Investor → KYC Provider (off-chain verification) + → Claim Issuer Contract (signs claim with private key) + → Identity Contract (stores signed claim on-chain) + → RWA Token (validates claim during transfer/mint) +``` -- Maintains a registry of trusted claim issuers -- Defines which claim topics are required for token participation -- Maps issuers to the claim topics they are authorized to issue -- Can be shared across multiple RWA tokens ### - Identity Registry Storage [Source Code](https://github.com/OpenZeppelin/stellar-contracts/tree/main/packages/tokens/src/rwa/identity_registry_storage) @@ -265,7 +347,15 @@ Stores identity information for verified investors, including: This module is an implementation detail. It is provided as the suggested implementation for the **Claim-based** approach. -Manages on-chain identity claims with cryptographic signatures. Claims are issued by trusted authorities and contain: +Manages on-chain identity claims with cryptographic signatures. + +This module can be used to extend or be embedded in identity systems. + + +This contract is under the control of the investors themselves, who are responsible for storing their claims and corresponding signatures. This gives investors ownership of their identity data. + + +Claims are issued by trusted authorities and contain: - Claim topic (e.g., KYC, AML) - Claim data (encrypted or hashed information) From 1b5fccaf97ec29b29aaaa761b507dcf1b29ae54d Mon Sep 17 00:00:00 2001 From: Ozgun Ozerk Date: Fri, 31 Oct 2025 19:03:14 +0300 Subject: [PATCH 05/16] suggestions part 3 --- content/stellar-contracts/tokens/rwa/rwa.mdx | 44 ++++++++++++++++---- 1 file changed, 35 insertions(+), 9 deletions(-) diff --git a/content/stellar-contracts/tokens/rwa/rwa.mdx b/content/stellar-contracts/tokens/rwa/rwa.mdx index b88372cc..ec5c11d7 100644 --- a/content/stellar-contracts/tokens/rwa/rwa.mdx +++ b/content/stellar-contracts/tokens/rwa/rwa.mdx @@ -238,14 +238,28 @@ The RWA package includes several supporting modules that work together to provid This is a mandatory module, since RWA token contract expects the compliance checks and hooks to be available. -Provides a modular framework for implementing custom compliance rules. -[Compliance Contract](https://github.com/OpenZeppelin/stellar-contracts/blob/main/packages/tokens/src/rwa/compliance/mod.rs#L67) uses a hook-based architecture where multiple [compliance modules](https://github.com/OpenZeppelin/stellar-contracts/blob/main/packages/tokens/src/rwa/compliance/mod.rs#L327) can be registered for specific events: - -- **Transferred**: Called after tokens are successfully transferred -- **Created**: Called after tokens are successfully minted -- **Destroyed**: Called after tokens are successfully burned -- **CanTransfer**: Called during transfer validation (read-only) -- **CanCreate**: Called during mint validation (read-only) +Provides a modular framework for implementing custom compliance rules through a hook-based architecture where multiple +[compliance modules](https://github.com/OpenZeppelin/stellar-contracts/blob/main/packages/tokens/src/rwa/compliance/mod.rs#L327) +can be registered to the [Compliance Contract](https://github.com/OpenZeppelin/stellar-contracts/blob/main/packages/tokens/src/rwa/compliance/mod.rs#L67). + +**Compliance Validation Flow:** + +```mermaid +graph TD + A[RWA Token Transfer/Mint] --> B[Compliance Contract] + B --> C{Hook Type
CanTransfer
CanCreate
etc.} + C --> D[Registered Modules 1..N] + D --> E[Transfer Limit Module] + D --> F[Country Restriction Module] + D --> G[Investor Count Module] + D --> H[Custom Module X] + E --> I{All modules
return true?} + F --> I + G --> I + H --> I + I -->|Yes| J[Operation Proceeds] + I -->|No| K[Operation Reverts] +``` The compliance contract is designed to be shared across multiple RWA tokens, with each hook function accepting a `token` parameter to identify the calling token. @@ -367,12 +381,24 @@ Claims are issued by trusted authorities and contain: This module is an implementation detail. It is provided as the suggested implementation for the **Claim-based** approach. -Validates cryptographic claims with support for multiple signature schemes: +Validates cryptographic claims and provides comprehensive claim lifecycle management. The module includes: +**Signature Verification:** - Ed25519 (Stellar native) - Secp256k1 (Ethereum compatible) - Secp256r1 (Enterprise PKI compatible) +**Key Management:** +- Topic-specific key authorization with registry tracking +- Each public key is tied to a signature scheme +- A signing key (public key + scheme) can be authorized to sign claims for specific topic and registry combinations +- The same signing key can be authorized across multiple topics and registries independently + +**Claim Invalidation Mechanisms:** +- **Passive Expiration**: Helper functions to encode/decode expiration metadata (`created_at` and `valid_until` timestamps) within claim data, allowing claims to automatically expire without on-chain action +- **Per-claim Revocation**: Fine-grained revocation of individual claims for precise control +- **Signature Invalidation**: Efficient bulk invalidation via nonce increment for revoking all claims signed by a specific key + ## Extensions The following optional extensions are provided: From 3be8bdb6c64f43bd75c883722a39e50b45b1ad91 Mon Sep 17 00:00:00 2001 From: Ozgun Ozerk Date: Fri, 31 Oct 2025 19:08:47 +0300 Subject: [PATCH 06/16] typo --- content/stellar-contracts/tokens/rwa/rwa.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/stellar-contracts/tokens/rwa/rwa.mdx b/content/stellar-contracts/tokens/rwa/rwa.mdx index ec5c11d7..513fa92a 100644 --- a/content/stellar-contracts/tokens/rwa/rwa.mdx +++ b/content/stellar-contracts/tokens/rwa/rwa.mdx @@ -247,7 +247,7 @@ can be registered to the [Compliance Contract](https://github.com/OpenZeppelin/s ```mermaid graph TD A[RWA Token Transfer/Mint] --> B[Compliance Contract] - B --> C{Hook Type
CanTransfer
CanCreate
etc.} + B --> C{CanTransfer
or
CanCreate} C --> D[Registered Modules 1..N] D --> E[Transfer Limit Module] D --> F[Country Restriction Module] From 44b69fa548c77a1c484856e7c17a63ed1f63b64d Mon Sep 17 00:00:00 2001 From: Ozgun Ozerk Date: Fri, 31 Oct 2025 21:59:52 +0300 Subject: [PATCH 07/16] architecture mermaid --- content/stellar-contracts/tokens/rwa/rwa.mdx | 56 +++++++++++++++++++- 1 file changed, 55 insertions(+), 1 deletion(-) diff --git a/content/stellar-contracts/tokens/rwa/rwa.mdx b/content/stellar-contracts/tokens/rwa/rwa.mdx index 513fa92a..2c347930 100644 --- a/content/stellar-contracts/tokens/rwa/rwa.mdx +++ b/content/stellar-contracts/tokens/rwa/rwa.mdx @@ -30,7 +30,61 @@ security tokens, including: ## Architecture -The RWA suite follows a modular architecture that separates concerns and allows for flexible integration: +The RWA suite follows a modular architecture that separates concerns and allows for flexible integration + +graph TB + + RWA[RWA Token] + COMP[Compliance] + IDV[Identity Verifier] + + subgraph "Compliance Modules (Optional)" + CM1[Transfer Limit Module] + CM2[Country Restriction Module] + CM3[Investor Count Module] + CM4[Custom Modules...] + + CM_TITLE["Compliance Modules (Optional)"] + CM_TITLE ~~~ CM1 + end + + subgraph " " + CTI[Claim Topics & Issuers] + IRS[Identity Registry Storage] + CI[Claim Issuer] + IC[Identity Claims] + + IV_TITLE["Claim-Based Identity Verification"] + IV_TITLE ~~~ IRS + end + + + + CTI ~~~ IRS ~~~ COMP + + subgraph "Optional Extensions" + DM[Document Manager
ERC-1643] + end + + RWA -->|"can_transfer(), can_create(), transferred(), created(), destroyed()"| COMP + RWA -->|"verify_identity()"| IDV + RWA -.-> DM + + COMP --> CM1 + COMP --> CM2 + COMP --> CM3 + COMP --> CM4 + + IDV -->|"get_claim_topics_and_issuers()"| CTI + IDV -->|"stored_identity()
get_recovered_to()"| IRS + IDV -->|"try_is_claim_valid()"| CI + IDV -->|"get_claim_ids_by_topic()
get_claim()"| IC + + CI --> |"has_claim_topic()"| CTI + IC --> |"is_claim_valid()"| CI + + style CM_TITLE fill:none,stroke:#ff9800,stroke-width:2px + style IV_TITLE fill:none,stroke:#ff9800,stroke-width:2px ### Core Components From e42c192ba96097ffa3e3f93c0b3d977c496dff8d Mon Sep 17 00:00:00 2001 From: Ozgun Ozerk Date: Fri, 31 Oct 2025 22:03:31 +0300 Subject: [PATCH 08/16] typo --- content/stellar-contracts/tokens/rwa/rwa.mdx | 2 ++ 1 file changed, 2 insertions(+) diff --git a/content/stellar-contracts/tokens/rwa/rwa.mdx b/content/stellar-contracts/tokens/rwa/rwa.mdx index 2c347930..6860c2c1 100644 --- a/content/stellar-contracts/tokens/rwa/rwa.mdx +++ b/content/stellar-contracts/tokens/rwa/rwa.mdx @@ -32,6 +32,7 @@ security tokens, including: The RWA suite follows a modular architecture that separates concerns and allows for flexible integration +```mermaid graph TB RWA[RWA Token] @@ -85,6 +86,7 @@ graph TB style CM_TITLE fill:none,stroke:#ff9800,stroke-width:2px style IV_TITLE fill:none,stroke:#ff9800,stroke-width:2px +``` ### Core Components From eddf3bd2197cdb42c5f9feae2fb14d05abc765bd Mon Sep 17 00:00:00 2001 From: Ozgun Ozerk Date: Fri, 31 Oct 2025 22:31:24 +0300 Subject: [PATCH 09/16] better mermaid diagrams --- content/stellar-contracts/tokens/rwa/rwa.mdx | 75 +++++++++++--------- 1 file changed, 43 insertions(+), 32 deletions(-) diff --git a/content/stellar-contracts/tokens/rwa/rwa.mdx b/content/stellar-contracts/tokens/rwa/rwa.mdx index 6860c2c1..cea26da7 100644 --- a/content/stellar-contracts/tokens/rwa/rwa.mdx +++ b/content/stellar-contracts/tokens/rwa/rwa.mdx @@ -39,54 +39,34 @@ graph TB COMP[Compliance] IDV[Identity Verifier] - subgraph "Compliance Modules (Optional)" + subgraph "Optional Modules" CM1[Transfer Limit Module] CM2[Country Restriction Module] - CM3[Investor Count Module] - CM4[Custom Modules...] - - CM_TITLE["Compliance Modules (Optional)"] - CM_TITLE ~~~ CM1 + CM3[Other Custom Modules...] end - subgraph " " - CTI[Claim Topics & Issuers] - IRS[Identity Registry Storage] - CI[Claim Issuer] - IC[Identity Claims] - - IV_TITLE["Claim-Based Identity Verification"] - IV_TITLE ~~~ IRS + subgraph "Optional Extensions" + DM[Document Manager
ERC-1643] end + IDV --> IVS - CTI ~~~ IRS ~~~ COMP - subgraph "Optional Extensions" - DM[Document Manager
ERC-1643] + subgraph "Identity Stack" + IVS[Custom Identity Suite] end - RWA -->|"can_transfer(), can_create(), transferred(), created(), destroyed()"| COMP - RWA -->|"verify_identity()"| IDV + RWA -->|"can_transfer()
can_create()
transferred()
created()
destroyed()"| COMP + RWA -->|"verify_identity()
recovery_target()"| IDV RWA -.-> DM COMP --> CM1 COMP --> CM2 COMP --> CM3 - COMP --> CM4 - - IDV -->|"get_claim_topics_and_issuers()"| CTI - IDV -->|"stored_identity()
get_recovered_to()"| IRS - IDV -->|"try_is_claim_valid()"| CI - IDV -->|"get_claim_ids_by_topic()
get_claim()"| IC +``` - CI --> |"has_claim_topic()"| CTI - IC --> |"is_claim_valid()"| CI - style CM_TITLE fill:none,stroke:#ff9800,stroke-width:2px - style IV_TITLE fill:none,stroke:#ff9800,stroke-width:2px -``` ### Core Components @@ -334,8 +314,39 @@ It can also support possible custom implementation approaches: - **Zero-Knowledge**: Privacy-preserving verification with custom ZK circuits - **Other custom approaches**: Any implementation that satisfies the `verify_identity` interface -The default claim-based implementation integrates with the **Claim Topics and Issuers Module** and -Identity Registry Storage. +The architecture of the default claim-based implementation is shown in the diagram below: + +```mermaid +graph TB + + RWA[RWA Token] + IDV[Identity Verifier] + + subgraph " " + CTI[Claim Topics & Issuers] + IRS[Identity Registry Storage] + CI[Claim Issuer] + IC[Identity Claims] + + IV_TITLE["Claim-Based Identity Verification"] + IV_TITLE ~~~ IRS + end + + + + RWA -->|"verify_identity()
recovery_target()"| IDV + + + IDV -->|"get_claim_topics_and_issuers()"| CTI + IDV -->|"stored_identity()
get_recovered_to()"| IRS + IDV -->|"try_is_claim_valid()"| CI + IDV -->|"get_claim_ids_by_topic()
get_claim()"| IC + + CI --> |"has_claim_topic()"| CTI + IC --> |"is_claim_valid()"| CI + + style IV_TITLE fill:none,stroke:#ff9800,stroke-width:2px +``` ### - Claim Topics and Issuers [Source Code](https://github.com/OpenZeppelin/stellar-contracts/tree/main/packages/tokens/src/rwa/claim_topics_and_issuers) From af8b8c5ef35e7c55501d6f2a5a2fdba180804f04 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=96zg=C3=BCn=20=C3=96zerk?= Date: Mon, 3 Nov 2025 17:26:35 +0300 Subject: [PATCH 10/16] Update content/stellar-contracts/tokens/rwa/rwa.mdx Co-authored-by: Boyan Barakov <9572072+brozorec@users.noreply.github.com> --- content/stellar-contracts/tokens/rwa/rwa.mdx | 1 + 1 file changed, 1 insertion(+) diff --git a/content/stellar-contracts/tokens/rwa/rwa.mdx b/content/stellar-contracts/tokens/rwa/rwa.mdx index cea26da7..5d7d504e 100644 --- a/content/stellar-contracts/tokens/rwa/rwa.mdx +++ b/content/stellar-contracts/tokens/rwa/rwa.mdx @@ -390,6 +390,7 @@ Each claim contains: - **Signature**: Cryptographic proof that the issuer created this claim - **Data**: The actual claim information (can include expiration dates, metadata) - **Scheme**: The signature algorithm used (Ed25519, Secp256k1, Secp256r1) +- **Uri**: Optional URI for additional information **How Claims Work:** From 23b20adf09f3d08e8f60ffa02ee53c28340a5f15 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=96zg=C3=BCn=20=C3=96zerk?= Date: Mon, 3 Nov 2025 17:26:57 +0300 Subject: [PATCH 11/16] Update content/stellar-contracts/tokens/rwa/rwa.mdx Co-authored-by: Boyan Barakov <9572072+brozorec@users.noreply.github.com> --- content/stellar-contracts/tokens/rwa/rwa.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/stellar-contracts/tokens/rwa/rwa.mdx b/content/stellar-contracts/tokens/rwa/rwa.mdx index 5d7d504e..b68f5a5d 100644 --- a/content/stellar-contracts/tokens/rwa/rwa.mdx +++ b/content/stellar-contracts/tokens/rwa/rwa.mdx @@ -507,7 +507,7 @@ When implementing RWA tokens, consider the following security aspects: 1. **Authorization**: All administrative functions expect RBAC checks to be enforced on the `operator` parameter 2. **Identity Verification**: Always verify identities before allowing token operations 3. **Compliance Validation**: Ensure compliance rules are properly configured before enabling transfers -4. **Freezing**: Use freezing mechanisms carefully as they can lock user funds +4. **Freezing**: Use freezing mechanisms carefully as they lock user funds 5. **Recovery**: Recovery operations should have strict authorization and verification 6. **Pausability**: The pause mechanism should only be accessible to authorized administrators 7. **Contract Upgrades**: Consider using immutable periphery contracts or implementing upgrade mechanisms carefully From a4d0ad9746e4ec35005836739de33903c392b930 Mon Sep 17 00:00:00 2001 From: Ozgun Ozerk Date: Mon, 3 Nov 2025 17:50:08 +0300 Subject: [PATCH 12/16] suggestions part 1 --- content/stellar-contracts/tokens/rwa/rwa.mdx | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/content/stellar-contracts/tokens/rwa/rwa.mdx b/content/stellar-contracts/tokens/rwa/rwa.mdx index b68f5a5d..e1aa5fa9 100644 --- a/content/stellar-contracts/tokens/rwa/rwa.mdx +++ b/content/stellar-contracts/tokens/rwa/rwa.mdx @@ -46,13 +46,11 @@ graph TB end subgraph "Optional Extensions" - DM[Document Manager
ERC-1643] + DM[Document Manager] end IDV --> IVS - - subgraph "Identity Stack" IVS[Custom Identity Suite] end @@ -510,4 +508,4 @@ When implementing RWA tokens, consider the following security aspects: 4. **Freezing**: Use freezing mechanisms carefully as they lock user funds 5. **Recovery**: Recovery operations should have strict authorization and verification 6. **Pausability**: The pause mechanism should only be accessible to authorized administrators -7. **Contract Upgrades**: Consider using immutable periphery contracts or implementing upgrade mechanisms carefully +7. **Contract Upgrades**: Consider following a secure upgrade strategy for your contracts. See: [Contract Upgrades](/stellar-contracts/utils/upgradeable) From 8d9b97eb2117b6c83e6b8b18319b3b6e5d86c688 Mon Sep 17 00:00:00 2001 From: Ozgun Ozerk Date: Mon, 3 Nov 2025 18:17:24 +0300 Subject: [PATCH 13/16] recovery explanation suggestion --- content/stellar-contracts/tokens/rwa/rwa.mdx | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/content/stellar-contracts/tokens/rwa/rwa.mdx b/content/stellar-contracts/tokens/rwa/rwa.mdx index e1aa5fa9..5e122688 100644 --- a/content/stellar-contracts/tokens/rwa/rwa.mdx +++ b/content/stellar-contracts/tokens/rwa/rwa.mdx @@ -506,6 +506,8 @@ When implementing RWA tokens, consider the following security aspects: 2. **Identity Verification**: Always verify identities before allowing token operations 3. **Compliance Validation**: Ensure compliance rules are properly configured before enabling transfers 4. **Freezing**: Use freezing mechanisms carefully as they lock user funds -5. **Recovery**: Recovery operations should have strict authorization and verification +5. **Recovery**: There are two distinct recovery flows, both requiring strict authorization: + - **Identity Recovery**: Managed by the Identity Registry Storage, transfers the identity contract reference and profile (including country data) from old wallet to new wallet, and creates a recovery mapping + - **Balance Recovery**: Managed by the RWA Token, transfers tokens from old to new account after verifying the identity recovery mapping exists (via `recovery_target()`) 6. **Pausability**: The pause mechanism should only be accessible to authorized administrators 7. **Contract Upgrades**: Consider following a secure upgrade strategy for your contracts. See: [Contract Upgrades](/stellar-contracts/utils/upgradeable) From c32e1cd99fdfb461bb041454c0318b5bb026e3ce Mon Sep 17 00:00:00 2001 From: Ozgun Ozerk Date: Mon, 3 Nov 2025 18:18:26 +0300 Subject: [PATCH 14/16] better explanation --- content/stellar-contracts/tokens/rwa/rwa.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/stellar-contracts/tokens/rwa/rwa.mdx b/content/stellar-contracts/tokens/rwa/rwa.mdx index 5e122688..da4748ac 100644 --- a/content/stellar-contracts/tokens/rwa/rwa.mdx +++ b/content/stellar-contracts/tokens/rwa/rwa.mdx @@ -507,7 +507,7 @@ When implementing RWA tokens, consider the following security aspects: 3. **Compliance Validation**: Ensure compliance rules are properly configured before enabling transfers 4. **Freezing**: Use freezing mechanisms carefully as they lock user funds 5. **Recovery**: There are two distinct recovery flows, both requiring strict authorization: - - **Identity Recovery**: Managed by the Identity Registry Storage, transfers the identity contract reference and profile (including country data) from old wallet to new wallet, and creates a recovery mapping + - **Identity Recovery**: Managed by the Identity Stack (Identity Registry Storage in Claim-Based approach), transfers the identity contract reference and profile (including country data) from old wallet to new wallet, and creates a recovery mapping - **Balance Recovery**: Managed by the RWA Token, transfers tokens from old to new account after verifying the identity recovery mapping exists (via `recovery_target()`) 6. **Pausability**: The pause mechanism should only be accessible to authorized administrators 7. **Contract Upgrades**: Consider following a secure upgrade strategy for your contracts. See: [Contract Upgrades](/stellar-contracts/utils/upgradeable) From 5eabda0737627db3372aa9ac99ba2b349cde8f2a Mon Sep 17 00:00:00 2001 From: Ozgun Ozerk Date: Mon, 3 Nov 2025 18:54:41 +0300 Subject: [PATCH 15/16] mermaid rework --- content/stellar-contracts/tokens/rwa/rwa.mdx | 42 ++++++-------------- 1 file changed, 13 insertions(+), 29 deletions(-) diff --git a/content/stellar-contracts/tokens/rwa/rwa.mdx b/content/stellar-contracts/tokens/rwa/rwa.mdx index da4748ac..27e1c6f1 100644 --- a/content/stellar-contracts/tokens/rwa/rwa.mdx +++ b/content/stellar-contracts/tokens/rwa/rwa.mdx @@ -312,7 +312,7 @@ It can also support possible custom implementation approaches: - **Zero-Knowledge**: Privacy-preserving verification with custom ZK circuits - **Other custom approaches**: Any implementation that satisfies the `verify_identity` interface -The architecture of the default claim-based implementation is shown in the diagram below: +The diagram below illustrates how identity verification works in the claim-based identity stack: ```mermaid graph TB @@ -326,24 +326,14 @@ graph TB CI[Claim Issuer] IC[Identity Claims] - IV_TITLE["Claim-Based Identity Verification"] - IV_TITLE ~~~ IRS end - - - RWA -->|"verify_identity()
recovery_target()"| IDV - + RWA -->|"verify_identity()"| IDV IDV -->|"get_claim_topics_and_issuers()"| CTI - IDV -->|"stored_identity()
get_recovered_to()"| IRS - IDV -->|"try_is_claim_valid()"| CI + IDV -->|"stored_identity()"| IRS + IDV -->|"is_claim_valid()"| CI IDV -->|"get_claim_ids_by_topic()
get_claim()"| IC - - CI --> |"has_claim_topic()"| CTI - IC --> |"is_claim_valid()"| CI - - style IV_TITLE fill:none,stroke:#ff9800,stroke-width:2px ``` ### - Claim Topics and Issuers @@ -392,22 +382,16 @@ Each claim contains: **How Claims Work:** -1. **Issuance**: A trusted authority (e.g., KYC provider) verifies an investor's identity off-chain -2. **Signing**: The authority creates a cryptographic signature over the claim data using their private key -3. **Storage**: The claim is stored on-chain in the investor's identity contract -4. **Verification**: When the investor tries to receive tokens, the RWA contract: - - Retrieves the required claims from the identity contract - - Validates the cryptographic signatures using the issuer's public key - - Checks that the claims haven't expired or been revoked - - Ensures the issuer is trusted and authorized for those claim topics +1. **Off-chain Verification**: KYC Provider verifies investor's identity documents off-chain +2. **Off-chain Signing**: KYC Provider signs the claim with their private key off-chain +3. **On-chain Storage**: Signed claim is stored in the investor's Identity Contract +4. **Token Validation**: When investor attempts to receive tokens, the RWA Token: + - Retrieves claims from the Identity Contract + - Calls the Claim Issuer Contract to validate signatures + - Checks for revocations (stored in Claim Issuer Contract) + - Verifies the issuer is trusted (via Claim Topics and Issuers registry) -**Example Flow:** -``` -Investor → KYC Provider (off-chain verification) - → Claim Issuer Contract (signs claim with private key) - → Identity Contract (stores signed claim on-chain) - → RWA Token (validates claim during transfer/mint) -``` +**Note:** The KYC Provider and Claim Issuer are the same entity. Signing happens off-chain; only the signed claim and revocation data are stored on-chain. ### - Identity Registry Storage From 6aac1e97b3d2b2c695fb4f5f19ad10f6cce33103 Mon Sep 17 00:00:00 2001 From: Ozgun Ozerk Date: Tue, 4 Nov 2025 13:13:36 +0300 Subject: [PATCH 16/16] architecture overview mermaid --- content/stellar-contracts/tokens/rwa/rwa.mdx | 43 ++++++++++++++++++++ 1 file changed, 43 insertions(+) diff --git a/content/stellar-contracts/tokens/rwa/rwa.mdx b/content/stellar-contracts/tokens/rwa/rwa.mdx index 27e1c6f1..4e6e48d2 100644 --- a/content/stellar-contracts/tokens/rwa/rwa.mdx +++ b/content/stellar-contracts/tokens/rwa/rwa.mdx @@ -482,6 +482,49 @@ Features: - Efficient storage with bucket-based architecture (supports up to 10,000 tokens) - Swap-remove pattern for compact storage +## Architecture Overview + +Now that we've covered each module individually, let's see how they work together. We'll walk through a `transfer()` operation to illustrate how the components interact: + +```mermaid +sequenceDiagram + participant InvestorA + participant Token + participant IdentityVerifier + participant IdentityRegistryStorage + participant ClaimTopicsAndIssuers + participant TrustedIssuer + participant InvestorB IdentityClaims + participant ComplianceContract + + Note over Token,ComplianceContract: 1. Eligibility + + InvestorA->>Token: transfer(B, amount) + Token->>IdentityVerifier: is_verified(B) + + IdentityVerifier->>IdentityRegistryStorage: Fetch identity: stored_identity(B) + IdentityVerifier->>ClaimTopicsAndIssuers: Fetch required claims and issuers: get_claim_topics_and_issuers() + + loop every pair of claim topic and issuer + IdentityVerifier->>InvestorB IdentityClaims: Fetch claim ids: get_claim_ids_by_topic() + loop every claim + IdentityVerifier->>InvestorB IdentityClaims: Fetch claim: get_claim() + IdentityVerifier->>TrustedIssuer: Check validity: is_claim_valid() + end + end + + IdentityVerifier-->>Token: B eligible + + Note over Token,ComplianceContract: 2. Compliance + + Token->>ComplianceContract: can_transfer(A, B, amount) + ComplianceContract->>ComplianceContract: checks all compliance modules + ComplianceContract-->>Token: transfer compliant + + Token->>Token: process transfer + Token->>InvestorA: notification hook: transferred() +``` + ## Security Considerations When implementing RWA tokens, consider the following security aspects: