> For the complete documentation index, see [llms.txt](https://bitbook.rwatokens.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://bitbook.rwatokens.net/cedex-and-trading/cedex-and-trading/smart-contract-reference.md).

# Smart Contract Reference

## Smart Contract Reference

**On-Chain Program Documentation · Solana Mainnet-Beta · Module-Aware Throughout**

Reference document for institutional reviewers, auditors, compliance officers, and integrators evaluating the platform's on-chain programs. This page documents what each program does, how the programs interact, what state they maintain, what events they emit, and how they enforce the 42 Transfer Hook controls — with explicit Module 1 (Equities), Module 2 (Real Estate), and Module 3 (CORECM — Carbon Ore, Rare Earth, and Critical Minerals) behavior surfaced in every program section.

The platform is operated by Groovy Company, Inc. The trading venue is CEDEX. The qualified-custody and onboarding anchor is Empire Stock Transfer. The same five programs serve all three modules at the structural level; module-specific behavior arises through module-aware oracles, additional SecurityConfig fields, and module-aware Transfer Hook checks documented inline below.

> This document describes **what** each program does, **why** each design decision exists, and **how each behavior is verified across modules**. Specific instruction signatures, account schemas, function bodies, and code-level details are maintained in the platform's internal program documentation and audit reports, accessible to authorized auditors under non-disclosure agreement.

***

### Table of Contents

1. ​Program Registry​
2. ​Transfer Hook Program​
3. ​AMM Program​
4. ​Liquidity Pool Program​
5. ​Governance Program​
6. ​Oracle Aggregator Program​
7. ​PDA Registry (All Programs)​
8. ​Event Registry (All Programs)​
9. ​State Machines​
10. ​Upgrade Authority Model​
11. ​Cross-Program Invocation Map​
12. ​Deployment Verification​
13. ​Module-Aware Program Behavior

***

### 1. Program Registry

The platform deploys five on-chain programs on Solana Mainnet-Beta. All five are written in Rust against the Anchor framework, audited by independent firms, and verified through Certora formal-verification specifications.

| Program               | Purpose                                                                                                              | Module Scope                                                                       | Upgrade Authority                        | Audit                                |
| --------------------- | -------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | ---------------------------------------- | ------------------------------------ |
| **Transfer Hook**     | Enforces the 42 sequential security controls on every ST22 token transfer. The foundational security layer.          | All modules — module-aware checks for Module 2 (NAV) and Module 3 (Classification) | 5-of-9 multi-signature plus 24h timelock | Certora plus Quantstamp plus Halborn |
| **AMM**               | Constant Product Market Maker engine. Native SPL Token-2022 Transfer Hook support.                                   | All modules — same fee distribution; per-mint pool isolation                       | 5-of-9 multi-signature plus 24h timelock | Certora plus OtterSec                |
| **Liquidity Pool**    | Global Unified CEDEX Liquidity Pool. LP tokens burned at initialization.                                             | All modules — single pool aggregating all module activity                          | **None — immutable program**             | Certora                              |
| **Governance**        | On-chain proposal and voting system for adjustable parameters.                                                       | All modules — same governance for module-shared and module-specific parameters     | 3-of-5 multi-signature                   | Halborn                              |
| **Oracle Aggregator** | Aggregates and validates oracle data from custody, OFAC, AML, NAV (Module 2), and Classification (Module 3) sources. | All modules — module-specific oracles initialized per mint                         | 5-of-9 multi-signature plus 24h timelock | Quantstamp                           |

Production program addresses are published in the Network Configuration document at mainnet deployment (Q3 2026). Until that point, this document refers to programs by descriptive name rather than address.

The five programs are deployed in dependency order: Transfer Hook (no dependencies) → Oracle Aggregator → Liquidity Pool → AMM → Governance. The deployment sequence is identical regardless of how many modules are in production; module-specific oracle initialization happens per-mint at issuance time, not at platform deployment.

***

### 2. Transfer Hook Program

**Purpose.** Enforces 42 sequential security controls on every ST22 token transfer through SPL Token-2022 cross-program invocation. The foundational security layer. All other programs depend on this.

**Why this program is special.** SPL Token-2022 introduced the Transfer Hook extension, which lets a token's mint specify a program that must approve every transfer. Once the hook is attached, it cannot be removed. This is what makes 100% compliance enforcement possible — every transfer of a Module 1, Module 2, or Module 3 ST22 token must pass all 42 controls; there is no path that bypasses them.

**Module relationship.** A single Transfer Hook deployment serves Module 1, Module 2, and Module 3 ST22 mints uniformly. Per-mint configuration in the SecurityConfig PDA carries module-specific parameters; module-aware oracle reads happen at runtime based on which oracles exist for the affected mint.

#### 2.1 Program Responsibilities

The Transfer Hook program performs three distinct functions:

| Function                                 | Frequency                                               | Trigger                                   | Module Scope                                                 |
| ---------------------------------------- | ------------------------------------------------------- | ----------------------------------------- | ------------------------------------------------------------ |
| **Hook execution**                       | Every ST22 transfer                                     | SPL Token-2022 cross-program invocation   | All modules — same execution path                            |
| **Per-mint configuration management**    | Once at mint creation; periodic parameter updates       | Admin instruction (multi-signature gated) | All modules — module-specific fields populated per mint type |
| **Per-investor holding-period tracking** | Once at token delivery; lock state queried per transfer | Empire Stock Transfer onboarding          | All modules — same Reg D / Reg S / Reg CF regimes            |

#### 2.2 Per-Mint Configuration State (SecurityConfig)

For each ST22 mint, the Transfer Hook program maintains a SecurityConfig state account. The same account schema serves all three modules; module-specific extensions sit in dedicated fields that are populated at mint creation based on module type.

**Cross-module fields (always populated):**

* The mint address and the configuration version.
* The maximum wallet concentration (default 4.99%, governance-adjustable between 1.00% and 9.99%).
* The circuit breaker threshold and cooldown duration.
* The price-impact maximum versus TWAP.
* The TWAP window seconds and minimum observations.
* The holding-period configuration (Reg D 6 months, Reg S 12 months, Reg CF 12 months — jurisdiction-specific durations are immutable program constants).
* The volume tracker (24-hour rolling buckets for spike detection).
* A blacklist of permanently-blocked wallets (OFAC SDN matches).
* The pause state (set true by Control 42 regulatory freeze).

**Module 1 (Equities) — no additional fields.** Standard SecurityConfig with default parameters. EDGAR-pipeline issuer-eligibility intelligence flows through Layer 9 IDOS off chain; the hook reads only the issuer-eligibility flag synthesized into the existing Control IV-08 path.

**Module 2 (Real Estate) — additional fields:**

* `nav_deviation_max_bps` — maximum allowed deviation between on-chain price and the most recent appraised NAV.
* `nav_reappraisal_max_age_secs` — maximum age of a NAV appraisal before the mint is paused on the AMM.
* `nav_circuit_breaker_enabled` — flag enabling the NAV-deviation circuit breaker.

For Module 2 mints, the wallet-concentration cap may be issuer-configured up to 9.99% (single-asset real-estate offerings often have natural concentration patterns where a single institutional investor holds a significant share).

**Module 3 (CORECM) — additional fields:**

* `classification_max_age_secs` — maximum age of the Classification oracle before staleness review.
* `federal_action_freeze_enabled` — flag enabling automatic Control 42 freeze coordination on detected federal action.

The configuration account is per-mint, not global. A pause on one ST22 mint does not affect other mints unless the pause is platform-wide. A federal-action freeze on one Module 3 mint does not affect other Module 3 mints unless the action references multiple basins.

#### 2.3 Per-Investor Holding Period State

For each investor-mint pair, the Transfer Hook program maintains a HoldingPeriodAccount. The schema is identical across modules:

* The beneficiary wallet address and mint address.
* The purchase timestamp (set by the Solana runtime clock at delivery — never by user input).
* The jurisdiction flag (US, Non-US, or Reg CF).
* The holding period in seconds (15,778,800 for US accredited under Reg D Rule 144; 31,536,000 for non-US under Reg S; 31,536,000 for US retail under Reg CF).
* The lock status.

The holding period seconds are hard-coded program constants. Governance cannot reduce them below the statutory minimum. The purchase timestamp is immutable post-creation and is verified by the Solana runtime clock — it cannot be backdated by any party. The same regime applies to Module 1, Module 2, and Module 3 investors.

#### 2.4 The 42 Controls

The Transfer Hook program executes 42 sequential controls on every transfer. The controls are documented in the Compliance Integration Guide §3 and consolidated in the Transfer Hook Reference. A high-level summary with module-aware annotations:

| Control Group                 | Range                | Function                                                                                                     | Module-Aware Behavior                                                                                                              |
| ----------------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- |
| Custody verification          | CV-01 through CV-06  | Verify Empire's per-block 1:1 attestation                                                                    | Same across all modules; CV-05 verifies the asset identifier (CUSIP for Module 1, property ID for Module 2, basin ID for Module 3) |
| Investor verification         | IV-07 through IV-14  | Verify KYC, accreditation (Reg D / Reg S / Reg CF), AML, identity, jurisdiction, age, classification, expiry | Module 3 requires enhanced KYC depth (beneficial ownership to ultimate owner)                                                      |
| Position limits               | PL-15 through PL-19  | Wallet whitelist, concentration, velocity, clustering, cumulative position                                   | Module 2 concentration cap (PL-16) may be issuer-configured up to 9.99%                                                            |
| Circuit breakers              | CB-20 through CB-23  | Price halt, price impact, velocity, oracle failure                                                           | **Module 2: CB-21 also enforces NAV-deviation breaker.** Module 3: CB-23 also pauses on Classification oracle failure.             |
| Holding period                | HP-24 through HP-29  | Reg D / Reg S / Reg CF holding-period enforcement                                                            | Same across all modules                                                                                                            |
| Sanctions compliance          | SC-30 through SC-34  | Three-layer OFAC screening, continuous re-screening, blacklist                                               | Same across all modules; Module 3 incidents may trigger coordinated regulatory action                                              |
| Protective conversion         | PC-35 through PC-38  | Issuer bankruptcy, SEC enforcement, Empire service loss, tripartite breach                                   | Module 3 adds an implicit federal-action trigger via PC-37 (Empire discretion)                                                     |
| Record-keeping and governance | RK-39 through REG-42 | Audit trail, hash-chain integrity, controlled migration, regulatory freeze                                   | **Module 3: REG-42 has automatic federal-action freeze coordination** through the Classification oracle                            |

#### 2.5 Hook Execution Flow

The hook executes controls in two phases. The execution structure is identical across modules; the difference is which oracles the parallel-phase controls read.

```
SEQUENTIAL (critical path — each must pass before next is evaluated):
  CV-01 through CV-06   →   Custody verification (Ed25519 attestation, 1:1 ratio)
  IV-07 through IV-14   →   Investor eligibility
  HP-24                 →   Holding period

PARALLEL (remaining controls execute together; any failure reverts atomically):
  PL-15 through PL-19   →   Position limits
  CB-20 through CB-23   →   Circuit breakers
                            (Module 2: + NAV-deviation read)
                            (Module 3: + Classification staleness read)
  SC-30 through SC-34   →   Sanctions compliance
  PC-35 through PC-38   →   Protective conversion
  RK-39 through REG-42  →   Audit trail and governance
                            (Module 3: + Classification federal-action read)

EMIT:
  TransferValidated event with all 42 controls' results
```

If any control fails, the entire transfer reverts — the Solana runtime guarantees atomicity, so no state changes are persisted on a partially-evaluated transfer.

The hook is **not callable directly**. The SPL Token-2022 runtime is the only caller; any direct invocation is rejected.

#### 2.6 Adjustable Parameters and Hard-Coded Bounds

The same parameter table applies to Module 1, Module 2, and Module 3 mints. Module-specific parameters (NAV deviation, classification age) follow the same governance bounds discipline.

| Parameter                       | Minimum    | Maximum      | Default                           | Immutable?                          | Module Scope                              |
| ------------------------------- | ---------- | ------------ | --------------------------------- | ----------------------------------- | ----------------------------------------- |
| Maximum wallet concentration    | 100 (1%)   | 999 (9.99%)  | 499 (4.99%)                       | No                                  | All modules; Module 2 may use up to 9.99% |
| Circuit breaker threshold       | 1000 (10%) | 5000 (50%)   | 3000 (30%)                        | No                                  | All modules                               |
| Circuit breaker cooldown        | 3600 (1h)  | 259200 (72h) | 86400 (24h)                       | No                                  | All modules                               |
| Price impact maximum (vs TWAP)  | 100 (1%)   | 500 (5%)     | 200 (2%)                          | No                                  | All modules                               |
| TWAP window                     | 900 (15m)  | 3600 (1h)    | 1800 (30m)                        | No                                  | All modules                               |
| TWAP minimum observations       | —          | —            | 60                                | **Yes**                             | All modules                               |
| Holding period (Reg D)          | —          | —            | 15,778,800 (6 months)             | **Yes**                             | All modules                               |
| Holding period (Reg S, Reg CF)  | —          | —            | 31,536,000 (12 months)            | **Yes**                             | All modules                               |
| `nav_deviation_max_bps`         | Per mint   | Per mint     | Per mint (typically 2200 = 22%)   | No                                  | **Module 2 only**                         |
| `nav_reappraisal_max_age_secs`  | Per mint   | Per mint     | Per mint (per tripartite cadence) | No                                  | **Module 2 only**                         |
| `classification_max_age_secs`   | Per mint   | Per mint     | Per mint (typically 86400 = 24h)  | No                                  | **Module 3 only**                         |
| `federal_action_freeze_enabled` | —          | —            | true                              | No (governance-toggleable per mint) | **Module 3 only**                         |

Parameters marked "Immutable" are hard-coded program constants. Governance cannot adjust them through any procedure, including emergency action. This is verified by Certora invariant E.4.

#### 2.7 Error Codes

The same error code map applies regardless of module. Module 2 NAV-deviation failures map to error 6021 (`PriceImpactExceeded`) with an `nav_variant` flag; Module 3 federal-action freezes map to error 6042 (`RegulatoryOverride`) with a `federal_action` source flag. The Transfer Hook Reference §Errors and the CEDEX API Reference §8 enumerate the module-specific variants.

| Code | Name                       | Category        | Module Scope                                          |
| ---- | -------------------------- | --------------- | ----------------------------------------------------- |
| 6001 | Custody discrepancy        | Custody         | All modules                                           |
| 6002 | Custody oracle unavailable | Custody         | All modules                                           |
| 6003 | Sender sanctioned          | Sanctions       | All modules                                           |
| 6004 | Receiver sanctioned        | Sanctions       | All modules                                           |
| 6005 | OFAC oracle stale          | Sanctions       | All modules                                           |
| 6006 | AML high risk              | AML             | All modules                                           |
| 6007 | Invalid signer             | CEI             | All modules                                           |
| 6020 | Wallet limit exceeded      | Position        | All modules                                           |
| 6021 | Price impact exceeded      | Circuit Breaker | All modules; Module 2 includes NAV-deviation variant  |
| 6022 | Velocity exceeded          | Position        | All modules                                           |
| 6023 | Cross-wallet detected      | Position        | All modules                                           |
| 6024 | Tokens locked              | Holding Period  | All modules; Reg D / Reg S / Reg CF variants          |
| 6036 | Global circuit breaker     | Emergency       | All modules                                           |
| 6037 | Daily sell limit exceeded  | Volume          | All modules                                           |
| 6038 | Custody discrepancy halt   | Emergency       | All modules                                           |
| 6039 | OFAC emergency block       | Emergency       | All modules                                           |
| 6040 | Oracle consensus fail      | Emergency       | All modules                                           |
| 6041 | Controlled migration       | Governance      | All modules                                           |
| 6042 | Regulatory override        | Regulatory      | All modules; Module 3 includes federal-action variant |

#### 2.8 Compute Budget

The hook logic itself uses approximately 3,500 compute units. Total transfer cost varies slightly by module due to additional oracle reads:

| Module   | Additional Oracle Reads                              | Total Compute (approx.) |
| -------- | ---------------------------------------------------- | ----------------------- |
| Module 1 | None beyond standard set                             | \~800,000 CU            |
| Module 2 | NAVOracle PDA read + deviation check                 | \~820,000 CU            |
| Module 3 | ClassificationOracle PDA read + federal-action check | \~830,000 CU            |

All three figures fit well within Solana's per-transaction compute budget.

***

### 3. AMM Program

**Purpose.** Constant Product Market Maker engine with native SPL Token-2022 Transfer Hook support. Every swap triggers all 42 Transfer Hook controls. This is the structural reason external DEXes (Raydium, Orca, Jupiter) cannot serve ST22 tokens — they call the original SPL Token Program, which bypasses the hook entirely.

**Module relationship.** The same AMM program serves all three modules. Each ST22 mint — Module 1, 2, or 3 — gets its own pool with the same constant-product mechanics. The fee distribution is identical (2% / 1.5% / 1.06% / 0.44%). The structural difference between modules is in pool dynamics: Module 2 pools have the additional NAV-deviation constraint imposed by the Transfer Hook; Module 3 pools have the additional federal-action freeze possibility.

#### 3.1 Pool Creation

Pools are protocol-controlled. Only the platform can initialize trading pools for ST22 tokens. Third parties cannot create pools. This applies identically to Module 1, Module 2, and Module 3 mints.

When a pool is initialized:

1. The mint is verified to have the platform's Transfer Hook extension permanently attached.
2. The pool is initialized with the constant-product invariant `k = initial_sol × initial_tokens`.
3. LP tokens are minted and immediately burned. The LP mint authority is set to `None`. No path to reconstitute the LP supply exists.
4. The pool is linked to the Global Unified CEDEX Liquidity Pool for fee deposit routing.
5. **For Module 2 pools:** the AMM verifies the mint has a configured NAVOracle PDA before pool initialization is permitted.
6. **For Module 3 pools:** the AMM verifies the mint has a configured ClassificationOracle PDA before pool initialization is permitted.

#### 3.2 Swap Execution

Every swap follows the same sequence regardless of module. Module-specific behavior surfaces inside the Transfer Hook invocation in step 3.

```
1. Calculate swap output using the constant-product formula
2. Check price impact versus TWAP — reject if above max_price_impact_bps (Control CB-21)
3. Execute Token-2022 transfer (triggers Transfer Hook → all 42 controls)
   ├─ Module 1 path: standard 42 controls
   ├─ Module 2 path: standard 42 + NAV-deviation read in CB-21
   └─ Module 3 path: standard 42 + Classification reads in CV-04 and REG-42
4. If hook passes → update pool reserves, distribute fees
5. If hook fails → entire transaction reverts atomically (zero state changes)
6. Emit SwapExecuted event with full fee breakdown
```

For a Module 2 mint paused due to NAV-deviation breach, swaps are rejected at step 3 with Error 6021 (NAV variant). For a Module 3 mint frozen by federal action, swaps are rejected at step 3 with Error 6042 (federal-action variant). Other mints — including other Module 2 or Module 3 mints not subject to the same condition — are unaffected.

#### 3.3 Constant-Product Mechanics

The CPMM uses the standard constant-product invariant: `x × y = k`. The 5% fee is deducted from the input amount before the invariant calculation. Every swap increases `k` by the fee amount — this is the structural property that makes the pool's value monotonically non-decreasing. This property holds identically for Module 1, Module 2, and Module 3 pools.

| Operation                         | Rounding         | Rationale                                |
| --------------------------------- | ---------------- | ---------------------------------------- |
| Output amount                     | Floor (truncate) | Pool never overpays — `k` only increases |
| Input amount (exact-output swaps) | Ceiling          | Pool never under-receives                |
| Fee calculation                   | Floor            | Conservative accounting                  |

All arithmetic uses 128-bit unsigned integers with checked-math. Overflow returns Error 7004 rather than wrapping.

#### 3.4 Fee Distribution

Every successful swap distributes the 5% protocol fee across four destinations. Fee distribution is identical across modules:

| Destination                         | Allocation      | Purpose                                      | Module Scope                         |
| ----------------------------------- | --------------- | -------------------------------------------- | ------------------------------------ |
| Global Unified CEDEX Liquidity Pool | 0.44% (44 bps)  | Permanently locked; pool grows monotonically | All modules — single shared pool     |
| Issuer treasury                     | 2.00% (200 bps) | Issuer's revenue share                       | All modules — per-mint issuer wallet |
| GROO staking pool                   | 1.50% (150 bps) | Staking reward distribution                  | All modules — single shared pool     |
| Protocol operations                 | 1.06% (106 bps) | Platform operations                          | All modules — single platform wallet |

The four allocations sum to 5.00%. This is a program invariant: the bps values must add to the total fee bps. Any configuration violating this is rejected at the program level.

#### 3.5 Error Codes

Same error map across modules. Module 2 and Module 3 mints can additionally surface Transfer Hook errors that abort swap execution at step 3 of the sequence.

| Code | Name                       | Trigger                                         |
| ---- | -------------------------- | ----------------------------------------------- |
| 7001 | Insufficient liquidity     | Pool reserves too low for swap                  |
| 7002 | Slippage exceeded          | Output below minimum amount out                 |
| 7003 | Pool not active            | Pool paused or not initialized                  |
| 7004 | Overflow                   | 128-bit arithmetic overflow                     |
| 7005 | Zero division              | Division by zero in CPMM calculation            |
| 7006 | Invalid mint               | Mint missing Transfer Hook extension            |
| 7007 | Unauthorized pool creation | Non-protocol authority attempted initialization |
| 7008 | Pool already exists        | Pool PDA already initialized for mint           |
| 7009 | LP not burned              | LP tokens not burned (should never occur)       |
| 7010 | Fee mismatch               | Fee config bps do not sum to total              |

***

### 4. Liquidity Pool Program

**Purpose.** Operates the Global Unified CEDEX Liquidity Pool — a single protocol-owned capital reserve serving all ST22 issuers across all three modules. LP tokens are burned at initialization. **The program has no upgrade authority — it is permanently immutable.**

**Module relationship.** The Global Pool is module-agnostic by design. A Module 1 swap, a Module 2 swap, and a Module 3 swap all route the same 0.44% fee allocation to the same Global Pool. Pool reserves grow monotonically across all module activity combined. There is no separate per-module pool.

#### 4.1 Initialization

The Global Pool is initialized once, at platform deployment. Initialization:

1. Creates the GlobalPool state account (PDA: `[b"global-pool"]`).
2. Creates the SOL reserve vault.
3. Creates the LP mint.
4. Burns all LP tokens by setting the LP mint authority to `None`.
5. Records the initialization timestamp and seed amount.

After initialization, **no instruction in any program can withdraw SOL from the pool.** The withdrawal function does not exist in the program code. This is verified by Certora invariant E.3 as a mathematical proof (not a test).

#### 4.2 Fee Deposits

The only function that mutates the Global Pool's state is `deposit_fee`, which is callable only via cross-program invocation from the AMM program. Every successful swap — Module 1, Module 2, or Module 3 — automatically routes the 0.44% fee allocation to the Global Pool through this single instruction.

Direct external calls to `deposit_fee` are rejected — the AMM program PDA must be the signer.

#### 4.3 Immutability

The Liquidity Pool program's upgrade authority is removed at deployment via the Solana CLI `--final` flag. Once removed, the upgrade authority cannot be restored. No combination of multi-signature votes, governance proposals, or legal orders can modify the program. This is the architectural foundation of the Global Pool non-extractability guarantee. The immutability applies regardless of module activity — even adding a hypothetical Module 4 in the future would not change the Liquidity Pool program.

#### 4.4 Certora Invariant E.3 — Global Pool Non-Extractability

Stated formally: for every program state `s` and every instruction `i`, executing `i` against `s` cannot produce a successor state `s'` where the Global Pool balance is less than the original. The Certora Prover verifies this invariant against the deployed bytecode of every program in the workspace. The proof is published with the audit reports.

The invariant covers all module activity: Module 1 fee deposits, Module 2 fee deposits, and Module 3 fee deposits all monotonically increase the pool balance.

#### 4.5 Cross-Module Pool Behavior

The Global Pool serves all three modules identically:

* A swap of a Module 1 ST22 token, a Module 2 real-estate ST22 token, or a Module 3 CORECM ST22 token routes the same 0.44% fee allocation to the same pool.
* The pool balance reflects fees aggregated across all module activity.
* A federal-action freeze on a single Module 3 mint does not affect the Global Pool — the pool continues receiving fees from other Module 3 mints, all Module 1 mints, and all Module 2 mints.
* A NAV-deviation pause on a single Module 2 mint does not affect the Global Pool — the pool continues receiving fees from other Module 2 mints, all Module 1 mints, and all Module 3 mints.
* The pool's growth rate over time reflects the combined trading activity of all three modules.

***

### 5. Governance Program

**Purpose.** On-chain proposal and voting system for adjustable protocol parameters. Governance can adjust parameter values within hard-coded bounds and execute program upgrades — but the 42 Transfer Hook controls themselves cannot be weakened by any governance procedure. This applies uniformly to Module 1, Module 2, and Module 3.

**Module relationship.** Governance proposals can target cross-module parameters (TWAP window, circuit breaker threshold) or module-specific parameters (Module 2 NAV deviation tolerance, Module 3 classification age). The governance program does not segregate proposals by module — a single proposal can affect a single mint, multiple mints across modules, or all mints platform-wide depending on the target parameter.

#### 5.1 Proposal Types

| Proposal Type        | Voting Threshold                          | Timelock         | Cancellation         | Module Scope                                               |
| -------------------- | ----------------------------------------- | ---------------- | -------------------- | ---------------------------------------------------------- |
| Parameter Adjustment | Simple majority                           | 48 hours         | 2-of-5 during window | All modules; can target single mint or all mints           |
| Program Upgrade      | 66.67% supermajority                      | 24 hours         | 2-of-5 during window | All modules — programs serve all modules uniformly         |
| Emergency Action     | 3-of-5 multi-signature plus Legal Counsel | None — immediate | None                 | All modules; Module 3 federal-action freezes use this path |

#### 5.2 Parameter Adjustment Procedure

1. A governance participant creates a proposal specifying the target parameter, the new value, and a description.
2. The voting period opens for at least 48 hours.
3. Vote tallies are recorded on chain.
4. If passed (simple majority), the proposal enters a 48-hour timelock.
5. During the timelock window, 2-of-5 of the parameter-authority multi-signature can cancel the proposal.
6. After timelock expiry, the 3-of-5 parameter-authority multi-signature executes the parameter update on chain.

Parameters cannot be set outside their hard-coded bounds. The program rejects any update that would push a parameter outside its `min`–`max` range, regardless of how the proposal was passed. Module-specific parameters (Module 2 `nav_deviation_max_bps`, Module 3 `classification_max_age_secs`) follow the same governance discipline.

#### 5.3 Program Upgrade Procedure

The same procedure as parameter adjustment, with three additional requirements:

1. The voting threshold is 66.67% supermajority, not simple majority.
2. The new program bytecode hash must be attested as matching an audited release.
3. Certora formal verification must pass on the new bytecode before execution.
4. The 5-of-9 upgrade-authority multi-signature (not the 3-of-5 parameter-authority) executes the upgrade.

A program upgrade affects all three modules simultaneously — a Transfer Hook upgrade applies to Module 1, Module 2, and Module 3 ST22 mints uniformly. There is no module-specific program upgrade; if module behavior needs to change independently, the change happens through module-specific parameters or new oracle behavior, not through program forking.

#### 5.4 Emergency Action

Emergency actions — primarily Control 42 regulatory freezes — bypass the timelock. Emergency authority requires:

* Legal Counsel authorization (documented in the platform's compliance system).
* 3-of-5 emergency-authority multi-signature.

Emergency actions are limited to specific operations defined in the program code: regulatory freezes (Control 42), oracle key rotations under emergency conditions, and circuit-breaker overrides. Emergency authority cannot upgrade programs or adjust parameters outside their normal governance scope.

**Module 3 federal-action freezes use this path.** When the platform's Classification oracle detects a federal action against a basin or mineral class associated with an issued Module 3 mint, the Incident Response Playbook §13 procedure executes Control 42 through this emergency-action channel — Legal Counsel authorization plus 3-of-5 multi-signature within a 60-minute SLA from detection.

#### 5.5 Proposal State Machine

```
CREATED ──► ACTIVE (voting period: at least 48h)
              │
              ├─ Votes meet threshold → PASSED
              ├─ Votes below threshold → FAILED
              ├─ Proposer cancels → CANCELLED
              │
              ▼
         PASSED ──► TIMELOCK PENDING
              │        Parameter Adjustment: 48h
              │        Program Upgrade: 24h
              │        Emergency Action: 0h (immediate)
              │
              ├─ 2-of-5 cancel during timelock → CANCELLED
              │
              ▼
         EXECUTED ──► On-chain state change applied
```

The state machine is identical regardless of which module a proposal affects. A Module 2 NAV-deviation tolerance adjustment, a Module 3 classification age adjustment, and a cross-module Transfer Hook upgrade all flow through the same state transitions.

***

### 6. Oracle Aggregator Program

**Purpose.** Aggregates and validates oracle data from seven sources before exposing it to the Transfer Hook program. Manages Ed25519 signature verification, staleness checks, consensus logic, and module-specific oracle lifecycles.

**Module relationship.** Five oracle categories serve all modules (Custody, OFAC, AML, TWAP, EDGAR for Module 1). Two oracle categories are module-specific: NAV (Module 2) and Classification (Module 3). The Oracle Aggregator program implements all seven; module-aware behavior is determined by which oracles exist for a given mint.

#### 6.1 Oracle Sources

| Oracle         | Source                                                                         | Update Cadence                    | Module Scope                    |
| -------------- | ------------------------------------------------------------------------------ | --------------------------------- | ------------------------------- |
| Custody        | Empire Stock Transfer (Ed25519-attested)                                       | Every Solana block (\~400ms)      | All modules                     |
| OFAC           | U.S. Treasury OFAC API                                                         | Hourly plus emergency push        | All modules                     |
| AML            | Chainalysis KYT plus TRM Labs                                                  | Per-transfer (cached 6h)          | All modules                     |
| TWAP           | Pyth Network (on-chain)                                                        | Continuous                        | All modules                     |
| EDGAR          | SEC EDGAR RSS plus EFTS                                                        | 60-second poll plus daily batch   | **Module 1 (Equities) only**    |
| NAV            | Independent licensed appraisers                                                | Per reappraisal-cycle cadence     | **Module 2 (Real Estate) only** |
| Classification | USGS Critical Minerals List, DOE Critical Materials Strategy, Federal Register | Daily plus emergency on EO update | **Module 3 (CORECM) only**      |

#### 6.2 Custody Oracle Update

The custody-relay service submits Empire-signed attestations to the oracle. The same flow serves Module 1, Module 2, and Module 3 mints — each ST22 mint has its own CustodyOracle PDA, and Empire's per-block attestation covers the affected mint regardless of module.

Each update goes through:

1. **Ed25519 signature verification** via the Solana Ed25519 precompile against Empire's registered public key.
2. **Slot freshness verification** — the slot in the payload must be the current slot or one slot prior.
3. **1:1 ratio check** — the custodied balance must be greater than or equal to the on-chain token supply. If less, `discrepancy_detected` is set true.
4. **State update** — the CustodyOracle account state is updated.
5. **Event emission** — `CustodyAttestationUpdated` for every successful update; `CustodyDiscrepancyDetected` when a discrepancy is detected.

The Custody Oracle is per-mint (PDA seeds: `[b"custody-oracle", mint]`). Each ST22 mint — Module 1, 2, or 3 — has its own oracle account.

#### 6.3 OFAC Oracle Update

The OFAC indexer service submits SDN-list refresh updates as a hash-of-list plus entry count. The actual SDN entries are tracked off chain (the Solana account size limit makes on-chain storage of the full SDN list infeasible); the on-chain hash provides cryptographic commitment to the indexer's view of the list.

The OFAC oracle is a global singleton (PDA seeds: `[b"ofac-oracle"]`). One OFAC oracle serves all mints across all modules.

#### 6.4 AML Oracle Update

The AML bridge service submits per-wallet AML scores from Chainalysis KYT and TRM Labs. The on-chain account caches the higher of the two scores for 6 hours. After cache expiry, the next transfer attempt requires a fresh score, which the AML bridge fetches before the transfer can proceed.

The AML Oracle is per-wallet (PDA seeds: `[b"aml-oracle", wallet]`). Same wallet AML score applies across all module activity for that wallet — a wallet that fails AML cannot trade Module 1, Module 2, or Module 3 ST22 mints.

#### 6.5 EDGAR Oracle (Module 1 only)

The EDGAR pipeline polls the SEC EDGAR RSS feed every 60 seconds for new filings (8-K, 10-K, 10-Q, Form D, DEF 14A, 15c2-11) and runs a daily EFTS full-text search batch at 02:00 UTC across the complete corpus. The pipeline feeds two consumers:

* **Control IV-08 (Transfer Hook)** — issuer eligibility flag synthesized into the SecurityConfig.
* **Layer 9 IDOS off-chain compliance** — issuer-disclosure intelligence for onboarding priority and ongoing monitoring.

The EDGAR oracle does not have a dedicated on-chain account; it influences the Module 1 SecurityConfig's eligibility flags and the off-chain IDOS scoring system. Module 2 and Module 3 issuers are not EDGAR-monitored — Module 2 disclosure flows through NAV oracles and tripartite-agreement reporting; Module 3 disclosure flows through Classification oracles and federal-source monitoring.

#### 6.6 NAV Oracle (Module 2 only)

The NAV Oracle holds the most recent appraised Net Asset Value for a Module 2 ST22 mint. The appraiser submits a signed appraisal to the NAV relay service, which submits it on chain after verifying the appraiser's authentication credentials and license validity at the time of appraisal. The Transfer Hook reads this oracle to enforce the NAV-deviation circuit breaker.

The NAV Oracle is per-mint (PDA seeds: `[b"nav-oracle", mint]`) and exists only for Module 2 ST22 mints. The PDA account holds the appraised NAV in USD-pegged stablecoin units, the appraiser identifier, the appraisal timestamp, the next-reappraisal target timestamp, the deviation tolerance, and the staleness threshold.

#### 6.7 Classification Oracle (Module 3 only)

The Classification Oracle holds the most recent USGS Critical Minerals List classification, DOE Critical Materials Strategy status, and federal-action status for a Module 3 ST22 mint's basin asset. The classification relay service polls federal sources on a 5-minute cadence (federal-action detection) and submits routine classification refreshes daily plus emergency pushes on Executive Order updates or court orders.

The Classification Oracle is per-mint (PDA seeds: `[b"classification-oracle", mint]`) and exists only for Module 3 ST22 mints. The PDA account holds the USGS classification, DOE status, Section 232 applicability flag, DPA Title III applicability flag, federal-action active flag, an array of active action references, and the last refresh timestamp.

#### 6.8 Staleness Thresholds

| Oracle         | Cache Valid      | Warning                               | Halt                                                | Module Scope |
| -------------- | ---------------- | ------------------------------------- | --------------------------------------------------- | ------------ |
| Custody        | 1 slot (\~400ms) | Above 3 slots                         | Above 1 slot (Error 6002)                           | All modules  |
| OFAC           | 24 hours         | Above 12 hours                        | Above 48 hours (Error 6005)                         | All modules  |
| AML            | 6 hours          | Above 3 hours                         | No score available (Error 6006)                     | All modules  |
| TWAP           | 5 minutes        | Above 2 minutes                       | Above 5 minutes (breaker disabled)                  | All modules  |
| EDGAR          | 36 hours         | Above 24 hours                        | No halt — continue with last batch                  | Module 1     |
| NAV            | Per-property     | 50% of `nav_reappraisal_max_age_secs` | Beyond `nav_reappraisal_max_age_secs` (mint paused) | Module 2     |
| Classification | 24 hours         | Above 12 hours                        | Above 48 hours (enhanced review on transfers)       | Module 3     |

#### 6.9 Key Rotation

Oracle relay keys can be rotated through governance proposal. Empire's custody attestation key has special handling: rotation requires Empire to communicate the new key through documented chain-of-custody, followed by a governance proposal that updates the Empire public key on every CustodyOracle account, followed by 5-of-9 multi-signature execution. The 48-hour timelock applies unless emergency override is authorized.

Module-specific oracle keys (NAV relay authority, Classification relay authority) follow the same governance procedure. Module 2 appraiser keys are managed per appraiser engagement under the tripartite agreement — when a new appraiser is engaged, their public key is registered in the NAV relay's authorized appraiser registry; old appraiser keys remain valid for verification of historical appraisals but cannot sign new attestations.

***

### 7. PDA Registry (All Programs)

| PDA                      | Seeds                                    | Program           | One Per          | Module Scope      |
| ------------------------ | ---------------------------------------- | ----------------- | ---------------- | ----------------- |
| SecurityConfig           | `[b"security-config", mint]`             | Transfer Hook     | ST22 mint        | All modules       |
| HoldingPeriodAccount     | `[b"holding-period", mint, beneficiary]` | Transfer Hook     | Investor × mint  | All modules       |
| ExtraAccountMetaList     | Token-2022 standard derivation           | Transfer Hook     | ST22 mint        | All modules       |
| CustodyOracle            | `[b"custody-oracle", mint]`              | Oracle Aggregator | ST22 mint        | All modules       |
| OFACOracle               | `[b"ofac-oracle"]`                       | Oracle Aggregator | Global singleton | All modules       |
| AMLOracle                | `[b"aml-oracle", wallet]`                | Oracle Aggregator | Wallet           | All modules       |
| **NAVOracle**            | `[b"nav-oracle", mint]`                  | Oracle Aggregator | Module 2 mint    | **Module 2 only** |
| **ClassificationOracle** | `[b"classification-oracle", mint]`       | Oracle Aggregator | Module 3 mint    | **Module 3 only** |
| Pool                     | `[b"pool", mint]`                        | AMM               | ST22 mint        | All modules       |
| FeeConfig                | `[b"fee-config"]`                        | AMM               | Global singleton | All modules       |
| GlobalPool               | `[b"global-pool"]`                       | Liquidity Pool    | Global singleton | All modules       |
| Proposal                 | `[b"proposal", id]`                      | Governance        | Proposal         | All modules       |

The PDA derivations are deterministic — auditors and integrators can compute the address of any account from the published seeds and the program ID. Module-specific PDAs (NAVOracle, ClassificationOracle) exist only for the relevant module's mints; attempting to derive them for a Module 1 mint, for example, returns a valid PDA address but no initialized account.

***

### 8. Event Registry (All Programs)

Every successful operation emits a structured event. Events are written to the Solana ledger and are queryable through standard Solana RPC providers. Cross-module events are emitted regardless of mint module; module-specific events are emitted only for the relevant module's mints.

#### 8.1 Transfer Hook Events

| Event                   | Emission Trigger                 | Module Scope                                                                                |
| ----------------------- | -------------------------------- | ------------------------------------------------------------------------------------------- |
| TransferValidated       | Every successful ST22 transfer   | All modules                                                                                 |
| CircuitBreakerTriggered | Any of CB-20 through CB-23 fires | All modules                                                                                 |
| RegulatoryFreezeEvent   | Control 42 activated or lifted   | All modules; Module 3 federal-action freezes use this event with `source: "federal_action"` |
| HoldingPeriodUnlocked   | Holding period elapses           | All modules                                                                                 |

#### 8.2 AMM Events

| Event           | Emission Trigger | Module Scope                     |
| --------------- | ---------------- | -------------------------------- |
| SwapExecuted    | Successful swap  | All modules — same fee breakdown |
| PoolInitialized | Pool creation    | All modules                      |

#### 8.3 Oracle Aggregator Events

| Event                           | Emission Trigger                                           | Module Scope      |
| ------------------------------- | ---------------------------------------------------------- | ----------------- |
| CustodyAttestationUpdated       | Successful custody oracle update                           | All modules       |
| CustodyDiscrepancyDetected      | balance < supply                                           | All modules       |
| OFACListRefreshed               | OFAC oracle update                                         | All modules       |
| **NAVOracleUpdated**            | Module 2 appraisal received                                | **Module 2 only** |
| **ClassificationOracleUpdated** | Routine classification refresh                             | **Module 3 only** |
| **FederalActionDetected**       | Module 3 federal-action P0 incident                        | **Module 3 only** |
| **FederalActionFreezeApplied**  | Module 3 Control 42 freeze applied via Classification path | **Module 3 only** |

#### 8.4 Liquidity Pool Events

| Event                 | Emission Trigger                | Module Scope                        |
| --------------------- | ------------------------------- | ----------------------------------- |
| GlobalPoolInitialized | One-time at platform deployment | All modules — single shared pool    |
| FeeDeposited          | Every fee deposit from AMM      | All modules — same allocation logic |

#### 8.5 Governance Events

| Event            | Emission Trigger                 | Module Scope |
| ---------------- | -------------------------------- | ------------ |
| ProposalCreated  | Proposal submitted               | All modules  |
| VoteCast         | Vote recorded                    | All modules  |
| ProposalExecuted | After timelock and threshold met | All modules  |

***

### 9. State Machines

#### 9.1 ST22 Token Lifecycle

The lifecycle structure is identical across modules. The asset class deposited into custody and the on-chain mint creation steps are the same; only the asset identifier and module-specific oracle initialization differ.

```
                        ┌─────────────────────┐
                        │  Board Resolution    │
                        │  (per-module charter)│
                        └────────┬─────────────┘
                                 │
                        ┌────────▼─────────────┐
                        │  Empire Custody      │
                        │  Deposit             │
                        │  Module 1: Common B  │
                        │  Module 2: SAE equity│
                        │  Module 3: BAE equity│
                        └────────┬─────────────┘
                                 │
                        ┌────────▼──────────┐
                        │  ST22 Mint Created │
                        │  + Transfer Hook   │
                        │  (IRREVERSIBLE)    │
                        └────────┬──────────┘
                                 │
                ┌────────────────▼──────────────────┐
                │  Module-specific oracle init:     │
                │   Module 1: CustodyOracle         │
                │   Module 2: + NAVOracle           │
                │   Module 3: + ClassificationOracle│
                └────────────────┬──────────────────┘
                                 │
                ┌────────────────▼────────────────┐
                │  Reg D / Reg S / Reg CF Offering │
                │  Empire KYC/KYB → Stablecoin     │
                │  settlement → Token delivery     │
                └────────────────┬────────────────┘
                                 │
                        ┌────────▼──────────┐
                        │  HOLDING PERIOD    │
                        │  Reg D: 6 mo       │
                        │  Reg S: 12 mo      │
                        │  Reg CF: 12 mo     │
                        │  (Control HP-24)   │
                        └────────┬──────────┘
                                 │ Timer elapses
                        ┌────────▼──────────┐
                        │  TRADEABLE         │
                        │  Secondary on CEDEX│
                        │  42 controls/trade │
                        └───────────────────┘
```

#### 9.2 CEDEX Order Lifecycle

```
PLACED ──► PRE-FLIGHT COMPLIANCE (2-3s)
              │
              ├─ ANY control fails → REJECTED (Error 6xxx)
              │   Module 1: standard 6 pre-flight checks
              │   Module 2: + NAV-deviation pre-flight check
              │   Module 3: + Classification freshness + federal-action checks
              │
              ▼
         VALIDATED ──► ON-CHAIN EXECUTION (400-600ms)
              │
              ├─ Slippage exceeded → REVERTED (7002)
              ├─ Insufficient liquidity → REVERTED (7001)
              │
              ▼
         FILLED ──► FEE DISTRIBUTION
              │        ├─ 0.44% → Global Pool (LOCKED)
              │        ├─ 2.00% → Issuer Treasury
              │        ├─ 1.50% → GROO Staking Pool
              │        └─ 1.06% → Protocol Operations
              │
              ▼
         SETTLED ──► AUDIT TRAIL EMITTED
```

#### 9.3 Module 2 NAV-Deviation Breaker Lifecycle

```
TRADING ──► NAV ORACLE UPDATE (per reappraisal cycle)
              │
              ├─ On-chain price within nav_deviation_max_bps → CONTINUE
              │
              ▼
         DEVIATION DETECTED ──► MINT PAUSED (per-mint, not platform-wide)
              │
              ▼
         AWAITING NEW APPRAISAL
              │
              ├─ Fresh appraisal restores price within bounds → RESUME
              ├─ Governance adjusts deviation threshold      → RESUME
              │
              ▼
         TRADING (resumed)
```

#### 9.4 Module 3 Federal-Action Freeze Lifecycle

```
NORMAL OPERATION ──► CLASSIFICATION ORACLE (24h cache)
              │
              ▼
         FEDERAL ACTION DETECTED (P0 incident)
              │
              ├─ Legal Counsel + 3-of-5 multi-sig → CONTROL 42 FREEZE
              │
              ▼
         FROZEN ──► No transfers; mint paused on AMM
              │
              ▼
         AWAITING FEDERAL-ACTION RESOLUTION
              │
              ├─ Action expires / rescinded / variance / exemption
              │
              ▼
         FREEZE LIFTED (Legal Counsel + 3-of-5)
              │
              ▼
         TRADING (resumed)
```

***

### 10. Upgrade Authority Model

| Program           | Authority Type         | Signers                    | Timelock | Module Scope                                 |
| ----------------- | ---------------------- | -------------------------- | -------- | -------------------------------------------- |
| Transfer Hook     | 5-of-9 multi-signature | Geographically distributed | 24 hours | All modules — single hook serves all         |
| AMM               | 5-of-9 multi-signature | Geographically distributed | 24 hours | All modules                                  |
| Liquidity Pool    | **None — immutable**   | —                          | —        | All modules — same immutable program         |
| Governance        | 3-of-5 multi-signature | —                          | 48 hours | All modules                                  |
| Oracle Aggregator | 5-of-9 multi-signature | Geographically distributed | 24 hours | All modules — module-specific oracles within |

#### 10.1 Transfer Hook Upgrade Procedure

1. A governance participant creates a Program Upgrade proposal.
2. Voting period is at least 48 hours.
3. 66.67% supermajority is required for passage.
4. The new bytecode hash must match an audited release.
5. Certora formal verification must pass on the new bytecode — all six invariants verified.
6. 24-hour timelock begins.
7. During the timelock, 2-of-5 of the parameter-authority multi-signature can cancel.
8. The 5-of-9 upgrade-authority multi-signature executes the BPF upgrade instruction after timelock expiry.
9. **Transfer Hook controls cannot be weakened.** The upgrade can only adjust parameters within hard-coded bounds, fix bugs, or extend functionality. Removing any of the 42 controls — or weakening any module-aware extension — would fail Certora invariant E.4 and the upgrade would be rejected at the formal-verification step.

#### 10.2 What No Upgrade Can Do

Even with full multi-signature authority and supermajority governance support, no upgrade can:

* Remove any of the 42 Transfer Hook controls (Certora invariant E.4 verification would fail). This applies to module-aware variants too — removing the Module 2 NAV-deviation check or the Module 3 federal-action freeze coordination would also fail E.4.
* Reduce a holding period below the statutory minimum (hard-coded constants are outside parameter space). Same Reg D / Reg S / Reg CF constants apply across all modules.
* Add a withdrawal function to the Liquidity Pool (the Liquidity Pool program is permanently immutable). Same pool serves all modules.
* Remove the Transfer Hook from existing mints (SPL Token-2022 standard makes hook attachment permanent). Applies to Module 1, 2, and 3 mints alike.
* Bypass the multi-signature requirement (multi-signature is enforced at the Solana program level).

***

### 11. Cross-Program Invocation Map

```
Token-2022 ───CPI──► Transfer Hook
                         │
                         ├──reads──► Oracle Aggregator
                         │           Module 1 reads:  CustodyOracle, OFACOracle, AMLOracle
                         │           Module 2 reads:  + NAVOracle
                         │           Module 3 reads:  + ClassificationOracle
                         │
                         └──emits──► TransferValidated event

CEDEX Backend ──tx──► AMM
                         │
                         ├──CPI──► Token-2022 ───CPI──► Transfer Hook (42 controls)
                         │                              (module-aware reads as above)
                         │
                         ├──CPI──► Liquidity Pool (deposit_fee: 0.44%)
                         │
                         └──emits──► SwapExecuted event

Empire Relay ──tx──► Oracle Aggregator (custody attestation)
                         │
                         ├──verify──► Ed25519 precompile
                         │
                         └──emits──► CustodyAttestationUpdated /
                                      CustodyDiscrepancyDetected
                                      (all modules — same path)

NAV Relay ──tx──► Oracle Aggregator (Module 2 appraisal)
                         │
                         ├──verify──► appraiser signature
                         │
                         └──emits──► NAVOracleUpdated

Classification Relay ──tx──► Oracle Aggregator (Module 3 USGS/DOE update)
                         │
                         └──emits──► ClassificationOracleUpdated
                                      FederalActionDetected (P0 path)
                                      FederalActionFreezeApplied (post Control 42)

Governance ──tx──► Governance
                         │
                         └──CPI──► target program (parameter update or BPF upgrade)
                                   (parameter target may be cross-module
                                    or module-specific)
```

The CPI map is deliberately constrained. The Liquidity Pool's `deposit_fee` instruction can only be called by the AMM program PDA. The Custody Oracle update can only be submitted by the registered Empire relay authority. The NAV Oracle update can only be submitted by the registered NAV relay authority with verified appraiser signatures. The Classification Oracle update can only be submitted by the registered Classification relay authority. Every cross-program path is verified by the calling program's PDA authority — there is no path for an arbitrary signer to invoke a privileged operation.

***

### 12. Deployment Verification

After deployment, every program is verified through the procedure documented in the Deployment Guide §10. Verification confirms:

| Verification                                                       | Mechanism                                                            | Module Scope       |
| ------------------------------------------------------------------ | -------------------------------------------------------------------- | ------------------ |
| Transfer Hook attached to every ST22 mint                          | Mint extension query — Hook program ID matches                       | All modules        |
| All five programs deployed                                         | Solana program-show on each program ID                               | All modules        |
| Upgrade authorities correct                                        | Each program's authority matches the expected multi-signature        | All modules        |
| Liquidity Pool program immutable                                   | Pool program upgrade authority is `None`                             | All modules        |
| LP burned at Global Pool initialization                            | LP mint supply is zero; LP mint authority is `None`                  | All modules        |
| Custody Oracle updating                                            | Attestation slot within 1 of current Solana slot                     | All modules        |
| **Module 1 EDGAR pipeline operational**                            | Last RSS poll within 60 seconds; last EFTS batch within 36 hours     | **Module 1 only**  |
| **Module 2 NAV Oracle initialized (per Module 2 mint)**            | NAV oracle has valid initial appraisal                               | **Module 2 only**  |
| **Module 3 Classification Oracle initialized (per Module 3 mint)** | Classification oracle has valid USGS/DOE classification              | **Module 3 only**  |
| **Module 3 federal-action monitoring operational**                 | Classification relay polling federal sources within 5-minute cadence | **Module 3 only**  |
| SecurityConfig parameters within governance bounds                 | Per-mint parameter query against expected ranges                     | All modules        |
| Module-specific SecurityConfig fields populated                    | Module 2 NAV bounds, Module 3 classification age                     | Module 2, Module 3 |

Any verification failure halts the deployment until resolved.

***

### 13. Module-Aware Program Behavior

The five programs serve all three modules identically at the structural level. Module-specific behavior arises from three module-aware components: Module-specific oracles (NAVOracle for Module 2; ClassificationOracle for Module 3), module-specific SecurityConfig fields, and module-aware Transfer Hook checks. This section consolidates the module-specific behavior surface — the same surface that has been threaded through each program section above.

#### 13.1 Module 1 — Equities

**Programs.** All five programs operate normally. No additional oracles or PDAs.

**Distinguishing properties.** Standard ST22 mint with Transfer Hook, AMM pool, fee distribution to Global Pool. Module 1 issuances use the EDGAR pipeline (an off-chain feed read by the Layer 9 IDOS off-chain compliance system) for issuer-disclosure intelligence; this does not change on-chain program behavior.

**Asset identifier.** CUSIP.

**Highest expected transaction volume** of the three modules — correlates with the broadest investor pool.

#### 13.2 Module 2 — Real Estate

**Additional oracle.** NAV Oracle (per mint).

**Distinguishing properties.** Each Module 2 ST22 mint corresponds to a single-asset entity holding the underlying real-property asset. The NAV Oracle holds the most recent appraised NAV from a licensed independent appraiser. The Transfer Hook enforces a NAV-deviation circuit breaker that pauses the mint on the AMM when the on-chain price deviates from the NAV by more than `nav_deviation_max_bps`.

**Asset identifier.** Property identifier.

**Module-specific SecurityConfig parameters.** `nav_deviation_max_bps`, `nav_reappraisal_max_age_secs`, `nav_circuit_breaker_enabled`.

**Module-specific events.** `NAVOracleUpdated`.

**Lower expected transaction volume** than Module 1, but higher per-transaction notional value.

#### 13.3 Module 3 — CORECM

**Additional oracle.** Classification Oracle (per mint).

**Distinguishing properties.** Each Module 3 ST22 mint corresponds to a basin-asset entity holding the mineral basin or mining concession. The Classification Oracle holds the most recent USGS Critical Minerals List classification, DOE Critical Materials Strategy status, and federal-action status from federal feeds. The Transfer Hook applies enhanced compliance review when classification staleness exceeds the threshold and supports automatic Control 42 federal-action freeze in coordination with Empire Stock Transfer.

**Asset identifier.** Basin identifier.

**Module-specific SecurityConfig parameters.** `classification_max_age_secs`, `federal_action_freeze_enabled`.

**Module-specific events.** `ClassificationOracleUpdated`, `FederalActionDetected`, `FederalActionFreezeApplied`.

**Lowest expected transaction volume** but highest regulatory sensitivity. Federal actions issued under Executive Orders, Section 232 of the Trade Expansion Act of 1962, Defense Production Act Title III, the Inflation Reduction Act critical-minerals provisions, Executive Order 14017, or the Energy Act of 2020 are detected by the platform's federal-action monitoring and trigger automatic P0 response under the Incident Response Playbook §13.

#### 13.4 Cross-Module Program Properties

The following properties are identical across all three modules at the program level:

* The Transfer Hook program executes the same 42 controls (with module-aware oracle reads in CB-21 for Module 2 and in CV-04/REG-42 for Module 3).
* The AMM program uses the same constant-product invariant and fee distribution.
* The Liquidity Pool aggregates fees from all module activity into the same Global Pool.
* The Governance program manages parameter and upgrade proposals identically — module-specific parameters follow the same governance discipline as cross-module parameters.
* The Oracle Aggregator manages the cross-module oracles (custody, OFAC, AML, TWAP) for every mint.
* Multi-signature thresholds and timelock durations apply uniformly.
* Empire Stock Transfer is the sole §17A custodian and sole onboarding authority for every issuance.
* The 1:1 backing invariant (Certora E.2) applies to every ST22 mint regardless of module.
* The Global Pool non-extractability invariant (Certora E.3) protects every module's fee accumulation.
* Holding periods (Reg D 6mo, Reg S 12mo, Reg CF 12mo) apply identically across modules.

***

### Related Documentation

* **Solana Blockchain Foundation** — Why Solana, Token-2022, Transfer Hook, module-specific foundations
* **Architecture Decisions** — ADR-001 through ADR-012 with full alternatives analysis
* **Security Model** — Threat model, key management, formal verification, module-specific threat surfaces
* **Infrastructure Overview** — Cloud architecture, environment separation, blockchain infrastructure
* **Network Configuration** — Program addresses, RPC endpoints, oracle PDAs, multi-signature addresses, production parameters
* **Deployment Guide** — Build, deploy, verify, upgrade, rollback procedures including module-specific initialization
* **Incident Response Playbook** — P0 through P3 runbooks; Module 3 federal-action freeze runbook
* **Empire Stock Transfer Integration** — Custody architecture, Ed25519 attestation, MSF, KYC/KYB/AML/OFAC, conflict-of-interest disclosure, module-aware custody coverage
* **Compliance Integration Guide** — Regulatory mapping, Category 1 Model B requirements, BSA/AML, OFAC, holding periods, module-specific compliance, federal-action coordination
* **Oracle Integration Guide** — Custody, OFAC, AML, TWAP, EDGAR (Module 1), NAV (Module 2), Classification (Module 3) relay architecture
* **Transfer Hook Reference** — Standalone reference for the 42 controls
* **Whitepaper Section 3** — Transfer Hook architecture and beta validation
* **Whitepaper Section 5** — AMM math and CEDEX specification

***

*RWA Tokens · Smart Contract Reference · Groovy Company, Inc.*


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://bitbook.rwatokens.net/cedex-and-trading/cedex-and-trading/smart-contract-reference.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.