Real World Asset Tokenization Smart Contract

README.md

@@ -1 +1,92 @@
-Comprehensive Asset Tokenization Guideline
+# Real World Asset Token Smart Contract
+
+## Overview
+
+This Clarity smart contract implements a comprehensive system for tokenizing real-world assets on the Stacks blockchain. It provides advanced features for asset management, token distribution, governance, and price feed integration.
+
+## Key Features
+
+1. Asset Registration and Management
+2. Semi-Fungible Token (SFT) Implementation
+3. Dividend Distribution System
+4. Governance Proposal and Voting Mechanism
+5. KYC (Know Your Customer) Integration
+6. Price Feed Oracle Integration
+7. Robust Input Validation and Error Handling
+
+## Core Functions
+
+### Asset Management
+
+- `register-asset`: Register a new real-world asset
+- `claim-dividends`: Claim dividends for a specific asset
+
+### Governance
+
+- `create-proposal`: Create a new governance proposal
+- `vote`: Vote on an existing proposal
+
+### Read-Only Functions
+
+- `get-asset-info`: Retrieve information about a specific asset
+- `get-balance`: Get the token balance of an address for a specific asset
+- `get-proposal`: Retrieve details of a specific proposal
+- `get-vote`: Get voting information for a specific proposal and voter
+- `get-price-feed`: Retrieve price feed information for an asset
+- `get-last-claim`: Get the last dividend claim amount for an address
+
+## Data Structures
+
+- `assets`: Stores metadata and state for each registered asset
+- `token-balances`: Tracks token ownership for each asset
+- `kyc-status`: Manages KYC approval status and levels for addresses
+- `proposals`: Stores governance proposal details
+- `votes`: Records votes cast on proposals
+- `dividend-claims`: Tracks dividend claims for each asset and address
+- `price-feeds`: Manages price feed data for assets
+
+## Constants
+
+- `MAX-ASSET-VALUE`: 1 trillion (1,000,000,000,000)
+- `MIN-ASSET-VALUE`: 1 thousand (1,000)
+- `MAX-DURATION`: ~1 day in blocks (144)
+- `MIN-DURATION`: ~1 hour in blocks (12)
+- `MAX-KYC-LEVEL`: 5
+- `MAX-EXPIRY`: ~1 year in blocks (52,560)
+- `tokens-per-asset`: 100,000 (number of SFTs per asset)
+
+## Error Handling
+
+The contract uses a comprehensive set of error codes for various scenarios, ensuring proper validation and error reporting. Some key error codes include:
+
+- `err-owner-only`: Operation restricted to contract owner
+- `err-not-found`: Requested item not found
+- `err-invalid-amount`: Invalid token or value amount
+- `err-not-authorized`: User not authorized for the operation
+- `err-kyc-required`: KYC approval required for the operation
+
+## Input Validation
+
+The contract implements several helper functions for input validation:
+
+- `validate-asset-value`: Ensures asset value is within allowed range
+- `validate-duration`: Checks if proposal duration is valid
+- `validate-kyc-level`: Verifies KYC level is within allowed range
+- `validate-expiry`: Ensures expiry is set to a valid future block height
+- `validate-minimum-votes`: Checks if minimum vote count is valid
+- `validate-metadata-uri`: Verifies metadata URI length and format
+
+## Usage
+
+To use this contract, deploy it to the Stacks blockchain and interact with it using the provided public functions. Ensure that users have the necessary permissions and meet the required conditions (e.g., KYC approval) for their intended actions.
+
+## Security Considerations
+
+- Only the contract owner can register new assets
+- KYC checks are implemented for certain operations
+- Input validation is performed to prevent invalid data entry
+- Proposal voting has minimum token holding requirements
+
+## Note on Completeness
+
+This README is based on the provided contract snippet. Some functionalities, such as KYC management and price feed updates, may not be fully represented here if they were not included in the provided code.

tokenizer/.gitignore

@@ -0,0 +1,4 @@
+
+settings/Mainnet.toml
+settings/Testnet.toml
+history.txt

tokenizer/.vscode/settings.json

@@ -0,0 +1,4 @@
+
+{
+    "deno.enable": true,
+}

tokenizer/.vscode/tasks.json

@@ -0,0 +1,18 @@
+
+{
+    "version": "2.0.0",
+    "tasks": [
+        {
+            "label": "check contracts",
+            "group": "test",
+            "type": "shell",
+            "command": "clarinet check"
+        },
+        {
+            "label": "test contracts",
+            "group": "test",
+            "type": "shell",
+            "command": "clarinet test"
+        }
+    ]
+}

