hostbasket/specs/rwda/README.md

# Real World Digital Asset (RWDA) Specifications

This document outlines the specifications for Real World Digital Assets (RWDAs) within the Digital Freezone Customer Portal.

## Overview

Real World Digital Assets (RWDAs) represent digitized ownership of real-world assets, providing users with the ability to invest in, trade, and manage these assets through the Digital Freezone platform. RWDAs bridge traditional assets with digital infrastructure, enabling fractional ownership, improved liquidity, and streamlined management.

## RWDA Core Components

### 1. Asset Information

#### 1.1. Basic Information
- **Name**: Unique, descriptive name of the asset
- **Symbol**: Trading symbol/ticker (e.g., BTC, ETH)
- **Description**: Comprehensive description of the asset and its underlying value
- **Asset Type**: Classification (e.g., Real Estate, Business Equity (Shares), Commodity (Gold, Copper))
- **Creation Date**: When the RWDA was created/tokenized
- **Issuer**: Entity responsible for creating and managing the RWDA, needs to be linked to a Entity in ZDFZ

#### 1.2. Media and Documentation
- **Logo/Image**: Visual representation of the asset
- **Documents**: Associated legal documents, prospectus, terms and conditions
- **Website**: Link to official website or documentation
- **Video**: Promotional or explanatory video content (if available)

#### 1.3. Categorization
- **Primary Category**: Main classification
- **Subcategories**: More specific classifications
- **Tags**: Keywords for searchability
- **Geographic Location**: Physical location of the underlying asset (if applicable)
- **Industry/Sector**: Economic sector classification

### 2. Financial Details

#### 2.1. Ownership Structure
- **Total Shares/Units**: Number of shares/units available
- **Share Value**: Current value per share/unit
- **Minimum Investment**: Smallest amount/units that can be purchased
- **Maximum Investment**: Largest amount/units that can be purchased by a single investor (if limited)
- **Market Cap**: Total value of all shares (Share Value × Total Shares)

#### 2.2. Performance Metrics
- **Historical Performance**: Price history and trends
- **Return on Investment (ROI)**: Historical and projected returns
- **Volatility Metrics**: Measures of price stability
- **Benchmark Comparison**: Performance relative to relevant benchmarks
- **Risk Assessment**: Quantitative and qualitative risk evaluation

#### 2.3. Financial Operations
- **Dividend Information**: Frequency, calculation method, distribution mechanism
- **Fee Structure**: Management fees, transaction fees, performance fees
- **Liquidity Provisions**: Mechanisms for buying/selling, liquidity guarantees
- **Valuation Methodology**: How asset value is determined and updated
- **Financial Reporting**: Frequency and type of financial reports provided

### 3. Terms & Conditions

#### 3.1. Ownership Rights
- **Voting Rights**: Whether ownership confers voting rights and how they work
- **Dividend Rights**: Entitlement to profits or revenue
- **Underlying Asset Rights**: Access or rights to the physical asset (if applicable)
- **Governance Participation**: Ability to participate in management decisions

#### 3.2. Restrictions
- **Vesting Period**: Time before shares become fully owned
- **Lock-in Period**: Time during which shares cannot be sold
- **Transfer Restrictions**: Rules governing asset transfers between users
- **Jurisdictional Limitations**: Geographic or regulatory restrictions
- **Investor Qualification**: Requirements for investors (accreditation, KYC level, etc.)

#### 3.3. Legal Framework
- **Governing Law**: Jurisdiction governing the asset (will normally be ZDFZ)
- **Regulatory Compliance**: Applicable regulations and compliance status (there should be a default)
- **Dispute Resolution**: Process for resolving disputes (ZDFZ)
- **Liability Limitations**: Extent of issuer and platform liability
- **Termination Conditions**: Circumstances under which the RWDA can be terminated

## RWDA User Interface Requirements

### 1. RWDA Listing and Discovery

#### 1.1. Marketplace View
- Grid/list view with filtering and sorting options
- Search functionality with advanced filters (*)
- Category and tag-based navigation
- Featured and trending asset highlights (*)

#### 1.2. RWDA Cards
- Asset name and symbol
- Primary image/logo
- Current price and change percentage
- Key metrics (market cap, risk level, etc.)
- Quick action buttons (view details, add to watchlist)

#### 1.3. Search and Filter
- Text search across name, description, and tags
- Filters for:
  - Asset type
  - Price range
  - Location


### 2. RWDA Detail View

#### 2.1. Overview Section
- Asset name, symbol, and type
- Current price and historical chart
- Key metrics dashboard
- Description and highlights
- Action buttons (buy, add to watchlist, share)
- Link to our main website/wiki (ebook e.g. docusaurus)

#### 2.2. Financial Information
- Detailed price information
- Historical performance charts (*)
- Return metrics
- Dividend history (if applicable) (*)
- Fee structure
- Financial projections (if available)

#### 2.3. Documentation

- Prospectus and offering documents
- Legal agreements
- Financial reports
- Regulatory filings
- Terms and conditions

#### 2.4. Asset-Specific Information

Will all be part of the ebook, doesn't have to be structured in DB

- For Real Estate: Location, size, amenities, occupancy
- For Business Equity: Business model, team, market position
- For Commodities: Storage, quality, certification
- For Intellectual Property: Protection status, licensing terms

