Proposal RWA Asset Metadata and Oracle Extension

[aguilar1x]

Proposal

Title: RWA Asset Metadata and Oracle Extension
Author: OppiaLabs, Matias Aguilar <@aguilar1x>
Status: Draft
Created: 2026-02-05
Updated: 2026-02-05
Version: 0.0.1
Discussion: https://github.com/stellar/stellar-protocol/discussions/1878

Simple Summary

A standard metadata schema for Real-World Asset (RWA) tokens on Stellar and
a Soroban oracle interface extension for storing and querying that metadata
on-chain.

Dependencies

• SEP-1: for off-chain metadata publication via
  stellar.toml.
• SEP-40: for the base oracle price feed interface that this
  SEP extends.
• SEP-41: for the standard fungible token interface.
• SEP-57: for the T-REX regulated token framework
  (complementary — this SEP handles metadata and oracle, not compliance).

Motivation

RWA tokens on Stellar require standardized, verifiable metadata — asset
type, jurisdiction, valuation method, underlying asset details, legal
documentation and access to trustworthy price feeds that understand the
nature of the asset being quoted. Today each issuer defines ad-hoc metadata
and deploys custom oracle contracts. This fragmentation creates three
problems:

1. Wallets and explorers cannot display RWA information consistently
   because there is no shared schema.
2. DeFi contracts (lending, vaults, DEXes) consuming RWA price feeds
   cannot access asset-level context such as type, jurisdiction, or
   tokenization details, limiting risk assessment capabilities.
3. Issuers must build bespoke integrations for every consumer, instead
   of implementing a single standard interface.

SEP-40 standardizes generic price feeds but has no concept of asset
metadata. SEP-57 (T-REX) standardizes regulated token operations
(compliance, identity, freezing) but does not address metadata or oracle
integration. This SEP fills the gap between both by defining:

• A metadata schema for describing RWA assets.
• An oracle extension that augments SEP-40 with RWA metadata storage
  and query functions.
• An integration pattern for how SEP-41/SEP-57 token contracts consume
  RWA metadata from the oracle.

Abstract

This SEP introduces two complementary specifications:

1. A metadata schema describing RWA assets through a standardized set
   of fields and enumerations. The schema can be published off-chain via
   SEP-1 (stellar.toml) as JSON, and on-chain via Soroban oracle
   contracts.

2. A Soroban oracle extension interface that adds RWA metadata
   functions on top of the SEP-40 price feed interface. An oracle
   implementing this SEP MUST also implement SEP-40, and additionally
   expose functions for registering, updating, and querying RWA metadata
   and tokenization information.

The combination enables wallets, explorers, DeFi protocols, and token
contracts to discover and consume RWA information through a uniform
interface, regardless of the oracle provider or asset issuer.

Specification

1. RWA Metadata Schema

1.1 Off-Chain Representation (JSON)

RWA metadata MAY be published off-chain as JSON. Recommended hosting
methods:

• As an entry under [[CURRENCIES]] in stellar.toml per SEP-1.
• As a JSON document at a stable URI referenced by the token contract or
  stellar.toml.

Required fields:

{
  "schema_version": "1.0",
  "asset_type": "REAL_ESTATE",
  "name": "Tokenized Office Building - 123 Main St",
  "underlying_asset": "Commercial real estate, Miami FL",
  "issuer": "G...",
  "jurisdiction": "US"
}

Optional fields:

{
  "description": "Grade-A office building, 50,000 sq ft",
  "valuation_method": "APPRAISAL",
  "legal_docs_uri": "https://issuer.example/docs/offering.pdf",
  "external_ids": {
    "isin": "US000000001",
    "lei": "5493001KJTIIGC8Y1R12",
    "cusip": "000000001"
  },
  "tokenization": {
    "token_contract": "C...",
    "total_supply": 1000000,
    "underlying_asset_id": "BLDG-123-MAIN",
    "tokenization_date": "2026-01-15"
  },
  "metadata": {
    "maturity_date": "2031-01-15",
    "coupon_rate": "5.25",
    "audit_report_uri": "https://issuer.example/docs/audit-2025.pdf"
  }
}

1.2 Asset Type Enum

The asset_type field MUST be one of the following values:

Value	Description
REAL_ESTATE	Commercial or residential real estate
EQUITY	Stocks, shares, or equity instruments
BOND	Government or corporate bonds
COMMODITY	Physical commodities (gold, oil, grain)
INVOICE	Trade receivables and invoice factoring
FUND	ETFs, mutual funds, or pooled investments
PRIVATE_DEBT	Private credit and loan instruments
INFRASTRUCTURE	Infrastructure projects and utilities
OTHER	Any other RWA not covered above

If asset_type is OTHER, the issuer SHOULD include an
asset_type_detail string describing the asset category.

1.3 Valuation Method Enum

The optional valuation_method field MUST be one of:

