Paritition and wrapping flow

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,14 @@
+---
+name: Feature request
+about: Suggest an idea
+labels: enhancement
+---
+
+**Motivation**
+Why this helps.
+
+**Proposed change**
+What to add or modify.
+
+**Notes**
+Any risks or rollout plan.

README.md

@@ -17,27 +17,81 @@ ERC-7518 introduces partitioned token management through the ERC-1155 multi-toke
 - **Interoperability**: Wrapping and unwrapping tokens, enabling cross‑chain or cross‑standard compatibility.  
 - **Built on ERC‑1155 + ERC‑165**: Ensures backward compatibility and easy integration with wallets and dApps.  
 
+## Partition Model at a Glance
+
+ERC-7518 represents **partitions as ERC-1155 `id` or `tokenId`s**.  
+Each `tokenId` corresponds to a **distinct partition** of a wrapped or regulated asset.  
+All compliance checks, locks, and transfer rules are evaluated *per partition*.
+
+| Concept | Description | Implemented In |
+|----------|--------------|----------------|
+| **Partition (`id`)** | Logical slice of an asset (e.g., restricted share class, lockup, compliance rule). | `erc1155mod.sol` |
+| **Partition Balances** | Tracked under ERC-1155 balances: `balanceOf(account, partitionId)` | `erc1155mod.sol` |
+| **Compliance Check** | Hook executed before every transfer to validate partition rule. | `erc7518.sol` (pre-transfer gate that calls `canTransfer`) |
+| **Lock / Restrict** | Temporarily freezes partition transfers. | `erc7518.sol` |
+| **Wrap / Unwrap** | Converts partitioned tokens ↔ fungible main balance. | `erc7518.sol` (`wrapToken`, `wrapTokenFromPartition`, `unwrapToken`) |
+| **Force Transfer** | Admin-triggered override respecting partition metadata. | `erc7518.sol` |
+
+`tokenId == partitionId`.  
+Partitions can be **minted, merged, or wrapped** dynamically without redeploying the contract.
+
 ## Project Structure
 
 ```
 erc‑7518‑foundry/
 ├── src/
-│   ├── ERC7518.sol              # Core implementation
-│   └── interfaces/
-│       └── IERC7518.sol         # Interface contract
+│   ├── erc7518.sol            # Entry contract, vault and wrapper
+│   ├── erc1155mod.sol         # ERC-1155 base ledger (partitions)
+│   └── STObasev2.sol          # Security Token Offering contract
 ├── test/
-│   └── ERC7518.t.sol            # Basic Foundry tests
+│   └── ERC7518.t.sol          # Foundry tests
 ├── script/
-│   └── Deploy.s.sol             # Simple deployment script
-├── lib/                         # Dependencies (e.g., OZ contracts)
+│   └── Deploy.s.sol           # Deployment script
+├── lib/                       # Dependencies (e.g., OZ contracts)
 ├── foundry.toml
 ├── README.md
 └── LICENSE
 ```
 
+## Contract Architecture and Flow
+
+*Note:* `STObasev2` stands for **Security Token Offering**. It is scoped to offering setup and settlement only, not a generic compliance or freeze module.
+
+The reference implementation has three main contracts that together realize the full ERC-7518 lifecycle.
+
+| Contract | Role | Description |
+|-----------|------|-------------|
+| **erc1155mod.sol** | Base Ledger | Implements the ERC-1155 multi-token standard with minor optimizations. Each `tokenId` represents a distinct partition and holds balances, mint, burn, and transfer logic. |
+| **STObasev2.sol** | Security Token Offering (STO) | Handles offering lifecycle and settlement. Manages sale inventory and pricing, settles purchases, and transfers purchased ERC‑1155 `tokenId` balances to investors. It does not implement global freezes or a generic transfer gate. |
+| **erc7518.sol** | Vault and Wrapper | Acts as the entry point for ERC-7518. It handles wrapping and unwrapping of external security tokens (ERC-20, ERC-721, or partitioned ERC-1400), integrates the compliance layer, and delegates balance management to `erc1155mod.sol`. |
+
+### High-Level System Flow
+
+![ERC-7518 System Flow](./assets/erc7518_system_flow.png)
+
+### Partition Lifecycle (from mint to redemption)
+
+1. **Mint**, issuer creates a partition by minting `tokenId` in `erc1155mod.sol`.
+2. **STO settlement** (optional), `STObasev2.sol` settles a purchase and transfers the purchased `tokenId` to the investor.
+3. **Transfer**, holder moves `tokenId` using `safeTransferFrom`, `erc7518.sol` calls the pre‑transfer gate (`canTransfer`) before updating balances.
+4. **Wrap from partition**, holder calls `wrapTokenFromPartition(partitionId, tokenId, amount, data)`, `erc7518.sol` performs the vault action and mints the wrapped representation.
+5. **Unwrap**, holder calls `unwrapToken(tokenId, amount, data)`, `erc7518.sol` burns wrapped balance and releases the original asset.
+6. **Payout / Merge / Burn**, issuer optionally distributes payouts, merges partitions, or burns when the lifecycle ends.
+
+### Code pointers
+
+| Action | Where |
+|---|---|
+| Mint partition | `src/erc1155mod.sol` |
+| Settle an STO purchase | `src/STObasev2.sol` |
+| Pre‑transfer gate | `src/erc7518.sol` (`canTransfer` call) |
+| Wrap from partition | `src/erc7518.sol` (`wrapTokenFromPartition`) |
+| Unwrap | `src/erc7518.sol` (`unwrapToken`) |
+
 ## Core Features
 
-### Partition Management
+### Partition Model and Management
+
 - Each `tokenId` represents a unique partition with independent compliance rules
 - Dynamic allocation of tokens between different classes or categories
 - Support for temporary non-fungibility during regulatory holding periods