### 3. RWDA Transaction Interfaces

#### 3.1. Purchase Interface

- Quantity/amount selection
- Price information with total calculation
- Fee disclosure
- Payment method selection (money comes from wallet)
- Terms acceptance
- Confirmation process

#### 3.2. Portfolio View

- Holdings summary with total value
- Individual asset performance
- Allocation visualization
- Transaction history
- Dividend/return tracking

#### 3.3. Transfer Interface (if allowed)

- Recipient selection/input
- Quantity/amount specification
- Fee disclosure
- Transfer confirmation
- Receipt generation

## RWDA Data Model

### 1. Core Asset Data

> TODO: needs to be checked

```
RWDA {
  id: String                    // Unique identifier
  name: String                  // Asset name
  symbol: String                // Trading symbol
  description: String           // Comprehensive description
  assetType: AssetType          // Type classification
  creationDate: DateTime        // Creation timestamp
  issuer: Entity                // Issuing entity
  
  // Media
  logo: ImageURL                // Primary image
  gallery: [ImageURL]           // Additional images
  documents: [Document]         // Associated documents
  website: URL                  // Official website
  videoURL: URL                 // Promotional video
  
  // Categorization
  primaryCategory: Category     // Main classification
  subcategories: [Category]     // Specific classifications
  tags: [String]                // Search keywords
  geographicLocation: Location  // Physical location
  industrySector: Sector        // Economic sector
  
  // Financial
  totalShares: Number           // Total available shares
  shareValue: Currency          // Value per share
  minimumInvestment: Number     // Minimum purchase
  maximumInvestment: Number     // Maximum purchase
  marketCap: Currency           // Total value
  
  // Performance
  historicalPrices: [PricePoint] // Price history
  roi: Percentage               // Return on investment
  volatility: Number            // Volatility metric
  riskAssessment: RiskLevel     // Risk evaluation
  
  // Operations
  dividendStructure: Dividend   // Dividend information
  feeStructure: [Fee]           // Associated fees
  liquidityProvisions: String   // Liquidity details
  valuationMethod: String       // Valuation approach
  reportingFrequency: String    // Reporting schedule
  
  // Terms
  votingRights: Boolean         // Has voting rights
  dividendRights: Boolean       // Has dividend rights
  underlyingAssetRights: String // Rights to physical asset
  governanceRights: String      // Governance participation
  
  // Restrictions
  vestingPeriod: Duration       // Vesting timeframe
  lockInPeriod: Duration        // Lock-in timeframe
  transferRestrictions: String  // Transfer rules
  jurisdictionalLimitations: [String] // Geographic restrictions
  investorQualifications: [String] // Investor requirements
  
  // Legal
  governingLaw: String          // Governing jurisdiction
  regulatoryCompliance: String  // Compliance status
  disputeResolution: String     // Dispute process
  liabilityLimitations: String  // Liability details
  terminationConditions: String // Termination rules
  
  // Technical
  digitalRepresentation: String // Digital representation method
  fractionalPrecision: Number   // Decimal places
  ownershipTracking: String     // Tracking mechanism
  certificateFormat: String     // Certificate details
  
  // Security
  ownershipVerification: String // Verification method
  transferSecurity: String      // Transfer security
  auditTrail: Boolean           // Has audit trail
  backupMechanisms: String      // Backup details
}
```

### 2. Related Data Structures

```
PricePoint {
  timestamp: DateTime           // Time of price
  price: Currency               // Price value
  volume: Number                // Trading volume
}

Dividend {
  frequency: String             // Payment frequency
  calculationMethod: String     // How calculated
  distributionMechanism: String // How distributed
  nextPaymentDate: DateTime     // Next payment
  historicalPayments: [Payment] // Payment history
}

Payment {
  date: DateTime                // Payment date
  amount: Currency              // Payment amount
  perShareAmount: Currency      // Amount per share
}

Fee {
  type: String                  // Fee type
  amount: Currency or Percentage // Fee amount
  frequency: String             // When charged
  description: String           // Fee details
}

Document {
  type: String                  // Document type
  title: String                 // Document title
  url: URL                      // Document location
  uploadDate: DateTime          // Upload timestamp
  version: String               // Document version
}
```

## RWDA Workflows

### 1. RWDA Creation and Listing

> will be manual scripts populating the DB

1. Asset identification and valuation
2. Legal structure establishment
3. Digital representation creation
4. Documentation preparation
5. Regulatory compliance verification
6. Platform listing and publication

### 2. RWDA Purchase

1. User discovers RWDA
2. User reviews RWDA details
3. User initiates purchase
4. User specifies quantity/amount
5. User confirms purchase
6. System processes transaction
7. Ownership is recorded
8. User receives confirmation

### 3. RWDA Management (operator)

1. User views portfolio
2. User monitors performance
3. User receives dividends/returns
4. User accesses documentation
5. User participates in governance (if applicable)

### 4. RWDA Transfer (if allowed)

1. User initiates transfer
2. User specifies recipient and amount
3. System verifies eligibility
4. User confirms transfer
5. System processes transfer
6. Both parties receive confirmation

### 5. RWDA Termination (if applicable) (*)

1. Termination conditions are met
2. Users are notified
3. Final distributions are calculated
4. Payments are processed
5. RWDA is archived