# DINO Secondary

Dino Secondary is the **shared secondary market rail** of the T-REX ecosystem.

It is a smart contract deployed on the **T-REX Ledger** that lets investors, distributors, and broker-dealers:

* **Publish on-chain intents (offers)** to buy or sell ERC-3643 (T-REX) tokens
* **Partially or fully take** existing offers
* **Share liquidity** across multiple platforms and dApps, instead of fragmenting it into isolated OTC channels

Every offer is created and settled directly onchain, with:

* Built-in compliance integration for ERC-3643
* Freezing of RWA tokens instead of moving them to escrow which helps maintain the integrity of the onchain cap tables at all times
* Configurable fee mechanisms for both the ecosystem and the asset issuer/operator

Dino Secondary is **not a single UI**. It is the **neutral onchain marketplace layer** that any T-REX-compatible application can plug into.

### Key Features

#### Intent-Based Trading

* **Offer creation** – Any investor or participant can publish an offer expressing their intent to:
  * Sell an ERC-3643 token for another token (e.g. stablecoin), or
  * Buy an ERC-3643 token by offering another token.
* **Flexibility** – Offers specify:
  * The token being offered (`tokenOut`)
  * The token requested (`tokenIn`)
  * The respective amounts
  * An expiration time

#### Partial Fills & Offer States

* Offers can be **partially filled** multiple times until:
  * Fully filled
  * Cancelled by the creator
  * Pruned after expiry or if conditions are no longer met
* The contract tracks:
  * Total offered amount
  * Filled amount
  * Remaining amount
  * Status (Active, Filled, Cancelled, Expired)

#### Two Token Handling Modes

Dino Secondary supports two ways to handle the asset vs payment tokens:

* **Freeze mode for ERC-3643 tokens**\
  When the offer is selling the ERC-3643 token:
  * The RWA tokens remain in the **seller’s wallet**
  * They are **frozen** using the ERC-3643 token’s built-in freeze mechanism
  * When the offer (or part of it) is taken, the relevant amount is unfrozen and transferred
* **Escrow mode for standard ERC-20 tokens**\
  When the offer is selling a non-ERC-3643 token:
  * Tokens are **transferred to the Dino Secondary contract** on offer creation
  * They stay in escrow until the offer is taken, cancelled, or pruned

This design ensures:

* RWA tokens remain tightly coupled with their identity/compliance logic
* Standard ERC-20s are handled with a classic escrow pattern

#### Compliance-Aware by Design

Dino Secondary is built for **ERC-3643 tokens**:

* At least one leg of every trade must involve the configured **ERC-3643 token** for this Dino Secondary instance.
* Transfers of that token are subject to the token’s existing compliance rules:
  * Identity registry checks
  * Eligibility / jurisdiction rules
  * Freeze/unfreeze controls
* If a transfer would violate compliance, the trade simply cannot be executed.

#### Shared Liquidity on the T-REX Ledger

All offers for a given ERC-3643 token are stored in the **same contract instance** on the T-REX Ledger. That means:

* Any dApp, broker-dealer, or platform integrating Dino Secondary taps into the **same pool of offers**.
* Liquidity is aggregated at the **contract level**, not at the UI level.
* New interfaces can appear (white-label platforms, wallets, institutional portals, aggregators) and **immediately see and use the existing offer book**.

### Actors & Roles

At a conceptual level, Dino Secondary involves:

* **Offer Creators (Makers)**\
  Investors or institutions who post offers to buy or sell the ERC-3643 token.
* **Offer Takers**\
  Counterparties who accept offers (fully or partially), triggering settlement.
* **Issuers / Operators**\
  Entities responsible for the ERC-3643 token and the market around it. They benefit from shared liquidity and may configure fees and operational parameters.
* **Platforms & dApps**\
  Any interface building on top of Dino Secondary: broker portals, investor dashboards, wallet integrations, etc.
* **Dino Secondary Contract**\
  The on-chain engine:
  * Stores & updates offers
  * Manages freezing / escrow of tokens
  * Enforces expiry and pruning
  * Handles fees
  * Relies on ERC-3643 compliance checks at settlement time

