From 5600e32f56f976e4dd0a018b682d225de83cd47b Mon Sep 17 00:00:00 2001 From: gid-ctl Date: Sat, 28 Dec 2024 16:52:33 +0100 Subject: [PATCH 1/8] feat: Initialize asset tokenization smart contract - Added constants for contract owner and error handling - Defined data variable for tracking the next asset ID - Included metadata for the contract's title, description, and features --- Clarinet.toml | 22 ++++++++++++---------- contracts/asset-stack.clar | 22 ++++++++++++++++++++++ tests/asset-stack_test.ts | 26 ++++++++++++++++++++++++++ 3 files changed, 60 insertions(+), 10 deletions(-) create mode 100644 contracts/asset-stack.clar create mode 100644 tests/asset-stack_test.ts diff --git a/Clarinet.toml b/Clarinet.toml index 2bca4de..9c4e8be 100644 --- a/Clarinet.toml +++ b/Clarinet.toml @@ -1,20 +1,22 @@ - [project] name = "AssetStack" authors = [] +description = "" telemetry = true +requirements = [] +[contracts.asset-stack] +path = "contracts/asset-stack.clar" +depends_on = [] + +[repl] +costs_version = 2 +parser_version = 2 + [repl.analysis] passes = ["check_checker"] + [repl.analysis.check_checker] -# If true, inputs are trusted after tx_sender has been checked. +strict = false trusted_sender = false -# If true, inputs are trusted after contract-caller has been checked. trusted_caller = false -# If true, untrusted data may be passed into a private function without a -# warning, if it gets checked inside. This check will also propagate up to the -# caller. callee_filter = false - -# [contracts.counter] -# path = "contracts/counter.clar" -# depends_on = [] diff --git a/contracts/asset-stack.clar b/contracts/asset-stack.clar new file mode 100644 index 0000000..7ced27b --- /dev/null +++ b/contracts/asset-stack.clar @@ -0,0 +1,22 @@ +;; Title: Asset Tokenization +;; Description: A smart contract that enables the creation and management of tokenized real-world assets +;; with fractional ownership capabilities, compliance checks, and secure transfer mechanisms. +;; +;; Features: +;; - Asset creation with metadata and configurable supply +;; - Fractional ownership representation +;; - Built-in compliance checks +;; - Secure ownership transfers +;; - Administrative controls for compliance management + +;; Constants +(define-constant CONTRACT-OWNER tx-sender) +(define-constant ERR-UNAUTHORIZED (err u1)) +(define-constant ERR-INSUFFICIENT-FUNDS (err u2)) +(define-constant ERR-INVALID-ASSET (err u3)) +(define-constant ERR-TRANSFER-FAILED (err u4)) +(define-constant ERR-COMPLIANCE-CHECK-FAILED (err u5)) +(define-constant ERR-INVALID-INPUT (err u6)) + +;; Data Variables +(define-data-var next-asset-id uint u1) \ No newline at end of file diff --git a/tests/asset-stack_test.ts b/tests/asset-stack_test.ts new file mode 100644 index 0000000..9a18ae0 --- /dev/null +++ b/tests/asset-stack_test.ts @@ -0,0 +1,26 @@ + +import { Clarinet, Tx, Chain, Account, types } from 'https://deno.land/x/clarinet@v0.14.0/index.ts'; +import { assertEquals } from 'https://deno.land/std@0.90.0/testing/asserts.ts'; + +Clarinet.test({ + name: "Ensure that <...>", + async fn(chain: Chain, accounts: Map) { + let block = chain.mineBlock([ + /* + * Add transactions with: + * Tx.contractCall(...) + */ + ]); + assertEquals(block.receipts.length, 0); + assertEquals(block.height, 2); + + block = chain.mineBlock([ + /* + * Add transactions with: + * Tx.contractCall(...) + */ + ]); + assertEquals(block.receipts.length, 0); + assertEquals(block.height, 3); + }, +}); From 8b90a4165c020725723d0dd2f34c2d93fff3180d Mon Sep 17 00:00:00 2001 From: gid-ctl Date: Sat, 28 Dec 2024 16:53:44 +0100 Subject: [PATCH 2/8] feat: Add data maps and NFT definition for asset management - Defined `asset-registry` map to store asset details - Defined `compliance-status` map to track user compliance - Added non-fungible token definition for asset ownership --- contracts/asset-stack.clar | 22 +++++++++++++++++++++- 1 file changed, 21 insertions(+), 1 deletion(-) diff --git a/contracts/asset-stack.clar b/contracts/asset-stack.clar index 7ced27b..9fa6873 100644 --- a/contracts/asset-stack.clar +++ b/contracts/asset-stack.clar @@ -19,4 +19,24 @@ (define-constant ERR-INVALID-INPUT (err u6)) ;; Data Variables -(define-data-var next-asset-id uint u1) \ No newline at end of file +(define-data-var next-asset-id uint u1) + +;; Data Maps +(define-map asset-registry + {asset-id: uint} + { + owner: principal, + total-supply: uint, + fractional-shares: uint, + metadata-uri: (string-utf8 256), + is-transferable: bool + } +) + +(define-map compliance-status + {asset-id: uint, user: principal} + {is-approved: bool} +) + +;; NFT Definition +(define-non-fungible-token asset-ownership-token uint) From 507a963c35115504d380fdd82ba085bfc00b355a Mon Sep 17 00:00:00 2001 From: gid-ctl Date: Sat, 28 Dec 2024 16:54:19 +0100 Subject: [PATCH 3/8] feat: Add private validation functions - Added `is-valid-metadata-uri` to validate metadata URI length - Added `is-valid-asset-id` to ensure asset ID is greater than zero - Added `is-valid-principal` to check if user is not the contract owner - Added `is-compliance-check-passed` to verify compliance status for a user and asset --- contracts/asset-stack.clar | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/contracts/asset-stack.clar b/contracts/asset-stack.clar index 9fa6873..ebcb5c7 100644 --- a/contracts/asset-stack.clar +++ b/contracts/asset-stack.clar @@ -40,3 +40,30 @@ ;; NFT Definition (define-non-fungible-token asset-ownership-token uint) + +;; Private Functions - Validation +(define-private (is-valid-metadata-uri (uri (string-utf8 256))) + (and + (> (len uri) u0) + (<= (len uri) u256) + ) +) + +(define-private (is-valid-asset-id (asset-id uint)) + (> asset-id u0) +) + +(define-private (is-valid-principal (user principal)) + (not (is-eq user CONTRACT-OWNER)) +) + +(define-private (is-compliance-check-passed + (asset-id uint) + (user principal) +) + (default-to false + (get is-approved + (map-get? compliance-status {asset-id: asset-id, user: user}) + ) + ) +) \ No newline at end of file From 2bf554b9d05084a03fd35be0b171062aaf9dd476 Mon Sep 17 00:00:00 2001 From: gid-ctl Date: Sat, 28 Dec 2024 16:54:57 +0100 Subject: [PATCH 4/8] feat: Add public function for asset creation - Implemented `create-asset` function to create a new asset with specified total supply, fractional shares, and metadata URI - Added validation checks for input parameters - Updated asset registry and minted a new NFT for the asset - Incremented the next asset ID after creation --- contracts/asset-stack.clar | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) diff --git a/contracts/asset-stack.clar b/contracts/asset-stack.clar index ebcb5c7..b3a2e28 100644 --- a/contracts/asset-stack.clar +++ b/contracts/asset-stack.clar @@ -66,4 +66,34 @@ (map-get? compliance-status {asset-id: asset-id, user: user}) ) ) +) + +;; Public Functions - Asset Management +(define-public (create-asset + (total-supply uint) + (fractional-shares uint) + (metadata-uri (string-utf8 256)) +) + (begin + (asserts! (> total-supply u0) ERR-INVALID-INPUT) + (asserts! (> fractional-shares u0) ERR-INVALID-INPUT) + (asserts! (is-valid-metadata-uri metadata-uri) ERR-INVALID-INPUT) + + (let ((asset-id (var-get next-asset-id))) + (map-set asset-registry + {asset-id: asset-id} + { + owner: tx-sender, + total-supply: total-supply, + fractional-shares: fractional-shares, + metadata-uri: metadata-uri, + is-transferable: true + } + ) + + (try! (nft-mint? asset-ownership-token asset-id tx-sender)) + (var-set next-asset-id (+ asset-id u1)) + (ok asset-id) + ) + ) ) \ No newline at end of file From 0ef6dbafbc5f84aa7f90a3f731eb45ee151b3e6f Mon Sep 17 00:00:00 2001 From: gid-ctl Date: Sat, 28 Dec 2024 16:55:35 +0100 Subject: [PATCH 5/8] feat: Add public function for transferring fractional ownership - Implemented `transfer-fractional-ownership` function to transfer ownership of asset fractions - Added validation checks for asset ID, recipient principal, transferability, and compliance status - Performed NFT transfer for the specified asset ID --- contracts/asset-stack.clar | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/contracts/asset-stack.clar b/contracts/asset-stack.clar index b3a2e28..bfeb602 100644 --- a/contracts/asset-stack.clar +++ b/contracts/asset-stack.clar @@ -96,4 +96,23 @@ (ok asset-id) ) ) +) + +(define-public (transfer-fractional-ownership + (asset-id uint) + (to-principal principal) + (amount uint) +) + (let ( + (asset (unwrap! (map-get? asset-registry {asset-id: asset-id}) ERR-INVALID-ASSET)) + (sender tx-sender) + ) + (asserts! (is-valid-asset-id asset-id) ERR-INVALID-INPUT) + (asserts! (is-valid-principal to-principal) ERR-INVALID-INPUT) + (asserts! (get is-transferable asset) ERR-UNAUTHORIZED) + (asserts! (is-compliance-check-passed asset-id to-principal) ERR-COMPLIANCE-CHECK-FAILED) + + (try! (nft-transfer? asset-ownership-token asset-id sender to-principal)) + (ok true) + ) ) \ No newline at end of file From 2e3dbb2076c4da95d9483a1a5c2799d4056b7e3d Mon Sep 17 00:00:00 2001 From: gid-ctl Date: Sat, 28 Dec 2024 16:56:10 +0100 Subject: [PATCH 6/8] feat: Add compliance management and read-only functions - Implemented `set-compliance-status` function to update compliance status for a user and asset - Added validation checks for asset ID, user principal, and contract owner authorization - Implemented `get-asset-details` read-only function to retrieve asset details from the registry --- contracts/asset-stack.clar | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/contracts/asset-stack.clar b/contracts/asset-stack.clar index bfeb602..3974f78 100644 --- a/contracts/asset-stack.clar +++ b/contracts/asset-stack.clar @@ -115,4 +115,29 @@ (try! (nft-transfer? asset-ownership-token asset-id sender to-principal)) (ok true) ) +) + +;; Public Functions - Compliance Management +(define-public (set-compliance-status + (asset-id uint) + (user principal) + (is-approved bool) +) + (begin + (asserts! (is-valid-asset-id asset-id) ERR-INVALID-INPUT) + (asserts! (is-valid-principal user) ERR-INVALID-INPUT) + (asserts! (is-eq tx-sender CONTRACT-OWNER) ERR-UNAUTHORIZED) + + (map-set compliance-status + {asset-id: asset-id, user: user} + {is-approved: is-approved} + ) + + (ok is-approved) + ) +) + +;; Read-only Functions +(define-read-only (get-asset-details (asset-id uint)) + (map-get? asset-registry {asset-id: asset-id}) ) \ No newline at end of file From 9b7780c7a087332bdd99d8322bcf42f761f8e076 Mon Sep 17 00:00:00 2001 From: gid-ctl Date: Sat, 28 Dec 2024 17:14:59 +0100 Subject: [PATCH 7/8] feat: Enhance asset tokenization protocol with event logging and share management --- contracts/asset-stack.clar | 134 +++++++++++++++++++++++++++++++++---- 1 file changed, 121 insertions(+), 13 deletions(-) diff --git a/contracts/asset-stack.clar b/contracts/asset-stack.clar index 3974f78..60c3402 100644 --- a/contracts/asset-stack.clar +++ b/contracts/asset-stack.clar @@ -1,4 +1,5 @@ -;; Title: Asset Tokenization +;; Title: Asset Tokenization Protocol +;; Version: 1.0.0 ;; Description: A smart contract that enables the creation and management of tokenized real-world assets ;; with fractional ownership capabilities, compliance checks, and secure transfer mechanisms. ;; @@ -11,12 +12,15 @@ ;; Constants (define-constant CONTRACT-OWNER tx-sender) +(define-constant CONTRACT-ADMIN CONTRACT-OWNER) (define-constant ERR-UNAUTHORIZED (err u1)) (define-constant ERR-INSUFFICIENT-FUNDS (err u2)) (define-constant ERR-INVALID-ASSET (err u3)) (define-constant ERR-TRANSFER-FAILED (err u4)) (define-constant ERR-COMPLIANCE-CHECK-FAILED (err u5)) (define-constant ERR-INVALID-INPUT (err u6)) +(define-constant ERR-INSUFFICIENT-SHARES (err u7)) +(define-constant ERR-EVENT-LOGGING (err u8)) ;; Data Variables (define-data-var next-asset-id uint u1) @@ -29,45 +33,113 @@ total-supply: uint, fractional-shares: uint, metadata-uri: (string-utf8 256), - is-transferable: bool + is-transferable: bool, + created-at: uint } ) (define-map compliance-status {asset-id: uint, user: principal} - {is-approved: bool} + { + is-approved: bool, + last-updated: uint, + approved-by: principal + } +) + +(define-map share-ownership + {asset-id: uint, owner: principal} + {shares: uint} ) ;; NFT Definition (define-non-fungible-token asset-ownership-token uint) +;; Events +(define-data-var last-event-id uint u0) + +(define-map events + {event-id: uint} + { + event-type: (string-utf8 24), + asset-id: uint, + principal1: principal, + timestamp: uint + } +) + +;; Private Functions - Event Logging +(define-private (log-event + (event-type (string-utf8 24)) + (asset-id uint) + (principal1 principal) +) + (begin + (let ((event-id (+ (var-get last-event-id) u1))) + (map-set events + {event-id: event-id} + { + event-type: event-type, + asset-id: asset-id, + principal1: principal1, + timestamp: block-height + } + ) + (var-set last-event-id event-id) + (ok event-id) + ) + ) +) + ;; Private Functions - Validation (define-private (is-valid-metadata-uri (uri (string-utf8 256))) (and (> (len uri) u0) (<= (len uri) u256) + (> (len uri) u5) ) ) (define-private (is-valid-asset-id (asset-id uint)) - (> asset-id u0) + (and + (> asset-id u0) + (< asset-id (var-get next-asset-id)) + ) ) (define-private (is-valid-principal (user principal)) - (not (is-eq user CONTRACT-OWNER)) + (and + (not (is-eq user CONTRACT-OWNER)) + (not (is-eq user (as-contract tx-sender))) + ) ) (define-private (is-compliance-check-passed (asset-id uint) (user principal) ) - (default-to false - (get is-approved - (map-get? compliance-status {asset-id: asset-id, user: user}) + (match (map-get? compliance-status {asset-id: asset-id, user: user}) + compliance-data (get is-approved compliance-data) + false + ) +) + +;; Private Functions - Share Management +(define-private (get-shares (asset-id uint) (owner principal)) + (default-to u0 + (get shares + (map-get? share-ownership {asset-id: asset-id, owner: owner}) ) ) ) +(define-private (set-shares (asset-id uint) (owner principal) (amount uint)) + (map-set share-ownership + {asset-id: asset-id, owner: owner} + {shares: amount} + ) +) + ;; Public Functions - Asset Management (define-public (create-asset (total-supply uint) @@ -77,6 +149,7 @@ (begin (asserts! (> total-supply u0) ERR-INVALID-INPUT) (asserts! (> fractional-shares u0) ERR-INVALID-INPUT) + (asserts! (<= fractional-shares total-supply) ERR-INVALID-INPUT) (asserts! (is-valid-metadata-uri metadata-uri) ERR-INVALID-INPUT) (let ((asset-id (var-get next-asset-id))) @@ -87,11 +160,17 @@ total-supply: total-supply, fractional-shares: fractional-shares, metadata-uri: metadata-uri, - is-transferable: true + is-transferable: true, + created-at: block-height } ) - (try! (nft-mint? asset-ownership-token asset-id tx-sender)) + ;; Initialize share ownership + (set-shares asset-id tx-sender total-supply) + + (unwrap! (nft-mint? asset-ownership-token asset-id tx-sender) ERR-TRANSFER-FAILED) + (unwrap! (log-event u"ASSET_CREATED" asset-id tx-sender) ERR-EVENT-LOGGING) + (var-set next-asset-id (+ asset-id u1)) (ok asset-id) ) @@ -106,18 +185,29 @@ (let ( (asset (unwrap! (map-get? asset-registry {asset-id: asset-id}) ERR-INVALID-ASSET)) (sender tx-sender) + (sender-shares (get-shares asset-id sender)) ) (asserts! (is-valid-asset-id asset-id) ERR-INVALID-INPUT) (asserts! (is-valid-principal to-principal) ERR-INVALID-INPUT) (asserts! (get is-transferable asset) ERR-UNAUTHORIZED) (asserts! (is-compliance-check-passed asset-id to-principal) ERR-COMPLIANCE-CHECK-FAILED) + (asserts! (>= sender-shares amount) ERR-INSUFFICIENT-SHARES) + + ;; Update share balances + (set-shares asset-id sender (- sender-shares amount)) + (set-shares asset-id to-principal (+ (get-shares asset-id to-principal) amount)) + + (unwrap! (log-event u"TRANSFER" asset-id sender) ERR-EVENT-LOGGING) + + (if (is-eq sender-shares amount) + (unwrap! (nft-transfer? asset-ownership-token asset-id sender to-principal) ERR-TRANSFER-FAILED) + true + ) - (try! (nft-transfer? asset-ownership-token asset-id sender to-principal)) (ok true) ) ) -;; Public Functions - Compliance Management (define-public (set-compliance-status (asset-id uint) (user principal) @@ -130,9 +220,15 @@ (map-set compliance-status {asset-id: asset-id, user: user} - {is-approved: is-approved} + { + is-approved: is-approved, + last-updated: block-height, + approved-by: tx-sender + } ) + (unwrap! (log-event u"COMPLIANCE_UPDATE" asset-id user) ERR-EVENT-LOGGING) + (ok is-approved) ) ) @@ -140,4 +236,16 @@ ;; Read-only Functions (define-read-only (get-asset-details (asset-id uint)) (map-get? asset-registry {asset-id: asset-id}) +) + +(define-read-only (get-owner-shares (asset-id uint) (owner principal)) + (ok (get-shares asset-id owner)) +) + +(define-read-only (get-compliance-details (asset-id uint) (user principal)) + (map-get? compliance-status {asset-id: asset-id, user: user}) +) + +(define-read-only (get-event (event-id uint)) + (map-get? events {event-id: event-id}) ) \ No newline at end of file From 8d19869719f15b9474b3a92c6b1161c83d1e6888 Mon Sep 17 00:00:00 2001 From: gid-ctl Date: Sat, 28 Dec 2024 20:24:15 +0100 Subject: [PATCH 8/8] feat: Add initial project files including LICENSE, CONTRIBUTING, CODE_OF_CONDUCT, and README --- CODE_OF_CONDUCT.md | 52 ++++++++ CONTRIBUTING.md | 63 ++++++++++ LICENSE | 21 ++++ README.md | 111 +++++++++++++++++ docs/technical-specification.md | 211 ++++++++++++++++++++++++++++++++ 5 files changed, 458 insertions(+) create mode 100644 CODE_OF_CONDUCT.md create mode 100644 CONTRIBUTING.md create mode 100644 LICENSE create mode 100644 README.md create mode 100644 docs/technical-specification.md diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..64a1c95 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,52 @@ +# Contributor Covenant Code of Conduct + +## Our Pledge + +We as members, contributors, and leaders pledge to make participation in our +community a harassment-free experience for everyone, regardless of age, body +size, visible or invisible disability, ethnicity, sex characteristics, gender +identity and expression, level of experience, education, socio-economic status, +nationality, personal appearance, race, religion, or sexual identity +and orientation. + +## Our Standards + +Examples of behavior that contributes to a positive environment: + +- Using welcoming and inclusive language +- Being respectful of differing viewpoints and experiences +- Gracefully accepting constructive criticism +- Focusing on what is best for the community +- Showing empathy towards other community members + +Examples of unacceptable behavior: + +- The use of sexualized language or imagery +- Trolling, insulting/derogatory comments, and personal or political attacks +- Public or private harassment +- Publishing others' private information without explicit permission +- Other conduct which could reasonably be considered inappropriate + +## Enforcement Responsibilities + +Project maintainers are responsible for clarifying and enforcing standards of +acceptable behavior and will take appropriate and fair corrective action in +response to any behavior that they deem inappropriate, threatening, offensive, +or harmful. + +## Scope + +This Code of Conduct applies within all community spaces, and also applies when +an individual is officially representing the community in public spaces. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported to the project maintainers. All complaints will be reviewed and +investigated promptly and fairly. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org), +version 2.0, available at +https://www.contributor-covenant.org/version/2/0/code_of_conduct.html. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..55bfafd --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,63 @@ +# Contributing to Asset Tokenization Protocol + +We love your input! We want to make contributing to the Asset Tokenization Protocol as easy and transparent as possible, whether it's: + +- Reporting a bug +- Discussing the current state of the code +- Submitting a fix +- Proposing new features +- Becoming a maintainer + +## We Develop with Github + +We use GitHub to host code, to track issues and feature requests, as well as accept pull requests. + +## Pull Requests Process + +1. Fork the repo and create your branch +2. If you've added code that should be tested, add tests +3. If you've changed APIs, update the documentation +4. Ensure the test suite passes +5. Make sure your code lints +6. Issue that pull request! + +## Any contributions you make will be under the MIT Software License + +When you submit code changes, your submissions are understood to be under the same [MIT License](LICENSE) that covers the project. Feel free to contact the maintainers if that's a concern. + +## Report bugs using Github's [issue tracker] + +We use GitHub issues to track public bugs. Report a bug by [opening a new issue](). + +## Write bug reports with detail, background, and sample code + +**Great Bug Reports** tend to have: + +- A quick summary and/or background +- Steps to reproduce + - Be specific! + - Give sample code if you can +- What you expected would happen +- What actually happens +- Notes (possibly including why you think this might be happening, or stuff you tried that didn't work) + +## Development Process + +1. Clone the repository +2. Create a new branch for your feature/fix +3. Write tests for your changes +4. Implement your changes +5. Run the test suite +6. Submit a Pull Request + +## Testing + +We use Clarinet for testing. To run tests: + +```bash +clarinet test +``` + +## License + +By contributing, you agree that your contributions will be licensed under its MIT License. diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..d82f56c --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2024 Gideon + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/README.md b/README.md new file mode 100644 index 0000000..6e5ae7d --- /dev/null +++ b/README.md @@ -0,0 +1,111 @@ +# Asset Tokenization Protocol + +A robust smart contract implementation for tokenizing real-world assets with fractional ownership capabilities, built on the Stacks blockchain. + +## Overview + +The Asset Tokenization Protocol enables the creation and management of tokenized real-world assets with features including: + +- Asset creation with configurable supply and metadata +- Fractional ownership management +- Built-in compliance checks +- Secure ownership transfers +- Administrative controls +- Comprehensive event logging + +## Features + +- **Asset Creation**: Create new tokenized assets with customizable total supply and fractional shares +- **Fractional Ownership**: Enable partial ownership of assets through divisible shares +- **Compliance Management**: Built-in compliance checks and status management +- **Secure Transfers**: Protected ownership transfer mechanisms with validation +- **Event Tracking**: Comprehensive event logging for all major operations +- **Administrative Controls**: Secure admin functions for compliance management + +## Getting Started + +### Prerequisites + +- [Clarinet](https://github.com/hirosystems/clarinet) for local development +- [Stacks Wallet](https://www.hiro.so/wallet) for contract interaction +- Basic understanding of Clarity smart contracts + +### Installation + +1. Clone the repository: + +```bash +git clone https://github.com/gid-ctl/AssetStack.git +``` + +2. Install dependencies: + +```bash +clarinet requirements +``` + +3. Run tests: + +```bash +clarinet test +``` + +### Usage + +#### Creating a New Asset + +```clarity +(contract-call? .asset-tokenization-protocol create-asset + u1000000 ;; total supply + u1000 ;; fractional shares + "https://metadata.example.com/asset/1" ;; metadata URI +) +``` + +#### Transferring Shares + +```clarity +(contract-call? .asset-tokenization-protocol transfer-fractional-ownership + u1 ;; asset-id + tx-sender ;; to-principal + u100 ;; amount +) +``` + +#### Checking Compliance Status + +```clarity +(contract-call? .asset-tokenization-protocol get-compliance-details + u1 ;; asset-id + tx-sender ;; user +) +``` + +## Architecture + +The protocol is built on several key components: + +1. **Asset Registry**: Stores core asset information and configuration +2. **Share Management**: Handles fractional ownership accounting +3. **Compliance System**: Manages user compliance status +4. **Event System**: Tracks all significant protocol actions +5. **NFT Layer**: Represents primary asset ownership + +## Security + +- Built-in authorization checks +- Comprehensive input validation +- Protected admin functions +- Event logging for audit trails + +## Contributing + +Please read [CONTRIBUTING.md](CONTRIBUTING.md) for details on our code of conduct and the process for submitting pull requests. + +## License + +This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. + +## Support + +For support, please open an issue in the GitHub repository or contact the maintainers. diff --git a/docs/technical-specification.md b/docs/technical-specification.md new file mode 100644 index 0000000..7a38bfd --- /dev/null +++ b/docs/technical-specification.md @@ -0,0 +1,211 @@ +# Technical Specification: Asset Tokenization Protocol + +## Overview + +The Asset Tokenization Protocol is a smart contract system designed to enable the tokenization of real-world assets with fractional ownership capabilities. This document outlines the technical architecture, components, and implementation details of the protocol. + +## System Architecture + +### Core Components + +1. **Asset Registry** + + - Stores asset metadata and configuration + - Tracks ownership and supply information + - Manages transferability status + +2. **Share Management System** + + - Handles fractional ownership accounting + - Manages share transfers between parties + - Tracks individual share balances + +3. **Compliance System** + + - Manages user compliance status + - Handles compliance checks for transfers + - Stores compliance history + +4. **Event System** + - Logs all significant protocol actions + - Maintains audit trail + - Enables external system integration + +### Data Structures + +#### Asset Registry + +```clarity +(define-map asset-registry + {asset-id: uint} + { + owner: principal, + total-supply: uint, + fractional-shares: uint, + metadata-uri: (string-utf8 256), + is-transferable: bool, + created-at: uint + } +) +``` + +#### Share Ownership + +```clarity +(define-map share-ownership + {asset-id: uint, owner: principal} + {shares: uint} +) +``` + +#### Compliance Status + +```clarity +(define-map compliance-status + {asset-id: uint, user: principal} + { + is-approved: bool, + last-updated: uint, + approved-by: principal + } +) +``` + +## Core Functions + +### Asset Creation + +- Function: `create-asset` +- Parameters: + - `total-supply`: Total number of shares + - `fractional-shares`: Minimum divisible unit + - `metadata-uri`: URI pointing to asset metadata +- Validation: + - Supply must be greater than 0 + - Fractional shares must be less than or equal to total supply + - Valid metadata URI format + +### Share Transfer + +- Function: `transfer-fractional-ownership` +- Parameters: + - `asset-id`: Unique identifier of the asset + - `to-principal`: Recipient address + - `amount`: Number of shares to transfer +- Validation: + - Valid asset ID + - Sufficient balance + - Compliance checks + - Transferability status + +### Compliance Management + +- Function: `set-compliance-status` +- Parameters: + - `asset-id`: Asset identifier + - `user`: User address + - `is-approved`: Compliance status +- Access Control: + - Only contract owner + - Valid asset and user validation + +## Security Considerations + +### Access Control + +- Contract owner privileges +- Transfer restrictions +- Compliance requirements + +### Input Validation + +- Range checks +- Format validation +- Address validation + +### Asset Protection + +- Ownership verification +- Balance checks +- Transfer locks + +## Error Handling + +### Error Codes + +- `ERR-UNAUTHORIZED`: Access control violation +- `ERR-INSUFFICIENT-FUNDS`: Insufficient balance +- `ERR-INVALID-ASSET`: Invalid asset reference +- `ERR-TRANSFER-FAILED`: Transfer operation failed +- `ERR-COMPLIANCE-CHECK-FAILED`: Failed compliance check +- `ERR-INVALID-INPUT`: Invalid input parameters +- `ERR-INSUFFICIENT-SHARES`: Insufficient share balance +- `ERR-EVENT-LOGGING`: Event logging failure + +## Event System + +### Event Types + +- Asset Creation +- Share Transfer +- Compliance Update +- Administrative Actions + +### Event Structure + +```clarity +{ + event-type: (string-utf8 24), + asset-id: uint, + principal1: principal, + timestamp: uint +} +``` + +## Performance Considerations + +### Storage Optimization + +- Minimal data storage +- Efficient data structures +- Optimized mapping access + +### Gas Efficiency + +- Minimized state changes +- Optimized loops and iterations +- Efficient validation checks + +## Integration Guidelines + +### External Systems + +- Event monitoring +- Compliance integration +- Metadata management + +### Client Integration + +- API endpoints +- Event handling +- Error management + +## Testing Strategy + +### Unit Tests + +- Function-level testing +- Input validation +- Error handling + +### Integration Tests + +- End-to-end workflows +- Multi-step operations +- Edge cases + +### Security Tests + +- Access control +- Input validation +- Error handling