Value	Description
APPRAISAL	Professional third-party appraisal
MARKET	Market-based pricing (comparable sales/trades)
INDEX	Index-linked pricing
ORACLE	On-chain oracle price feed
NAV	Net Asset Value calculation (funds)
OTHER	Other valuation methodology

---

2. On-Chain Data Types (Soroban)

The following Soroban contract types correspond to the JSON schema above
and are used by the oracle extension interface.

/// RWA asset type classification
#[contracttype]
#[derive(Clone, Debug, PartialEq, Eq)]
pub enum RWAAssetType {
    RealEstate,
    Equity,
    Bond,
    Commodity,
    Invoice,
    Fund,
    PrivateDebt,
    Infrastructure,
    Other,
}

/// Valuation methodology
#[contracttype]
#[derive(Clone, Debug, PartialEq, Eq)]
pub enum ValuationMethod {
    Appraisal,
    Market,
    Index,
    Oracle,
    Nav,
    Other,
}

/// Tokenization details for an RWA
#[contracttype]
#[derive(Clone, Debug)]
pub struct TokenizationInfo {
    /// Token contract address (if tokenized)
    pub token_contract: Option<Address>,
    /// Total token supply
    pub total_supply: Option<i128>,
    /// Identifier of the underlying off-chain asset
    pub underlying_asset_id: Option<String>,
    /// Tokenization date (unix timestamp)
    pub tokenization_date: Option<u64>,
}

/// Complete on-chain RWA metadata
#[contracttype]
#[derive(Clone, Debug)]
pub struct RWAMetadata {
    /// Asset identifier (code or symbol in the oracle)
    pub asset_id: Symbol,
    /// Human-readable name
    pub name: String,
    /// Description of the asset
    pub description: String,
    /// RWA asset type classification
    pub asset_type: RWAAssetType,
    /// Underlying asset identifier or description
    pub underlying_asset: String,
    /// Issuer address
    pub issuer: Address,
    /// Jurisdiction code (ISO 3166-1 alpha-2)
    pub jurisdiction: Symbol,
    /// Tokenization information
    pub tokenization_info: TokenizationInfo,
    /// External identifiers (ISIN, LEI, CUSIP, etc.)
    pub external_ids: Vec<(Symbol, String)>,
    /// URI pointing to legal documentation
    pub legal_docs_uri: Option<String>,
    /// Valuation methodology
    pub valuation_method: ValuationMethod,
    /// Extensible key-value metadata
    pub metadata: Vec<(Symbol, String)>,
    /// Creation timestamp
    pub created_at: u64,
    /// Last update timestamp
    pub updated_at: u64,
}

---

3. Oracle Extension Interface (Soroban)

An oracle implementing this SEP MUST implement the SEP-40
PriceFeedTrait interface for price data, and MUST additionally implement
the following RWA metadata functions.

3.1 Admin Functions

These functions MUST require authorization from the oracle admin.

/// Register or update RWA metadata for an asset.
fn set_rwa_metadata(env: &Env, asset_id: Symbol, metadata: RWAMetadata);

/// Update tokenization info for a previously registered asset.
fn update_tokenization_info(
    env: &Env,
    asset_id: Symbol,
    tokenization_info: TokenizationInfo,
);

/// Set the maximum acceptable age (in seconds) for price data.
/// Consumer contracts SHOULD reject prices older than this threshold.
fn set_max_staleness(env: &Env, max_seconds: u64);

3.2 Query Functions

These functions MUST be callable by any account without authorization.

/// Get complete RWA metadata for an asset.
/// Returns None if asset_id is not registered.
fn get_rwa_metadata(env: &Env, asset_id: Symbol) -> Option<RWAMetadata>;

/// Get the RWA asset type for an asset.
/// Returns None if asset_id is not registered.
fn get_rwa_asset_type(env: &Env, asset: Asset) -> Option<RWAAssetType>;

/// Get tokenization info for an asset.
/// Returns None if asset_id is not registered.
fn get_tokenization_info(
    env: &Env,
    asset_id: Symbol,
) -> Option<TokenizationInfo>;

/// Get all registered RWA asset identifiers.
fn get_all_rwa_assets(env: &Env) -> Vec<Symbol>;

/// Resolve a token contract address to its oracle asset identifier.
/// Returns None if no mapping exists.
fn get_asset_id_from_token(
    env: &Env,
    token_address: Address,
) -> Option<Symbol>;

/// Get the configured maximum staleness in seconds.
fn max_staleness(env: &Env) -> u64;

3.3 Relationship with SEP-40

An oracle implementing this SEP MUST also implement the following SEP-40
functions for price data:

• base(env) -> Asset
• assets(env) -> Vec<Asset>
• decimals(env) -> u32
• resolution(env) -> u32
• lastprice(env, asset) -> Option<PriceData>
• price(env, asset, timestamp) -> Option<PriceData>
• prices(env, asset, records) -> Option<Vec<PriceData>>

This SEP does not redefine any SEP-40 types or functions. The Asset,
PriceData, and PriceFeedTrait definitions from SEP-40 apply unchanged.

