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.

Program Registry
Transfer Hook Program
AMM Program
Liquidity Pool Program
Governance Program
Oracle Aggregator Program
PDA Registry (All Programs)
Event Registry (All Programs)
State Machines
Upgrade Authority Model
Cross-Program Invocation Map
Deployment Verification
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%)

All modules; Module 2 may use up to 9.99%

Circuit breaker threshold

1000 (10%)

5000 (50%)

3000 (30%)

All modules

Circuit breaker cooldown

3600 (1h)

259200 (72h)

86400 (24h)

All modules

Price impact maximum (vs TWAP)

100 (1%)

500 (5%)

200 (2%)

All modules

TWAP window

900 (15m)

3600 (1h)

1800 (30m)

All modules

TWAP minimum observations

—

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 (typically 2200 = 22%)

Module 2 only

nav_reappraisal_max_age_secs

Per mint

Per mint (per tripartite cadence)

Module 2 only

classification_max_age_secs

Per mint

Per mint (typically 86400 = 24h)

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

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:

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

Creates the GlobalPool state account (PDA: [b"global-pool"]).
Creates the SOL reserve vault.
Creates the LP mint.
Burns all LP tokens by setting the LP mint authority to None.
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

A governance participant creates a proposal specifying the target parameter, the new value, and a description.
The voting period opens for at least 48 hours.
Vote tallies are recorded on chain.
If passed (simple majority), the proposal enters a 48-hour timelock.
During the timelock window, 2-of-5 of the parameter-authority multi-signature can cancel the proposal.
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:

The voting threshold is 66.67% supermajority, not simple majority.
The new program bytecode hash must be attested as matching an audited release.
Certora formal verification must pass on the new bytecode before execution.
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:

Ed25519 signature verification via the Solana Ed25519 precompile against Empire's registered public key.
Slot freshness verification — the slot in the payload must be the current slot or one slot prior.
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.
State update — the CustodyOracle account state is updated.
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

A governance participant creates a Program Upgrade proposal.
Voting period is at least 48 hours.
66.67% supermajority is required for passage.
The new bytecode hash must match an audited release.
Certora formal verification must pass on the new bytecode — all six invariants verified.
24-hour timelock begins.
During the timelock, 2-of-5 of the parameter-authority multi-signature can cancel.
The 5-of-9 upgrade-authority multi-signature executes the BPF upgrade instruction after timelock expiry.
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.

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.

PreviousOracle Integration Guide

Last updated 1 month ago

Was this helpful?

Good evening