docs: add tokenization section

.gitbook/defi/tokenization/iassets.mdx

@@ -0,0 +1,113 @@
+---
+title: iAssets
+description: >-
+  Synthetic real-world asset derivatives on Injective: how iAssets work, what markets are
+  available, how prices are sourced, and how to trade them.
+updatedAt: "2026-07-09"
+---
+
+iAssets are synthetic perpetual futures contracts that give traders price exposure to real-world
+assets, including equities, commodities, and FX pairs, without requiring custody of the underlying.
+Unlike permissioned native tokens, iAssets carry no direct on-chain representation of the underlying
+instrument. Collateral is posted in USDT or other supported stablecoins, positions are cash-settled,
+and price exposure is delivered through Injective's decentralized oracle infrastructure.
+
+iAssets trade through Injective's native derivatives engine under exactly the same mechanics as
+crypto perpetual futures: margin-based positions, funding rates, an orderbook (or RFQ for
+supported front-ends), and 24/7 continuous trading even when the underlying market is closed.
+
+---
+
+## How iAssets Work
+
+### Price Feed
+
+Each iAsset market is anchored to a decentralized oracle price feed sourced via Pyth. This price determines:
+- The mark price used for margin and liquidation calculations
+- Funding rate direction and magnitude
+- Settlement value when a position is closed
+
+Price feed hours vary by asset class:
+
+| Asset Class | Price Feed Hours | Trading Hours |
+|-------------|-----------------|---------------|
+| iAssets (Equities, supported) | 24/5 via SEDA aggregation (pre-market through overnight) | 24/7 |
+| iAssets (Equities, other) | Regular market hours only | 24/7 |
+| iAssets (FX / Commodities) | Sunday 6PM ET to Friday 5PM ET | 24/7 |
+
+iAssets continue trading 24/7 on Injective even when the mark price is not updating. Outside of active feed hours, the mark price is held constant, which means PnL does not shift and liquidation is virtually impossible until the next price update cycle resumes.
+
+### Settlement
+
+iAssets are cash-settled perpetuals with no physical delivery of shares, commodities, or
+currency. When you close a position, the PnL is settled in USDT based on the mark price at the
+time of close.
+
+### Funding Rate
+
+Like all perpetual futures on Injective, iAssets accrue a funding rate to keep the perpetual price
+anchored to the oracle price. When the perpetual trades at a premium to the oracle price, long
+positions pay short positions, and vice versa.
+
+---
+
+## Available Markets
+
+iAsset markets cover three primary categories:
+
+| Category | Examples |
+|----------|---------|
+| **Equities** | Major US and international equity exposures |
+| **Commodities** | Gold, silver, crude oil, and other commodities |
+| **FX** | Major currency pairs |
+
+The full current list of active iAsset markets is available on the Injective exchange.
+
+---
+
+## Trading iAssets
+
+### Differences from Crypto Perpetuals
+
+iAssets trade identically to crypto perpetuals on Injective, with one key distinction: the
+underlying price source. For crypto markets, the oracle is typically sourced from spot DEX prices.
+For iAssets, the oracle relies on off-chain financial data providers. This means:
+
+- **No spot arbitrage**: There is no on-chain spot market for the underlying to hedge against.
+  Arbitrage is purely between the iAsset perpetual price and the oracle price, not the physical asset.
+- **Oracle dependency**: Outside of active feed hours, the mark price is held constant by design. If an unplanned outage occurs during market hours, positions remain open but no new funding accrues until the feed resumes.
+- **Extended hours**: iAssets trade 24/7 but price exposure is limited to active feed windows (see the price feed table above). Outside those windows, PnL does not shift.
+
+### Margin and Leverage
+
+Margin is posted in USDT or other supported stablecoins. Leverage varies by market (typically 25x for equities, 50x for commodities, 100x for FX).
+See [Margin trading](/trading/margin-trading) for how cross- and isolated-margin work.
+
+### Fees
+
+iAssets are subject to the same maker/taker fee schedule as other Injective derivative markets.
+See [Fees](/trading/fees).
+
+---
+
+## iAssets vs. Permissioned Native Assets
+
+| | iAssets | Permissioned Native Assets |
+|---|---|---|
+| **What it represents** | Synthetic price exposure | On-chain token representation of an RWA |
+| **Custody of underlying** | None | Depends on issuer structure |
+| **Collateral** | USDT margin | Asset-specific |
+| **Settlement** | Cash (USDT) | Token-denominated |
+| **Transfer restrictions** | None | Enforced by Permissions module |
+| **Compliance controls** | None | Whitelist, blacklist, freeze, custom Wasm hook |
+| **Best for** | Traders seeking price exposure | Issuers requiring regulated, tokenized instruments |
+
+---
+
+## Further Reading
+
+- [Permissioned Assets](/defi/tokenization/permissioned-assets): for tokenizing RWAs with compliance controls
+- [Perpetual Markets](/trading/perpetual-markets): how perpetual futures work on Injective
+- [Funding Rates](/trading/funding-rates)
+- [Margin Trading](/trading/margin-trading)
+- [Oracle Feed Sources](/trading/oracle-feed-sources)