---

4. Token Contract Integration Pattern

A token contract implementing SEP-41 (or SEP-57) MAY integrate with an
oracle implementing this SEP by storing the oracle contract address and
the asset symbol that identifies the token in the oracle.

4.1 Recommended Token Functions

Token contracts MAY expose the following convenience functions that proxy
oracle data:

/// Get the oracle contract address this token is linked to.
fn asset_contract(env: Env) -> Address;

/// Get the oracle asset symbol this token tracks.
fn pegged_asset(env: Env) -> Symbol;

/// Get the current price from the linked oracle.
fn get_price(env: Env) -> Option<PriceData>;

/// Get the price at a specific timestamp from the linked oracle.
fn get_price_at(env: Env, timestamp: u64) -> Option<PriceData>;

/// Get oracle price decimals.
fn oracle_decimals(env: Env) -> u32;

/// Get RWA metadata from the linked oracle.
fn get_rwa_metadata(env: Env) -> Option<RWAMetadata>;

/// Get the asset type from the linked oracle.
fn get_asset_type(env: Env) -> Option<RWAAssetType>;

4.2 Compliance Integration

This SEP does not define compliance logic. Token contracts requiring
compliance checks (identity verification, transfer restrictions, freezing)
SHOULD implement SEP-57 (T-REX), which provides a modular compliance and
identity verification framework. The oracle defined in this SEP is
complementary to SEP-57: the oracle provides asset-level metadata and
pricing, while SEP-57 provides participant-level compliance and
identity.

---

5. Price Staleness

Consumer contracts SHOULD verify that price data is not stale before
using it. The recommended check is:

current_ledger_timestamp - price.timestamp <= oracle.max_staleness()

Oracle operators SHOULD set max_staleness to a value appropriate for the
asset class. For example:

• Equities and commodities with active markets: 300–900 seconds
• Real estate with periodic appraisals: 86,400 seconds (1 day) or more
• Bonds with daily NAV: 86,400 seconds

Design Rationale

1. Why extend SEP-40 instead of a new oracle interface?

SEP-40 is the established oracle standard on Stellar, implemented by
Reflector and consumed by DeFi protocols. Defining a new parallel oracle
interface would fragment the ecosystem. By extending SEP-40, RWA oracles
remain compatible with existing consumers that only need price data, while
RWA-aware consumers can query the additional metadata functions.

2. Why both on-chain and off-chain metadata?

On-chain metadata (via oracle) enables smart contracts to consume asset
information programmatically a lending protocol can check
asset_type to apply different collateral factors, or jurisdiction to
enforce geographic restrictions. Off-chain metadata (via SEP-1 JSON)
enables wallets and explorers to display rich information without
on-chain queries. Both channels serve different consumers and SHOULD
contain consistent data.

3. Why a fixed asset type enum?

A fixed enum enables wallets to display consistent icons, categories, and
risk indicators across all RWA tokens. The OTHER variant with
asset_type_detail provides an escape hatch for novel asset classes. New
enum values can be added in future versions of this SEP via the standard
SEP versioning process.

4. Why external_ids as a key value vector?

Different jurisdictions and asset classes use different identifier systems
(ISIN for securities, LEI for legal entities, CUSIP for North American
instruments). A key value structure avoids hard coding specific identifier
systems and allows the schema to accommodate any present or future
standard.

Security Concerns

Oracle Trust

Oracles are trusted dependencies. A compromised oracle can report
incorrect metadata or prices, leading to misinformed decisions by
consumers. Issuers and oracle operators SHOULD:

• Publish governance policies describing who can update metadata and
  prices.
• Use multisig or timelocked admin keys.
• Maintain audit logs of metadata changes.

Off-Chain Metadata Integrity

Clients MUST treat off-chain JSON metadata (from stellar.toml or URIs)
as untrusted. Where possible, clients SHOULD cross-reference off-chain
metadata with on-chain values stored in the oracle.

Price Staleness and Manipulation

Consumer contracts MUST check price timestamps against max_staleness
before relying on price data. RWA assets are often illiquid, meaning price
updates may be infrequent and more susceptible to manipulation than
actively traded assets. Consumers SHOULD apply time-weighted averaging
(TWAP) where appropriate, per SEP-40 recommendations.

Metadata Mutability

Oracle admins can update metadata at any time via set_rwa_metadata. This
is necessary because RWA metadata legitimately changes (jurisdictions,
valuations, legal documents). However, consumers relying on metadata for
critical decisions SHOULD monitor metadata change events and re-evaluate
when changes occur.

Changelog

• v0.0.1: Initial draft.

[Villarley]

Great approach, RWAs are complex and there's no exact SEP approach to create one. T-REX it's great but here I see great improvements.

[FabianSanchezD]

This is great! RWAs need standardized metadata and extending the SEP-40 is a good solution to fix this. The issue that you mentioned that wallets/explorers get fragmented data is true!