tokenizer/Clarinet.toml

@@ -0,0 +1,22 @@
+[project]
+name = "tokenizer"
+authors = []
+description = ""
+telemetry = true
+requirements = []
+[contracts.rwa]
+path = "contracts/rwa.clar"
+depends_on = []
+
+[repl]
+costs_version = 2
+parser_version = 2
+
+[repl.analysis]
+passes = ["check_checker"]
+
+[repl.analysis.check_checker]
+strict = false
+trusted_sender = false
+trusted_caller = false
+callee_filter = false

tokenizer/README.md

@@ -0,0 +1,77 @@
+## Overview
+
+The Real World Asset Tokenization Smart Contract enables the representation of physical assets (e.g., real estate, art, precious metals) as digital tokens. This contract introduces features like asset registration, dividend distribution, compliance via KYC checks, and voting-based governance. Tokenization allows fractional ownership, enabling smaller investors to invest in traditionally illiquid assets.
+
+## Features
+
+- **Asset Registration**: Register assets with metadata, value, and ownership details.
+- **Fractional Ownership**: Assets are divided into smaller, tradeable tokens.
+- **Dividend Distribution**: Distribute dividends to token holders based on ownership.
+- **KYC Compliance**: Enforce KYC levels to ensure only verified addresses can hold assets.
+- **Governance**: Implement on-chain voting for asset-related decisions.
+- **Price Feed Integration**: Track asset prices and update them periodically.
+
+## Contract Components
+
+### Constants
+- Define essential values like the maximum asset value, durations for proposals, and KYC levels.
+- Include error codes for ease of debugging and user-friendly error handling.
+
+### Data Maps
+- `assets`: Stores asset details, including ownership, metadata, and valuation.
+- `token-balances`: Manages token balances for each asset holder.
+- `kyc-status`: Keeps track of KYC approval levels for participants.
+- `proposals` and `votes`: Implements governance features, allowing token holders to create and vote on proposals.
+- `dividend-claims`: Records dividend claims for individual asset holders.
+- `price-feeds`: Maintains price data for assets.
+
+### Helper Functions
+- **Input Validators**: Ensure input values (e.g., asset value, duration) conform to specified criteria.
+- **Utility Functions**: Retrieve asset and proposal IDs and verify KYC compliance.
+
+## Functions
+
+### Public Functions
+
+- **Asset Management**
+  - `register-asset(metadata-uri, asset-value)`: Registers a new asset, specifying metadata and valuation. Only the contract owner can register assets.
+  - `claim-dividends(asset-id)`: Allows token holders to claim dividends based on their share of ownership.
+
+- **Governance and Voting**
+  - `create-proposal(asset-id, title, duration, minimum-votes)`: Creates a proposal for asset-related decisions. A minimum amount of tokens is required to participate.
+  - `vote(proposal-id, vote-for, amount)`: Enables token holders to vote on proposals by committing a specific amount of tokens.
+
+### Read-Only Functions
+
+- `get-asset-info(asset-id)`: Retrieves detailed information about a specific asset.
+- `get-balance(owner, asset-id)`: Checks the token balance of a particular owner for an asset.
+- `get-proposal(proposal-id)`: Fetches details of a specific proposal.
+- `get-price-feed(asset-id)`: Returns the current price information for an asset.
+
+### Private Functions
+
+- `get-next-asset-id()`, `get-next-proposal-id()`: Retrieve unique IDs for new assets or proposals.
+- `validate-asset-value(value)`, `validate-duration(duration)`, etc.: Helper functions to validate input values, improving contract security and integrity.
+
+## Setup and Deployment
+
+1. **Prerequisites**: Ensure you have Clarity tools and a testnet wallet setup.
+2. **Compilation**: Compile the contract using a Clarity-compatible development environment.
+3. **Deployment**: Deploy the contract to the Stacks testnet or mainnet with a wallet holding enough STX for deployment fees.
+4. **Post-deployment Configuration**: Configure price feeds and KYC information for users as needed.
+
+
+## Error Codes
+
+| Code                  | Meaning                           |
+|-----------------------|-----------------------------------|
+| `err-owner-only`      | Only the contract owner can execute this action |
+| `err-not-found`       | Asset or proposal not found      |
+| `err-already-listed`  | Asset is already registered      |
+| `err-invalid-amount`  | Invalid amount specified         |
+| `err-not-authorized`  | Action requires additional permissions |
+| `err-kyc-required`    | KYC verification required        |
+| `err-invalid-duration`| Duration exceeds limits          |
+| `err-invalid-votes`   | Minimum votes not met            |
+
+-- Author: Amobi Ndubuisi