.gitbook/defi/tokenization/index.mdx

@@ -0,0 +1,61 @@
+---
+title: Tokenization
+description: >-
+  Overview of real-world asset tokenization on Injective, covering permissioned
+  native asset issuance and synthetic RWA derivatives.
+updatedAt: "2026-07-09"
+---
+
+Injective provides native infrastructure for bringing real-world assets (RWAs) onchain,
+from tokenized treasuries and fixed income instruments to equities, commodities, and pre-IPO credit.
+Rather than relying on wrapped representations or off-chain bridges, Injective supports two complementary
+approaches to RWA tokenization, each suited to different use cases and compliance requirements.
+
+Whether you are an issuer looking to launch a compliant, permissioned asset with transfer restrictions
+and KYC enforcement, or a builder wanting to give traders synthetic exposure to real-world markets
+without custody of the underlying, Injective provides the on-chain primitives to do it.
+
+## Approaches to Tokenization on Injective
+
+### Permissioned Native Assets
+
+Issuers can create fully on-chain token representations of real-world assets using Injective's
+`TokenFactory` and `Permissions` modules in combination. This approach is suitable for regulated
+assets that require compliance controls at the protocol level, for example tokenized treasuries,
+money market funds, or private credit instruments that must restrict transfers to KYC-verified
+addresses.
+
+Key capabilities:
+- **Whitelist/blacklist enforcement**: restrict minting, sending, and receiving to approved addresses only
+- **Freeze and pause**: disable all transfers across the asset at any time
+- **Role-based access control**: assign granular permissions (mint, burn, send, receive) to different roles
+- **Wasm contract hooks**: extend compliance logic with custom smart contracts that trigger on every receive event
+- **Governance compatibility**: namespace settings can be overridden by on-chain governance if configured
+
+This approach gives issuers full control over the asset lifecycle and is designed to support the
+compliance requirements of institutional tokenization.
+
+### iAssets (Synthetic RWA Derivatives)
+
+iAssets are synthetic derivatives that track real-world asset prices, including equities, commodities,
+and FX pairs, using Injective's native perpetual futures engine and decentralized oracle infrastructure.
+Unlike permissioned native assets, iAssets do not require custody of the underlying asset. Margin
+is posted in USDT or other supported stablecoins and positions are cash-settled, giving traders
+direct price exposure without the legal or operational overhead of holding the real asset.
+
+iAssets trade 24/7 on Injective. Outside of active oracle feed hours, the mark price is held constant and PnL does not shift until the feed resumes.
+
+## Key Concepts
+
+| Term | Definition |
+|------|------------|
+| **TokenFactory** | A permissionless module that allows any account to create a new native token denom. The creator becomes the admin, with the ability to mint and burn the asset. |
+| **Permissions Module** | An RBAC (Role-Based Access Control) layer built on top of TokenFactory denoms. Enables compliant, permissioned asset issuance with transfer restrictions, whitelisting, and freeze capabilities. |
+| **Namespace** | The container within the Permissions module that holds all roles, permissions, and policy settings for a single asset. Each asset denom can have one namespace. |
+| **iAssets** | Synthetic perpetual futures contracts that track the price of real-world assets (equities, commodities, FX) using decentralized oracles. No custody of the underlying asset is required. |
+| **Wasm Contract Hook** | An optional smart contract invoked on every receive event for a permissioned asset. Used to implement custom compliance logic beyond what the Permissions module provides natively. |
+
+## Navigation
+
+- **[Permissioned Assets](/defi/tokenization/permissioned-assets)**: How to issue compliant, permissioned RWA tokens on Injective using the TokenFactory and Permissions modules. Covers roles, namespaces, transfer restrictions, KYC enforcement, and how to launch a permissioned asset.
+- **[iAssets](/defi/tokenization/iassets)**: Synthetic RWA derivatives that provide price exposure to equities, commodities, and FX markets without custody of the underlying asset. Built on Injective's perpetual futures engine with 24/7 trading and decentralized oracle price feeds.