At the admin level, the contract uses an [**AccessManager**](https://docs.openzeppelin.com/contracts/5.x/api/access#AccessManager) with roles (such as `ADMIN_ROLE` and `FEE_MANAGER_ROLE`) to control pausing and fee configuration. Those details are described on the [**Admin & Management**](https://docs.t-rex.network/t-rex-network/t-rex-apps/dino/dino-secondary/admin-and-management) page.

### Trading Model & Offer Lifecycle

#### 1. Offer Creation

A maker:

1. Chooses:
   * Which token they are **offering** (`tokenOut`)
   * Which token they **want in return** (`tokenIn`)
   * Amounts and expiry
2. Calls `createOffer(...)` via their preferred dApp or platform.

Under the hood:

* If `tokenOut` is the ERC-3643 token:
  * Dino Secondary checks that the maker’s **free (unfrozen)** balance is sufficient
  * Freezes the offered amount in the maker’s wallet
* If `tokenOut` is a standard ERC-20:
  * Transfers the offered amount into escrow (the Dino Secondary contract)
* Records the offer in storage and emits an `OfferCreated` event
* Charges the relevant **ecosystem fee** for offer creation

#### 2. Taking an Offer

A taker:

1. Selects an offer and decides how much to take (can be partial).
2. Approves the appropriate token if needed (e.g. payment token).
3. Calls `takeOffer(offerID, amount)`.

Dino Secondary:

* Validates the offer is still active and not expired
* If the offer is no longer valid, it is automatically **pruned** and cannot be taken.
* Computes the corresponding counter-amount using the offer’s price ratio.
* Executes settlements:
  * **Unfreezing & transfer** when selling ERC-3643
  * **Escrow release** when selling standard ERC-20
  * Transfers the requested token from taker to maker
* Applies **volume-based fees** and any configured fixed fees.
* Updates the offer’s filled amount and marks it:
  * **Partially filled** (still active with reduced remaining size), or
  * **Filled** (fully executed and closed)
* Emits events (partially filled / filled) and charges **ecosystem fees**.

#### 3. Cancelling an Offer

Makers can cancel their own active offers:

* Call `cancelOffer(offerID)`.
* Dino Secondary:
  * Unfreezes ERC-3643 tokens or releases escrow as needed
  * Marks the offer as **Cancelled**
  * Emits `OfferCancelled` and charges the **ecosystem fee** for cancellation

#### 4. Pruning Expired or Invalid Offers

Any address can trigger pruning via `pruneOffer(offerID)`:

* If the offer:
  * Has expired, or
  * Is underfunded (e.g. maker moved their frozen tokens away or no longer has enough balance)
* Then:
  * Dino Secondary releases any frozen/escrowed tokens
  * Marks the offer as **Expired**
  * Emits `OfferPruned`

Pruning prevents stale or unsafe offers from being executed and keeps the active offer set clean.

### Compliance & ERC-3643 Integration

Dino Secondary is designed to align with all compliance guarantees of **ERC-3643**:

* The ERC-3643 token itself:
  * Validates transfers against its Identity Registry
  * Enforces eligibility rules (KYC/AML, jurisdiction, investor type, etc.)
  * Manages freeze/unfreeze states
* Dino Secondary always interacts with the token using its **standard interfaces**, which means:
  * If a transfer would violate compliance, the token reverts and the trade cannot be settled.
  * Freeze/unfreeze operations respect existing identity and permission structures.

As a result, **secondary market activity remains fully compliant** with the same rules as primary issuance and transfers.

### Fees & Incentives (High-Level)

Dino Secondary supports multiple fee layers:

* **T-REX Ecosystem Fees**\
  Collected via the shared **Ecosystem Fee Collector**, with different multipliers depending on the operation (offer creation, taking, cancellation).
* **Asset / Market-Level Fees**\
  Configurable by authorized operators (via the `FEE_MANAGER_ROLE`), including:
  * A **fixed fee** per trade
  * A **volume-based fee** (percentage) capped to protect users

Details on how to configure, calculate, and monitor these fees are covered in the [**Admin & Management**](https://docs.t-rex.network/t-rex-network/t-rex-apps/dino/dino-secondary/admin-and-management) page.

### Integration Patterns for Platforms & dApps

A typical integration with Dino Secondary follows these steps:

1. **Discovery & Display**
   * Query the list of open offers for a given ERC-3643 token.
   * Display:
     * Maker, price, remaining size, expiry, direction (buy/sell).
2. **Offer Creation (Maker UI)**
   * Provide a form where users choose:
     * Sell token / buy token
     * Amounts and expiry
   * Guide them through:
     * Approving tokens (if needed)
     * Calling `createOffer(...)`
3. **Offer Taking (Taker UI)**
   * Allow users to:
     * Select any open offer
     * Choose full or partial amount
   * Use preview helpers (from the Developer Reference) to show:
     * Exact amounts they will send/receive
     * Applicable fees
   * Call `takeOffer(...)` and display results.
4. **Offer Management**
   * Expose “My Offers” view:
     * List of user-created offers
     * Status, remaining amount, time to expiry
   * Provide actions to:
     * Cancel offers
     * Trigger pruning of expired or invalid offers

Because Dino Secondary is **shared infrastructure** on the T-REX Ledger, one integration lets your platform:

* Access all offers for that token
* Co-exist with other platforms and broker-dealers on the same liquidity pool

### Dino Secondary in the T-REX Apps Stack

Within the broader T-REX ecosystem:

* **DinoPrimary** handles compliant subscription & redemption (primary market).
* **DinoSecondary** handles intent-based secondary trading for the same ERC-3643 tokens.
* **DinoFactory** deploys both contracts and configures their access control consistently.
* **T-REX Engine** exposes APIs to read offers and interact with Dino Secondary programmatically.
* **DINO Secondary dApp** (and any other integrated front-ends) provide user-facing UIs on top of this shared contract.

### Related Documentation

For more details:

* [**Dino Secondary – Admin & Management**](https://docs.t-rex.network/t-rex-network/t-rex-apps/dino/dino-secondary/admin-and-management)\
  Roles, pausing, fee configuration, and operational best practices.
* [**Dino Secondary – Developer Reference**](https://docs.t-rex.network/t-rex-network/t-rex-apps/dino/dino-secondary/developer-reference)\
  Solidity interfaces, function signatures, events, error codes, and concrete integration examples.