.gitbook/defi/tokenization/permissioned-assets.mdx

@@ -0,0 +1,221 @@
+---
+title: Permissioned Assets
+description: >-
+  How to issue compliant, permissioned real-world asset tokens on Injective using
+  the TokenFactory and Permissions modules, including roles, namespaces, transfer
+  restrictions, and KYC enforcement.
+updatedAt: "2026-07-09"
+---
+
+Injective's `TokenFactory` and `Permissions` modules together provide the primitives for issuing
+compliant real-world asset tokens natively on-chain. This is suited for regulated assets such as
+tokenized treasuries, money market funds, private credit instruments, and stablecoins that require
+protocol-level enforcement of transfer restrictions, investor whitelisting, and administrative controls.
+
+The two modules work in layers:
+
+1. **TokenFactory** creates the token denom and assigns an admin
+2. **Permissions** adds a namespace on top of that denom, enabling RBAC-based compliance controls
+
+Both must be in place for a fully permissioned asset. The TokenFactory denom must be created first.
+
+---
+
+## How It Works
+
+### Step 1: Create a TokenFactory Denom
+
+Any account can create a new token denom using `TokenFactory`. The denom takes the format
+`factory/{creator_address}/{subdenom}`. The creator becomes the admin of the denom and retains
+the ability to mint and burn the asset.
+
+```bash
+injectived tx tokenfactory create-denom <subdenom> [flags]
+```
+
+> **Important:** Do not transfer the TokenFactory admin to the null address
+> (`inj1qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqe2hm49`). The Permissions module requires the namespace
+> creator to be the admin of the corresponding TokenFactory denom.
+
+### Step 2: Create a Permissions Namespace
+
+Once the denom exists, create a namespace to add compliance controls. The namespace defines:
+- **Roles**: named permission sets (e.g. `admin`, `user`, `EVERYONE`)
+- **Actions**: what each role is allowed to do (mint, burn, send, receive, and namespace management actions)
+- **Role Managers**: addresses that can assign roles to other addresses
+- **Policy Statuses**: whether each action is enabled, disabled, or permanently sealed
+- **Policy Managers**: addresses that can enable/disable actions
+- **Wasm Contract Hook**: optional smart contract invoked on every receive event
+
+```bash
+injectived tx permissions create-namespace <namespace.json> [flags]
+```
+
+---
+
+## Roles and Actions
+
+### Actions
+
+Actions are the atomic operations that can be permitted or restricted per role:
+
+| Action | Description |
+|--------|-------------|
+| `MINT` | Mint tokens to any address with `RECEIVE` permissions |
+| `RECEIVE` | Receive tokens. Addresses without this permission cannot hold the asset. |
+| `BURN` | Burn tokens from own wallet |
+| `SEND` | Send tokens to any address with `RECEIVE` permissions |
+| `SUPER_BURN` | Burn tokens from any other address's wallet (not own wallet, unless the address also has `BURN`) |
+| `MODIFY_POLICY_MANAGERS` | Update which addresses can change policy statuses |
+| `MODIFY_CONTRACT_HOOK` | Update the Wasm contract hook address |
+| `MODIFY_ROLE_PERMISSIONS` | Update which actions are assigned to which roles |
+| `MODIFY_ROLE_MANAGERS` | Update which addresses manage each role |
+
+### The `EVERYONE` Role
+
+Every namespace must define an `EVERYONE` role, which applies to any address not assigned a specific role.
+This is typically used to allow permissionless transfer (for public tokens) or restrict all actions
+(for fully permissioned assets where only whitelisted addresses can hold the token).
+
+The `EVERYONE` role cannot be assigned `MINT`, `SUPER_BURN`, or any namespace management actions.
+
+### Blacklist Roles
+
+Any role with no permitted actions acts as a blacklist role. Addresses assigned a blacklist role
+have all permissions revoked until the role is removed. This supersedes all other roles the
+address may hold.
+
+---
+
+## Policy Statuses
+
+Each action has a policy status that controls whether it is available across the entire namespace,
+regardless of individual role permissions:
+
+- **Enabled** (default): addresses with the correct role can perform the action
+- **Disabled**: no address can perform the action until it is re-enabled
+- **Sealed**: the current enabled/disabled state is permanently locked and cannot be changed
+
+Sealing a namespace management action effectively disables it permanently, even if sealed while enabled.
+Use sealing carefully, as it is irreversible.
+
+---
+
+## Wasm Contract Hook
+
+The Wasm contract hook allows issuers to extend compliance logic beyond what the Permissions module
+provides natively. The hook is invoked on every receive event for the permissioned asset. The contract
+receives `fromAddr`, `toAddr`, `action`, and `amount`, and can implement custom logic such as
+on-chain KYC checks, transfer limits, or reporting.
+
+The hook address is set in the namespace and can be updated by any address with the `MODIFY_CONTRACT_HOOK`
+role, unless that policy has been sealed.
+
+---
+
+## Example Namespace Configuration
+
+The following is an example namespace for a permissioned RWA token where only whitelisted addresses
+can receive the asset, and an admin address retains full management control:
+
+```json
+{
+  "denom": "factory/inj1address/myRWAToken",
+  "role_permissions": [
+    {
+      "name": "EVERYONE",
+      "role_id": 0,
+      "permissions": 0
+    },
+    {
+      "name": "admin",
+      "role_id": 1,
+      "permissions": 2013265920
+    },
+    {
+      "name": "investor",
+      "role_id": 2,
+      "permissions": 14
+    }
+  ],
+  "actor_roles": [
+    {
+      "actor": "inj1adminaddress",
+      "roles": ["admin"]
+    }
+  ],
+  "role_managers": [
+    {
+      "manager": "inj1adminaddress",
+      "roles": ["admin", "investor"]
+    }
+  ]
+}
+```
+
+In this configuration:
+- `EVERYONE` has no permissions, so by default no address can hold the asset
+- `admin` has full namespace management permissions
+- `investor` can receive, burn, and send the asset (`RECEIVE` + `BURN` + `SEND` = 14)
+- The admin must explicitly assign the `investor` role to each whitelisted address
+
+---
+
+## Managing the Asset
+
+### Adding Whitelisted Addresses
+
+Once the namespace is live, the role manager assigns roles to investor addresses:
+
+```bash
+injectived tx permissions update-namespace-roles <roles.json> [flags]
+```
+
+```json
+{
+  "denom": "factory/inj1address/myRWAToken",
+  "role_actors_to_add": [
+    {
+      "role": "investor",
+      "actors": ["inj1investor1", "inj1investor2"]
+    }
+  ]
+}
+```
+
+### Freezing the Asset
+
+To pause all transfers across the asset, disable the `SEND` and `RECEIVE` actions via a namespace update:
+
+```bash
+injectived tx permissions update-namespace <namespace-update.json> [flags]
+```
+
+```json
+{
+  "denom": "factory/inj1address/myRWAToken",
+  "policy_statuses": [
+    { "action": 2, "is_disabled": true, "is_sealed": false },
+    { "action": 8, "is_disabled": true, "is_sealed": false }
+  ]
+}
+```
+
+### Claiming a Voucher
+
+If a module-initiated transfer fails because the recipient lacks `RECEIVE` permissions, the funds
+are held in escrow. Once the recipient is granted the correct role, they can claim the funds:
+
+```bash
+injectived tx permissions claim-voucher <denom>
+```
+
+---
+
+## Further Reading
+
+- [Permissions Module — Concepts](/developers-native/injective/permissions/01_concepts)
+- [Permissions Module — State](/developers-native/injective/permissions/02_state)
+- [Permissions Module — State Transitions](/developers-native/injective/permissions/03_state_transitions)
+- [TokenFactory Module](/developers-native/injective/tokenfactory/01_concepts)
+- [iAssets](/defi/tokenization/iassets)