Oracle Integration Guide

Oracle Integration Guide

Seven Oracle Categories · Ed25519 Attestation · Fail-Safe Architecture · Relay Operations · Module-Aware

Technical reference for oracle operators, the Empire Stock Transfer technical team, compliance provider integrators (Chainalysis, TRM Labs), and infrastructure engineers responsible for maintaining the real-time data feeds that drive every Transfer Hook compliance decision. The platform's oracle architecture serves all three production modules: Equities (Module 1), Real Estate (Module 2), and CORECM — Carbon Ore, Rare Earth, and Critical Minerals (Module 3). Module-aware oracles (NAV for Module 2; Classification for Module 3) are documented alongside cross-module oracles (Custody, OFAC, AML, TWAP, EDGAR).

---

Table of Contents

1. ​Architecture Overview​

2. ​Custody Verification Oracle (Empire)​

3. ​OFAC / SDN Sanctions Oracle​

4. ​AML Risk Scoring Oracle​

5. ​TWAP and Price Discovery Oracle (Pyth)​

6. ​SEC EDGAR Intelligence Oracle​

7. ​NAV Oracle — Module 2​

8. ​Classification Oracle — Module 3​

9. ​On-Chain Account Schemas​

10. ​Relay Service Architecture​

11. ​Fail-Safe Cascade​

12. ​Health Monitoring​

13. ​Failure Injection Testing​

14. ​Key Rotation​

15. ​Troubleshooting

---

1. Architecture Overview

1.1 Role in the Stack

The Oracle Network is the real-time data backbone feeding the Transfer Hook's 42 compliance controls. Oracle data flows directly to the Transfer Hook through the Oracle Aggregator program — it does not pass through the platform's application stack. An oracle failure is a compliance failure.

                     EXTERNAL DATA SOURCES
   ┌────────┬────────┬────────┬────────┬────────┬────────┬────────┐
   │ Empire │Treasury│Chainalys│ Pyth  │  SEC   │ Lic'd  │ USGS+  │
   │ Stock  │ OFAC   │ + TRM  │ Net   │ EDGAR  │ Apprai-│ DOE +  │
   │ Trans- │  API   │ Labs   │       │  RSS   │  ser   │ Federal│
   │  fer   │        │        │       │        │ Network│Register│
   └────┬───┴────┬───┴────┬───┴────┬──┴────┬───┴────┬───┴────┬───┘
        │        │        │        │       │        │        │
   ┌────▼───┬────▼───┬────▼───┬────▼──┬────▼───┬────▼───┬────▼───┐
   │Custody │ OFAC   │  AML   │ TWAP  │ EDGAR  │  NAV   │Classif-│
   │ Relay  │Indexer │ Bridge │Consum-│Pipeline│ Relay  │ication │
   │        │        │        │  er   │        │        │ Relay  │
   └────┬───┴────┬───┴────┬───┴────┬──┴────┬───┴────┬───┴────┬───┘
        │        │        │        │       │        │        │
   ORACLE AGGREGATOR PROGRAM (on chain)
        │
   ┌────▼──────────────────────────────────────────────────────────┐
   │ TRANSFER HOOK (42 controls)                                   │
   │   Controls CV-01 to CV-06: read CustodyOracle                 │
   │   Controls SC-30 to SC-34: read OFACOracle                    │
   │   Control IV-09:           read AMLOracle                     │
   │   Control HP-24:           read HoldingPeriodAccount          │
   │   Control CB-21:           read TWAP from SecurityConfig      │
   │                            (+ NAVOracle for Module 2 mints)   │
   │   Control CV-04 / IV-08:   read EDGAR issuer eligibility +    │
   │                            ClassificationOracle for Module 3  │
   │   Control REG-42:          activated on Module 3 federal      │
   │                            actions; auto-coordination via     │
   │                            ClassificationOracle               │
   └───────────────────────────────────────────────────────────────┘

1.2 Seven Oracle Categories

Oracle	Transfer Hook Controls	Source	Update Cadence	Module Scope	Fail-Safe
Custody	CV-01 to CV-06	Empire Ed25519 API	Every block (~400ms)	All modules	REJECT ALL TRANSFERS
OFAC / SDN	SC-30 to SC-34	U.S. Treasury OFAC	Hourly + emergency push	All modules	Cache <24h; halt >48h
AML	IV-09	Chainalysis KYT + TRM Labs	Per-transfer (cached 6h)	All modules	Cache <6h
TWAP / Price	CB-20, CB-21, CB-22, CB-23	Pyth Network	Sub-second	All modules	Last confirmed price
EDGAR	IV-08 + Layer 9 IDOS	SEC EDGAR RSS + EFTS	Real-time + daily batch	Module 1 (Equities)	Last batch
NAV	CB-21 (extension)	Independent licensed appraisers	Per reappraisal cycle	Module 2 (Real Estate)	Mint paused on staleness
Classification	CV-04 (extension) + REG-42	USGS + DOE + Federal Register	Daily + emergency on EO update	Module 3 (CORECM)	Enhanced review on staleness; auto-freeze on federal action

1.3 Asymmetric Fail-Safe Principle

Not all oracle failures are equal. The custody oracle has the strictest fail-safe because a custody discrepancy threatens the 1:1 backing guarantee — the foundational property of every ST22 token. A stale AML score is manageable risk. A wrong custody count is existential.

Oracle Failure	Risk Level	Response
Custody stale > 1 slot	Catastrophic	Reject ALL transfers (Error 6001 / 6002)
OFAC stale > 24h	High	Use cached list
OFAC stale > 48h	Critical	Halt ALL transfers
AML stale > 6h	Medium	Mandatory on-demand refresh
TWAP unavailable > 5 min	Medium	Disable circuit breaker
EDGAR batch delayed	Low	Continue with last batch, flag stale
NAV stale beyond nav_reappraisal_max_age_secs (Module 2)	High	Pause affected Module 2 mint until fresh appraisal
NAV deviation exceeds nav_deviation_max_bps (Module 2)	High	Pause affected Module 2 mint until fresh appraisal restores price
Classification stale beyond classification_max_age_secs (Module 3)	Medium	Continue with enhanced review; flag operations
Federal action detected (Module 3)	Catastrophic	Auto-coordinate Control 42 freeze (Legal Counsel + 3-of-5 within 60-min SLA)

---

2. Custody Verification Oracle (Empire)

The most critical oracle. Zero-tolerance. Zero-discrepancy. Hard fail-safe. Operates identically across all three modules.

2.1 Data Source

Empire Stock Transfer — SEC §17A-registered transfer agent and qualified custodian. Empire holds the authoritative record of the underlying asset for each ST22 issuer:

• Module 1. Common Class B shares of the issuing entity.

• Module 2. Equity in the single-asset entity that owns the underlying real-property asset.

• Module 3. Equity in the basin-asset entity that owns the underlying mineral basin or mining concession.

The custody oracle treats all three uniformly — it tracks the custodied balance and the on-chain token supply. The asset class is recorded in the SecurityConfig's asset_identifier field at mint creation; the oracle does not need to discriminate between modules.

2.2 Attestation Payload

Empire signs a 64-byte payload with Ed25519 on every Solana block. The signed payload contains:

Field	Size	Description
mint	32 bytes	ST22 mint address
custodied_balance	8 bytes	Empire-custodied unit count
token_supply	8 bytes	On-chain circulating supply
slot	8 bytes	Current Solana slot
timestamp	8 bytes	Unix timestamp

Total signed payload: 64 bytes. Signed with Empire's Ed25519 private key (HSM-backed). Verified with the Solana Ed25519 precompile.

2.3 Relay Service

The custody relay service bridges Empire's API to the on-chain CustodyOracle account. The service polls per Solana slot (~400ms cadence), fetches the latest attestation from Empire, verifies the Ed25519 signature locally as a pre-check, and submits the on-chain update.

interface EmpireCustodyResponse {
  mint:               string;
  custodied_balance:  number;
  token_supply:       number;
  signature:          string;    // Base58-encoded Ed25519 signature
  timestamp:          number;
}

class CustodyRelay {
  private readonly empireApi:    string;
  private readonly connection:   Connection;
  private readonly relayKeypair: Keypair;

  async run(): Promise<void> {
    // Poll every Solana block (~400ms)
    this.connection.onSlotChange(async (slotInfo) => {
      for (const mint of this.activeMints) {
        try {
          const attestation = await this.fetchEmpireAttestation(mint);
          this.verifySignature(attestation);
          await this.updateCustodyOracle(mint, attestation);

          if (attestation.custodied_balance !== attestation.token_supply) {
            this.triggerP0Alert(mint, attestation);
          }
        } catch (error) {
          this.handleRelayError(mint, error);
        }
      }
    });
  }

  private async updateCustodyOracle(
    mint: PublicKey,
    attestation: EmpireCustodyResponse,
  ): Promise<string> {
    return await this.oracleProgram.methods
      .updateCustodyOracle(/* attestation fields */)
      .accounts({
        custodyOracle:   this.deriveCustodyOraclePda(mint),
        mint,
        relayAuthority:  this.relayKeypair.publicKey,
        clock:           SYSVAR_CLOCK_PUBKEY,
        ed25519Program:  Ed25519Program.programId,
      })
      .signers([this.relayKeypair])
      .rpc();
  }
}

2.4 On-Chain Verification Flow

When the Transfer Hook reads the CustodyOracle, it executes four sequential checks:

1. Ed25519 signature is valid (is_valid flag is true). If false, return Error 6002 (CustodyOracleUnavailable).

2. Attestation is fresh — slot age must be at most 1 (i.e., current slot or one slot prior). If older, return Error 6002.

3. Token supply is less than or equal to the custodied balance (zero-tolerance ratio). If supply exceeds custody, return Error 6001 (CustodyDiscrepancy).

4. No active discrepancy is recorded. If discrepancy_detected is true, return Error 6038 (CustodyDiscrepancyHalt).

All four checks must pass for any transfer to proceed.

2.5 Discrepancy Response Procedure

CustodyOracle detects: custodied_balance ≠ token_supply
  │
  ├─ IMMEDIATE: Error 6001 on ALL subsequent transfers (affected mint)
  ├─ IMMEDIATE: Circuit breaker activates
  ├─ IMMEDIATE: CustodyDiscrepancyDetected event emitted
  │
  ├─ 0-15 min: P0 dual notification
  │    ├─ Platform operations: PagerDuty alert
  │    └─ Empire compliance: dedicated hotline
  │
  ├─ Investigation:
  │    ├─ Empire confirms actual unit count
  │    ├─ Platform verifies on-chain supply
  │    └─ Root cause identified
  │
  └─ Resolution:
       ├─ 2-of-3 oracle consensus confirms count matches
       │    ├─ Primary: Empire Ed25519
       │    ├─ Secondary: platform verification node
       │    └─ Tertiary: quarterly audit record
       ├─ discrepancy_detected set to false
       └─ Trading resumes

2.6 Specifications

Parameter	Value
Update cadence	Every Solana block (~400ms)
Signature algorithm	Ed25519 (NIST-standardized)
Verification	Solana native Ed25519 precompile (~120 CU)
Staleness threshold	1 slot (> 1 slot = Error 6002)
Discrepancy threshold	Zero tolerance (≥ 1 unit = Error 6001)
Latency SLA	< 200ms from custody change to oracle update
Fail-safe	REJECT ALL TRANSFERS — hard halt
Production record	Zero discrepancy events across three beta issuers, $7M+ processed

---

3. OFAC / SDN Sanctions Oracle

3.1 Data Source

U.S. Treasury Department Office of Foreign Assets Control (OFAC) SDN list via official API. Operates identically across all three modules.

3.2 Three-Layer Screening

Layer	Method	Purpose	Example
Layer 1: Exact Address	Direct Solana wallet address match against known SDN addresses	Catches directly sanctioned wallets	Wallet ABC123 matches SDN entry
Layer 2: Fuzzy Entity	Entity name and alias matching via Chainalysis KYT entity resolution	Catches slight name variations in entity investors	"ACME Corp" matches "ACME Corporation LLC"
Layer 3: 2-Hop Clustering	Transaction graph analysis — wallets within 2 degrees of SDN entities	Catches proxy wallet strategies	Wallet funded by wallet funded by SDN address

3.3 Indexer Service

The OFAC indexer service runs scheduled hourly refreshes plus an emergency-push listener for Treasury webhook events. On each refresh, the service fetches the current SDN list, computes a SHA-256 hash, compares with the previous hash, indexes new entries if changed, and updates the on-chain OFACOracle account with the hash and entry count.

class OFACIndexer {
  private readonly ofacApiUrl       = 'https://api.treasury.gov/ofac/sdn';
  private readonly refreshIntervalMs = 3_600_000; // 1 hour
  private sdnList:  SDNEntry[] = [];
  private listHash: Buffer;

  async run(): Promise<void> {
    setInterval(() => this.refreshSDNList(), this.refreshIntervalMs);
    this.listenForEmergencyUpdates();
  }

  private async refreshSDNList(): Promise<void> {
    const response = await fetch(this.ofacApiUrl);
    const entries: SDNEntry[] = await response.json();
    const hash = crypto.createHash('sha256')
      .update(JSON.stringify(entries))
      .digest();

    if (hash.equals(this.listHash)) return;

    this.sdnList  = entries;
    this.listHash = hash;
    await this.updateOFACOracle(hash, entries.length);
    await this.rescreenActiveWallets();
  }
}

The actual SDN entries are tracked off chain — Solana account-size limits make on-chain storage of the full SDN list infeasible. The on-chain hash provides cryptographic commitment to the indexer's view of the list.

3.4 Transfer Hook Integration

Controls SC-30 through SC-34 read the OFAC oracle on every transfer. The hook performs three checks: oracle freshness (halt if older than halt_threshold), exact address match against the indexed SDN set, and continuous re-screening on every transfer (Control SC-33). Sender match returns Error 6003 (SenderSanctioned); receiver match returns Error 6004 (ReceiverSanctioned); oracle stale beyond threshold returns Error 6005 (OfacOracleStale).

3.5 Staleness Thresholds

Age	Status	Behavior
0–24 hours	Fresh	Normal operation — SDN check on every transfer
24–48 hours	Stale (cached)	Continue with cached list. P2 alert raised.
> 48 hours	Critical	HALT ALL TRANSFERS — Error 6005 on every transfer until refresh

3.6 False-Positive Handling

If a legitimate wallet is flagged: the transfer is rejected with Error 6003 or 6004; the compliance team is notified automatically (5-minute SLA); Empire Stock Transfer is notified for investor record annotation; manual review determines whether the flag is accurate; if false positive, the wallet is cleared in the oracle and the investor can retry. Typical resolution: 1–4 hours.

---

4. AML Risk Scoring Oracle

4.1 Dual-Provider Architecture

Two independent blockchain-analytics providers score every wallet. Different ML models and training data reduce single-provider blind spots.

Provider	Capabilities	Integration
Chainalysis KYT	Industry standard. Widest entity coverage. Law-enforcement relationships.	REST API per-wallet query
TRM Labs	200+ behavioral features. Strong pattern detection for emerging threats.	REST API per-wallet query

4.2 Risk Disposition

Score Range	Disposition	Transfer Action	Post-Transfer
0–30	Approve	Transfer proceeds	—
31–70	Enhanced Review	Transfer proceeds but flagged	Compliance team reviews within 24h
71–100	Reject	Transfer rejected — Error 6006	Wallet blocked. Empire notified.

The higher of the two provider scores determines disposition. If Chainalysis scores 25 (approve) but TRM scores 72 (reject), the wallet is rejected.

4.3 Bridge Service

The AML bridge service queries both providers in parallel, aggregates the higher score, determines disposition, updates the on-chain AMLOracle account, and caches the result for 6 hours.

class AMLBridge {
  private readonly chainalysisApi:  ChainalysisKYT;
  private readonly trmApi:          TRMLabs;
  private readonly cacheValidSecs = 21_600; // 6 hours

  async scoreWallet(wallet: PublicKey): Promise<AMLScore> {
    const cached = await this.getCache(wallet);
    if (cached && !this.isStale(cached)) return cached;

    const [chainalysisScore, trmScore] = await Promise.all([
      this.chainalysisApi.getScore(wallet.toBase58()),
      this.trmApi.getScore(wallet.toBase58()),
    ]);

    const aggregateScore = Math.max(
      chainalysisScore.risk_score,
      trmScore.risk_score,
    );

    const disposition =
      aggregateScore <= 30 ? 'approve' :
      aggregateScore <= 70 ? 'review'  :
      'reject';

    await this.updateAMLOracle(wallet, aggregateScore, disposition);
    await this.setCache(wallet, aggregateScore, disposition);

    return { score: aggregateScore, disposition };
  }
}

4.4 Cache Management

Scenario	Behavior
Cached score < 6 hours old	Use cached. No API call.
Cached score 6–12 hours old	Mandatory refresh before transfer proceeds.
No cached score (new wallet)	On-demand fresh query. Both providers.
Provider API timeout (> 2s)	Use partner provider score only. Log degradation.
Both providers timeout	Use last cached score if < 12h. Reject if no score exists.

4.5 Specifications

Parameter	Value
Providers	Chainalysis KYT + TRM Labs
Aggregation	Higher score determines disposition
Approve threshold	0–30
Review threshold	31–70
Reject threshold	71–100 (Error 6006)
Cache validity	6 hours
Refresh cadence	Every 6h for active wallets; on-demand for new wallets
Latency SLA	< 400ms (cached), < 2s (fresh query)
Fail-safe	Cache < 6h; reject if no score available
Module 3 enhancement	Beneficial-ownership depth required for entity investors

---

5. TWAP and Price Discovery Oracle (Pyth)

5.1 Data Source

Pyth Network — pull-based high-frequency price oracle. First-party data publishers (institutional market makers, trading firms) publish price attestations directly on chain.

5.2 TWAP Calculation

Control CB-21 enforces maximum 2% price impact per transfer against a rolling TWAP. The TWAP calculation uses time-weighted observations across a 30-minute window with a minimum of 60 observations.

The TWAP state is held inside the SecurityConfig per mint. Observation list, window seconds, minimum observations, and outlier-rejection sigma are all read by the Transfer Hook on every transfer.

5.3 TWAP Parameters

Parameter	Default	Governance Range	Immutable?
Calculation window	30 minutes	15–60 min	No
Minimum observations	60	—	Yes
Max price impact per transfer	2% (200 bps)	1–5% (100–500 bps)	No
Outlier rejection	> 3σ from rolling median	—	Yes
Circuit-breaker reset	Automatic on TWAP normalization	—	N/A

5.4 Consumer Service

The TWAP consumer subscribes to the Pyth Network SOL-USD price feed, accumulates observations into a rolling window, prunes observations outside the window, rejects outliers using 3σ filtering against the rolling median, calculates the time-weighted TWAP, and updates the SecurityConfig's TWAP state.

class TWAPConsumer {
  private readonly pythConnection: PythConnection;
  private observations: PriceObservation[] = [];

  async run(): Promise<void> {
    this.pythConnection.onPriceChange(this.priceFeedId, (price) => {
      this.observations.push({
        price:      price.price,
        confidence: price.confidence,
        timestamp:  Date.now() / 1000,
        slot:       price.slot,
      });

      const windowStart = Date.now() / 1000 - this.windowSecs;
      this.observations = this.observations
        .filter(o => o.timestamp >= windowStart);

      const filtered = this.rejectOutliers(this.observations);

      if (filtered.length >= this.minObservations) {
        const twap = this.calculateTWAP(filtered);
        this.updateSecurityConfigTWAP(twap);
      }
    });
  }
}

5.5 Circuit-Breaker Integration

Trigger	Threshold	Response	Control
Single-trade price impact	> 2% vs TWAP	Block trade (Error 6021)	CB-21
5-minute price movement	> 10%	15-minute trading halt (Error 6005)	CB-20
TWAP unavailable	> 5 minutes	Circuit breaker disabled. P2 alert.	CB-22
Volume spike	> 100x 24h avg	Enhanced monitoring. P2 alert.	CB-22

5.6 Manipulation Resistance

Attack	Defense	Why It Fails
Single-block price manipulation	60-observation minimum across 30-min window	One manipulated observation cannot move TWAP
Sustained manipulation (30 min)	Cost of sustained manipulation across 60+ observations exceeds extractable value	Economically irrational
Outlier injection	3σ rejection excludes extreme values	Manipulated observations automatically excluded
TWAP stale attack (force disable)	Circuit breaker disabled after 5 min — trades proceed without impact limit	Attacker gains no advantage; other controls (wallet limits, volume halt) still active

5.7 Module 2 — TWAP versus NAV

For Module 2 (Real Estate) mints, the TWAP-based circuit breaker (CB-21) is supplemented by a NAV-deviation circuit breaker also classified under CB-21. Both checks must pass: the TWAP-based price-impact check and the NAV-deviation check. The NAV oracle and its deviation enforcement are documented in §7. Module 1 and Module 3 mints rely on TWAP alone for CB-21.

---

6. SEC EDGAR Intelligence Oracle

6.1 Module Scope

The EDGAR oracle is Module 1-only. It serves Equities issuers that file SEC reports via EDGAR. Module 2 (Real Estate) and Module 3 (CORECM) issuers are not SEC-reporting in the same way; their issuer-disclosure pipelines are the NAV oracle (Module 2) and the Classification oracle (Module 3) respectively.

6.2 Dual Consumer Architecture

The EDGAR oracle is unique — it feeds both the Transfer Hook (via Control IV-08 issuer eligibility) and the Layer 9 IDOS off-chain compliance system. Single pipeline, two consumers.

Consumer	Purpose
Control IV-08 (Transfer Hook)	Issuer eligibility — SEC registration current, no enforcement action, 15c2-11 compliance. Failure flags via is_eligible field on SecurityConfig.
Layer 9 IDOS	Issuer Distress and Opportunity Score — issuer-disclosure intelligence for onboarding priority and ongoing monitoring.

6.3 Data Pipeline

SEC EDGAR RSS Feed ──────────────────────────────────────────┐
  │ Real-time: new filings across ~15,000 OTC companies       │
  │ Polling interval: 60 seconds                              │
  ▼                                                           │
Deduplication + Normalization ──────────────────────┐         │
  ▲                                                 │         │
SEC EDGAR EFTS API ─────────────────────────────────┘         │
  │ Daily batch: full-text search across complete corpus      │
  │ Throughput: 1,000 CIKs per batch                          │
  ▼                                                           │
┌──────────────────────────────────────────────────────────────┘
│
├──► Control IV-08: issuer eligibility flag
│      ├─ 10-K / 10-Q current?       → allow
│      ├─ 8-K enforcement detected?  → flag for halt
│      ├─ Form D filed?              → Reg D verified
│      └─ Rule 15c2-11 status        → eligibility flag
│
└──► Layer 9 IDOS:
       ├─ NLP extraction from 8-K, 10-K, 10-Q
       ├─ Going-concern detection
       ├─ Tier degradation tracking
       └─ Capital-raise timing analysis

6.4 Filing Type Mapping

Filing	Control IV-08 (Transfer Hook)	Layer 9 IDOS	Latency
8-K	Enforcement detection → flag for halt on match	Material event → immediate IDOS update	< 60s from RSS
10-K / 10-Q	Current filing status verification	Financial-distress NLP scan	< 60s from RSS
Form D	Reg D registration verification	Capital-raise urgency scoring	< 60s from RSS
DEF 14A	SEC reporting compliance confirmation	Shareholder-count extraction	Daily batch
15c2-11	Trading eligibility (Expert Market detection)	Tier-degradation scoring	15-min polling

6.5 Pipeline Service

The EDGAR pipeline runs RSS polling every 60 seconds and a full EFTS batch daily at 02:00 UTC. RSS-detected filings are deduplicated against the cache, classified by type, processed by both consumers (Control IV-08 and Layer 9 IDOS), and update the on-chain issuer-eligibility flag where applicable.

class EDGARPipeline {
  private readonly rssUrl  = 'https://www.sec.gov/cgi-bin/browse-edgar?...';
  private readonly eftsUrl = 'https://efts.sec.gov/LATEST/search-index';

  async run(): Promise<void> {
    setInterval(() => this.pollRSS(), 60_000);
    cron.schedule('0 2 * * *', () => this.runFullBatch());
  }

  private async pollRSS(): Promise<void> {
    const filings = await this.fetchRSS();
    for (const filing of filings) {
      if (this.isMonitoredIssuer(filing.cik)) {
        await this.updateIssuerEligibility(filing);
        await this.updateIDOSScore(filing);
      }
    }
  }
}

6.6 Specifications

Parameter	Value
RSS polling interval	60 seconds
EFTS batch schedule	Daily at 02:00 UTC
EFTS throughput	1,000 CIKs per batch
Monitored universe	~15,000 OTC companies
8-K processing latency	< 60 seconds from RSS publication
Module scope	Module 1 only
Fail-safe	Continue with last batch. IDOS flagged stale. P2 alert.

---

7. NAV Oracle — Module 2

The NAV Oracle holds the most recent appraised Net Asset Value for a Module 2 (Real Estate) ST22 mint. It is the structural mechanism for tying the on-chain price of a Module 2 mint to the underlying real-property value.

7.1 Module Scope

The NAV oracle is Module 2-only. Module 1 mints have no NAV oracle (their value is determined purely by AMM trading). Module 3 mints have no NAV oracle (their value is also AMM-determined; classification status, not NAV, is the regulatory anchor).

7.2 Data Source

Independent licensed real-estate appraisers engaged under the tripartite agreement between the issuer, Groovy Company, Inc., and Empire Stock Transfer. The appraiser is selected at mint creation and rotates per the schedule defined in the issuer's tripartite. Each appraisal is signed by the appraiser using Ed25519 (HSM-backed where the appraiser's infrastructure supports it; software-backed otherwise) and submitted via the NAV relay service.

7.3 Update Cadence

NAV reappraisals follow the schedule defined in the tripartite agreement. Common schedules:

Property Type	Reappraisal Cadence	Between-Cycle Reviews
Stabilized commercial (office, multifamily)	Annual	Quarterly
Active development	Quarterly	Monthly
Distressed or special situation	Quarterly	Continuous (event-driven)

The on-chain nav_reappraisal_max_age_secs field on the NAVOracle PDA reflects the configured maximum. When the on-chain age exceeds this threshold, the affected mint is paused on the AMM until a fresh appraisal is published.

7.4 Attestation Payload

The NAV attestation is a 96-byte signed payload containing the mint, the appraised NAV in USD-pegged stablecoin units, the appraiser's identifier, the appraisal timestamp, the next-reappraisal target timestamp, and the appraiser's authority signature.

Field	Size	Description
mint	32 bytes	Module 2 ST22 mint address
appraised_nav_usd	16 bytes	u128 — appraised NAV in USD-pegged stablecoin units
appraiser_id	16 bytes	Identifier of the licensed appraiser
appraisal_timestamp	8 bytes	Unix timestamp
next_reappraisal_target	8 bytes	Unix timestamp (issuer-tripartite schedule)
signature_metadata	16 bytes	Appraiser key version, license number reference

7.5 Relay Service

The NAV relay service receives signed appraisal submissions from authorized appraisers, verifies appraiser authentication and license credentials, validates the Ed25519 signature against the appraiser's registered public key, and submits the on-chain update.

class NAVRelay {
  private readonly authorizedAppraisers: Map<string, AppraiserCredentials>;
  private readonly oracleProgram:        Program;

  async receiveAppraisal(submission: NAVSubmission): Promise<void> {
    const appraiser = this.authorizedAppraisers.get(submission.appraiser_id);
    if (!appraiser) {
      throw new Error('Unauthorized appraiser');
    }

    if (this.isLicenseExpired(appraiser, submission.appraisal_timestamp)) {
      throw new Error('Appraiser license expired at appraisal time');
    }

    const signatureValid = this.verifySignature(
      submission.payload,
      submission.signature,
      appraiser.public_key,
    );
    if (!signatureValid) {
      throw new Error('Invalid Ed25519 signature');
    }

    await this.updateNAVOracle(submission);
    this.emitNAVOracleUpdated(submission);
  }
}

7.6 Transfer Hook Integration

The Transfer Hook reads the NAV oracle during the price-impact circuit-breaker check (CB-21). For each Module 2 transfer:

1. The on-chain price is calculated from the AMM pool reserves.

2. The current NAV is read from the NAVOracle PDA.

3. The deviation (price - nav) / nav is computed in basis points.

4. If the deviation exceeds nav_deviation_max_bps, the transfer is rejected with Error 6021 (PriceImpactExceeded / NAV variant).

5. If the NAV is stale beyond nav_reappraisal_max_age_secs, the mint is paused on the AMM. New transfers are rejected with Error 6021 (NAV stale variant).

7.7 Specifications

Parameter	Value
Update cadence	Per tripartite reappraisal schedule (typically annual or quarterly)
Signature algorithm	Ed25519
Verification	Solana Ed25519 precompile against registered appraiser public key
Deviation tolerance default	22% (2200 bps) — aligned with the documented commercial-building fractionalization premium
Deviation tolerance range	Governance-set per mint
Staleness threshold default	Configured per mint via nav_reappraisal_max_age_secs
Module scope	Module 2 only
Fail-safe	Mint paused pending fresh appraisal

---

8. Classification Oracle — Module 3

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 (CORECM) ST22 mint's basin asset.

8.1 Module Scope

The Classification oracle is Module 3-only. It is the regulatory backbone for CORECM tokenization — Module 3 ST22 tokens are subject to federal-action sensitivity that does not apply to Module 1 or Module 2.

8.2 Data Sources

Source	What	Update Cadence
USGS Critical Minerals List	Mineral-classification status (rare earth, critical mineral category, etc.)	Annual list; emergency updates
DOE Critical Materials Strategy	Material-priority designation (high priority, near-critical, etc.)	Program announcements
Federal Register	Executive Orders, Section 232 proclamations, DPA Title III orders, court orders	Continuous
DOE program announcements	Critical Materials Strategy program changes, funding directives	Continuous
DOD Procurement Directives	Defense-procurement actions affecting strategic minerals	Continuous

8.3 Update Mechanism

The classification relay service polls the federal sources on a 5-minute cadence for federal-action detection (the most time-sensitive class) and a daily cadence for routine classification refreshes. New federal actions matching a basin or mineral class associated with an issued Module 3 mint trigger an automatic P0 incident under the Incident Response Playbook §13.

8.4 Federal Frameworks Tracked

Framework	Trigger Source	Typical Lead Time to Effect
USGS Critical Minerals List	Annual list publication; emergency update	30–60 days from publication
DOE Critical Materials Strategy	Program announcement	30–90 days from announcement
Section 232 (Trade Expansion Act of 1962)	Presidential proclamation	Effective on signature; sometimes phased in
Defense Production Act Title III	Executive Order; DOD contract action	Effective immediately
Inflation Reduction Act critical-minerals	IRS guidance; Treasury rulemaking	30–60 days from guidance
Executive Order 14017 (supply-chain resilience)	EO updates; agency reports	Variable
Energy Act of 2020	DOE program updates	Variable

8.5 Attestation Payload

The Classification attestation is a multi-field on-chain account containing:

Field	Description
mint	Module 3 ST22 mint address
usgs_critical_minerals_status	USGS classification (e.g., "critical_mineral_rare_earth")
doe_critical_materials_status	DOE designation (e.g., "high_priority")
section_232_applicable	Boolean — whether Section 232 currently applies
dpa_title_iii_applicable	Boolean — whether DPA Title III currently applies
federal_action_active	Boolean — whether any federal-action freeze is active
active_action_references	Array of action references (e.g., ["EO-14118"])
last_refresh_timestamp	Unix timestamp of last update

8.6 Relay Service

The classification relay service maintains a continuous monitoring posture across federal sources. The service deduplicates events, classifies severity, and submits two distinct on-chain update types: routine classification refreshes (USGS / DOE status changes without federal action) and federal-action events (P0-severity, triggering automatic Control 42 coordination).

8.7 Transfer Hook Integration

The Transfer Hook reads the Classification oracle on every Module 3 transfer:

1. Freshness check — if classification_max_age_secs is exceeded, transfers are flagged for enhanced compliance review (does not block transfers but is logged for operations review).

2. Federal-action check — if federal_action_active is true, Control 42 (regulatory freeze) is triggered automatically. Transfers are rejected with Error 6042 (RegulatoryOverride / FederalActionFrozen variant). The freeze is executed by Legal Counsel + 3-of-5 multi-signature within 60 minutes per the Incident Response Playbook §13.

8.8 Federal-Action Freeze Coordination

When the relay detects a federal action targeting a basin or mineral class associated with an issued Module 3 mint, the following sequence executes:

1. Federal action detected (Federal Register, DOE, USGS, court order)
   ├─ Source verified
   ├─ Action reference captured (e.g., "EO-14118")
   └─ Affected basin/mineral class matched against issued mint registry

2. P0 incident raised
   ├─ PagerDuty alert to operations
   ├─ Notification to Legal Counsel
   └─ Notification to all multi-signature key holders

3. ClassificationOracle updated
   ├─ federal_action_active = true
   ├─ active_action_references += action reference
   └─ federal_action_detected event emitted on chain

4. Pre-flight enforcement begins
   ├─ All new orders for affected mints rejected with Error 6042
   └─ classification WebSocket channel emits federal_action_detected

5. Legal Counsel + 3-of-5 multi-signature execution (within 60-min SLA)
   ├─ Control 42 (regulatory freeze) activated on chain
   ├─ federal_action_freeze_applied event emitted
   └─ All in-flight transfers revert at the Transfer Hook layer

6. Resolution
   ├─ Federal action expires, is rescinded, or variance/exemption obtained
   ├─ Legal Counsel + 3-of-5 multi-signature lift the freeze
   ├─ federal_action_active = false
   └─ Trading resumes

8.9 Specifications

Parameter	Value
Federal-action polling cadence	5 minutes
Routine classification refresh	Daily + emergency push
Staleness threshold	Configured per mint via classification_max_age_secs
Detection-to-freeze SLA	60 minutes
Module scope	Module 3 only
Fail-safe (staleness)	Enhanced review on transfers; flagged for operations
Fail-safe (federal action)	Auto-coordinate Control 42 freeze

---

9. On-Chain Account Schemas

9.1 CustodyOracle

A single CustodyOracle PDA exists per ST22 mint. The account holds the most recent attestation, including the custodied balance, the on-chain token supply, the attestation slot and timestamp, Empire's Ed25519 public key, the Ed25519 signature of the most recent attestation, the validity flag, the discrepancy-detected flag, and the PDA bump.

PDA seeds: [b"custody-oracle", mint]. Cardinality: one per ST22 mint regardless of module.

9.2 OFACOracle

A global singleton account holds the OFAC oracle state: the last refresh timestamp, the SHA-256 hash of the current SDN list, the entry count, the staleness threshold (86,400 seconds = 24h default), and the halt threshold (172,800 seconds = 48h default).

PDA seeds: [b"ofac-oracle"]. Cardinality: global singleton.

9.3 AMLOracle

One AMLOracle PDA per wallet. The account holds the wallet, the aggregated risk score (0–100), the provider that generated the score (Chainalysis or TRM Labs), the score timestamp, the cache validity (21,600 seconds = 6h default), and the PDA bump.

PDA seeds: [b"aml-oracle", wallet]. Cardinality: one per wallet.

9.4 NAVOracle (Module 2 only)

One NAVOracle PDA per Module 2 mint. The account holds the most recent appraised NAV in USD-pegged stablecoin units, the appraiser identifier, the appraisal timestamp, the next-reappraisal target, the signature, the deviation tolerance, the staleness threshold, and the PDA bump.

PDA seeds: [b"nav-oracle", mint]. Cardinality: one per Module 2 ST22 mint.

9.5 ClassificationOracle (Module 3 only)

One ClassificationOracle PDA per Module 3 mint. The account holds the USGS classification status, the DOE classification status, the Section 232 applicability flag, the DPA Title III applicability flag, the federal-action active flag, the array of active action references, the last refresh timestamp, the staleness threshold, and the PDA bump.

PDA seeds: [b"classification-oracle", mint]. Cardinality: one per Module 3 ST22 mint.

9.6 PDA Registry

PDA	Seeds	Cardinality	Module Scope
CustodyOracle	[b"custody-oracle", mint]	One per ST22 mint	All modules
OFACOracle	[b"ofac-oracle"]	Global singleton	All modules
AMLOracle	[b"aml-oracle", wallet]	One per wallet	All modules
NAVOracle	[b"nav-oracle", mint]	One per Module 2 mint	Module 2 only
ClassificationOracle	[b"classification-oracle", mint]	One per Module 3 mint	Module 3 only

---

10. Relay Service Architecture

10.1 Service Registry

Service	Process	Restart Policy	Health Check	Module Scope
custody-relay	pm2 managed	Auto-restart on crash	/health endpoint + slot age check	All modules
ofac-indexer	pm2 managed	Auto-restart on crash	/health endpoint + staleness check	All modules
aml-bridge	pm2 managed	Auto-restart on crash	/health endpoint + provider status	All modules
twap-consumer	pm2 managed	Auto-restart on crash	/health endpoint + observation count	All modules
edgar-pipeline	pm2 managed	Auto-restart on crash	/health endpoint + last batch time	Module 1
nav-relay	pm2 managed	Auto-restart on crash	/health endpoint + appraiser-channel status	Module 2
classification-relay	pm2 managed	Auto-restart on crash	/health endpoint + federal-source poll status	Module 3

10.2 Infrastructure

┌────────────────────────────────────────────────────┐
│           Kubernetes (EKS)                         │
├────────────────────────────────────────────────────┤
│  custody-relay         │  Dedicated pod (critical) │
│  ofac-indexer          │  Shared pod               │
│  aml-bridge            │  Shared pod               │
│  twap-consumer         │  Shared pod               │
│  edgar-pipeline        │  Shared pod (Module 1)    │
│  nav-relay             │  Shared pod (Module 2)    │
│  classification-relay  │  Dedicated pod (Module 3) │
├────────────────────────────────────────────────────┤
│  Helius RPC            │  Primary Solana connection │
│  Triton RPC            │  Failover connection       │
│  MongoDB Atlas         │  Cache + state storage     │
│  Datadog Agent         │  Metrics + logging         │
│  PagerDuty             │  Alert routing             │
└────────────────────────────────────────────────────┘

The classification-relay service runs in a dedicated pod because federal-action detection has the strictest detection-to-freeze SLA (60 minutes) outside the custody fail-safe.

10.3 Relay Key Management

Service	Key Type	Storage	Rotation
custody-relay	Ed25519 (relay authority)	AWS KMS	Quarterly
ofac-indexer	Ed25519 (relay authority)	AWS KMS	Quarterly
aml-bridge	API keys (Chainalysis + TRM)	AWS Secrets Manager	Annual or on compromise
twap-consumer	Ed25519 (no write — read-only)	AWS KMS	Annual
edgar-pipeline	None (SEC API is public)	—	—
nav-relay	Ed25519 (relay authority) + appraiser pubkeys registry	AWS KMS + secured registry	Quarterly (relay); per-appraiser per tripartite
classification-relay	Ed25519 (relay authority)	AWS KMS	Quarterly

---

11. Fail-Safe Cascade

When multiple oracles fail simultaneously, the cascade follows priority order. The custody fail-safe always dominates — when custody fails, the platform is in a compliance halt and downstream oracles become irrelevant for the affected mint.

CUSTODY ORACLE FAILS
  └─ IMMEDIATE: All transfers halt (Error 6001 / 6002)
     └─ Downstream: OFAC, AML, TWAP, EDGAR, NAV, Classification irrelevant
        (no transfers executing to check against)

CUSTODY OK + OFAC ORACLE STALE > 48h
  └─ All transfers halt (Error 6005)
     └─ Downstream: AML, TWAP, EDGAR, NAV, Classification irrelevant

CUSTODY OK + OFAC OK + AML FAILS
  └─ Use cached scores (< 6h). Reject if no score exists.
     └─ Transfers continue for wallets with cached scores
     └─ New wallets blocked until AML service restored

CUSTODY OK + OFAC OK + AML OK + TWAP FAILS > 5 min
  └─ Circuit breaker disabled
     └─ Transfers continue WITHOUT price-impact protection
     └─ All other 41 controls still active
     └─ P2 alert — engineering investigation

CUSTODY OK + OFAC OK + AML OK + TWAP OK + EDGAR FAILS (Module 1)
  └─ Continue with last batch data
     └─ IDOS scores flagged stale
     └─ Control IV-08 uses last confirmed status
     └─ P2 alert — operations review

CUSTODY OK + ... + NAV FAILS (Module 2)
  └─ Affected Module 2 mint paused on the AMM
     └─ New trades on the affected mint rejected (Error 6021 NAV-stale variant)
     └─ Other Module 2 mints unaffected; Module 1 / 3 unaffected
     └─ P1 alert — appraisal-cycle escalation

CUSTODY OK + ... + CLASSIFICATION ORACLE STALE (Module 3)
  └─ Affected Module 3 mint enters enhanced review
     └─ Transfers continue but flagged for operations
     └─ P2 alert — operations review

CUSTODY OK + ... + FEDERAL ACTION DETECTED (Module 3)
  └─ P0 incident raised
     └─ Pre-flight rejection: Error 6042
     └─ Control 42 freeze executed within 60-min SLA
     └─ All transfers on affected mint halt at Transfer Hook
     └─ Other Module 3 mints unaffected; Module 1 / 2 unaffected

---

12. Health Monitoring

12.1 Monitoring Endpoints

Endpoint	Checks	Alert On
GET /health/custody	Oracle freshness (slot age), signature validity, discrepancy status	Slot age > 5
GET /health/ofac	SDN list age, entry count, refresh status	Age > 12h
GET /health/aml	Provider API availability, cache hit rate, average score latency	Timeout > 2s
GET /health/twap	Observation count, TWAP staleness, Pyth feed status	Observations < 60
GET /health/edgar	Last RSS poll, last batch completion, pipeline status	Batch > 36h old
GET /health/nav	Per-mint NAV staleness, appraiser-channel status	Any mint > 50% of nav_reappraisal_max_age_secs
GET /health/classification	Per-mint classification staleness, federal-source poll status, federal-action queue	Federal-action queue depth > 0

12.2 Datadog Dashboards

Dashboard	Key Metrics
Oracle Overview	All seven oracle statuses, global health score
Custody Deep Dive	Attestation latency histogram, slot age trend, discrepancy counter (must always be 0)
OFAC and AML	SDN list freshness, AML query latency by provider, score-distribution histogram
TWAP and Circuit Breaker	TWAP versus spot price, observation count, breaker trigger count
EDGAR Pipeline (Module 1)	Filing processing latency, RSS poll success rate, batch completion times
NAV Oracle (Module 2)	Per-mint NAV staleness countdown, deviation distribution, appraisal-cycle calendar
Classification Oracle (Module 3)	Per-mint classification freshness, federal-action queue depth, P0 incident timeline, freeze-SLA tracking

12.3 Alert Thresholds

Alert	Condition	Severity	Escalation
Custody oracle stale	Slot age > 5	P0	CTO + all multi-sig holders
Custody discrepancy	discrepancy_detected == true	P0	CTO + Legal Counsel + Empire
OFAC stale > 24h	last_refresh > 24h ago	P1	CTO + compliance
AML both providers down	Both Chainalysis + TRM timeout	P1	CTO + DevOps
TWAP unavailable > 5 min	Observation count < 60 or feed stale	P2	On-call engineer
EDGAR batch failed	Last batch > 36h ago	P2	On-call engineer
NAV stale (Module 2)	Per-mint > nav_reappraisal_max_age_secs	P1	Operations + issuer outreach
NAV deviation (Module 2)	Per-mint > nav_deviation_max_bps	P1	Operations + issuer outreach
Classification stale (Module 3)	Per-mint > classification_max_age_secs	P2	On-call engineer
Federal action detected (Module 3)	federal_action_active == true (any mint)	P0	CTO + Legal Counsel + multi-sig holders
Relay service crash	pm2 status ≠ online	P2	On-call engineer
RPC failover triggered	Primary Helius → Triton backup	P2	DevOps

---

13. Failure Injection Testing

Chaos testing validates that fail-safes work correctly under degraded conditions.

13.1 Test Scenarios

Test	Method	Expected Behavior	Frequency	Module Scope
Custody relay killed	pm2 stop custody-relay	All transfers halt after 1 slot stale. Error 6002.	Monthly	All modules
Empire API returns 500	Mock error response	Relay retries 3x, then stale. Transfers halt.	Monthly	All modules
False custody discrepancy	Inject custodied_balance ≠ token_supply	Error 6001 on all transfers. P0 alert.	Quarterly	All modules
OFAC indexer killed	pm2 stop ofac-indexer	Cached SDN list used < 24h. Halt > 48h.	Monthly	All modules
Both AML providers timeout	Network partition on AML bridge	Cached scores used < 6h. New wallets blocked.	Monthly	All modules
Pyth feed stale	Mock stale Pyth data	Circuit breaker disabled after 5 min. P2 alert.	Monthly	All modules
EDGAR RSS down	Block SEC RSS endpoint	Last batch used. IDOS flagged stale. P2 alert.	Monthly	Module 1
RPC failover	Block Helius endpoint	Automatic failover to Triton. P2 alert.	Monthly	All modules
All oracles fail simultaneously	Kill all relay services	All transfers halt (custody fail-safe dominates). P0.	Quarterly	All modules
NAV relay killed	pm2 stop nav-relay	Affected Module 2 mints pause when staleness exceeded.	Monthly	Module 2
NAV deviation injection	Inject NAV value triggering deviation	Affected mint paused. Error 6021. P1 alert.	Quarterly	Module 2
Classification relay killed	pm2 stop classification-relay	Module 3 mints enter enhanced review on staleness. P2.	Monthly	Module 3
Federal-action injection	Inject federal-action event	P0 incident raised. Control 42 freeze within 60 min.	Quarterly	Module 3

13.2 Running Chaos Tests

The chaos-test runbook is documented in the platform's internal operations repository. Module-specific scenarios are gated to environments with active Module 2 or Module 3 mints (devnet always; mainnet via specific test mints).

---

14. Key Rotation

14.1 Rotation Schedule

Key	Rotation	Process
Empire Ed25519 (custody attestation)	Empire-managed per §17A	Empire rotates → new pubkey registered on chain via multi-sig
Relay authority keys (custody-relay, ofac-indexer, twap-consumer)	Quarterly	New key generated in AWS KMS → governance proposal → 48h timelock → on-chain update
Chainalysis API key	Annual	Rotate in Secrets Manager → restart aml-bridge
TRM Labs API key	Annual	Rotate in Secrets Manager → restart aml-bridge
Module 2 appraiser keys	Per appraiser engagement	New appraiser key registered when added to tripartite registry
Module 2 NAV-relay authority	Quarterly	Same as other relay authority keys
Module 3 classification-relay authority	Quarterly	Same as other relay authority keys

14.2 Empire Key Rotation

1. Empire generates new Ed25519 keypair (HSM-backed)
2. Empire communicates new public key to the platform via secure channel
3. Platform creates governance proposal to update empire_pubkey on every CustodyOracle
4. 48-hour timelock
5. 5-of-9 multi-signature executes on-chain update
6. Old key deauthorized in same transaction
7. Verification: next attestation signed with new key, verified on chain

14.3 Module 2 Appraiser Key Rotation

When a new appraiser is engaged or an appraiser's license is renewed:

1. Appraiser provides new public key plus current license documentation
2. Issuer-Empire-Platform tripartite reviews and signs off
3. NAV relay registers the new appraiser public key in the authorized registry
4. Old appraiser public key remains valid for verification of historical appraisals
   but cannot sign new attestations

---

15. Troubleshooting

15.1 Common Issues

Symptom	Diagnosis	Resolution
All transfers failing with 6002	Custody oracle stale	Check pm2 status custody-relay. Verify Helius RPC. Restart relay.
Transfers failing with 6005	OFAC oracle stale > 48h	Check pm2 status ofac-indexer. Verify Treasury API access. Restart indexer.
New wallets rejected with 6006	AML providers unreachable	Check Chainalysis + TRM API keys. Verify network. Restart aml-bridge.
Circuit breaker stuck active	TWAP stale or miscalculated	Check Pyth feed status. Verify observation count ≥ 60. Restart twap-consumer.
Module 1 issuer tokens halted unexpectedly	Control IV-08 detected enforcement action	Check EDGAR pipeline logs. Verify 8-K filing. May be correct behavior.
AML scores all returning 0	API key expired	Rotate API keys in AWS Secrets Manager. Restart aml-bridge.
Oracle accounts not found	PDAs not initialized	Run oracle-initialization for the affected mint per the Deployment Guide.
Module 2 mint paused on AMM with Error 6021	NAV deviation exceeded or NAV stale	Check pm2 status nav-relay. Verify appraiser-channel health. Confirm next reappraisal scheduled.
Module 2 NAV oracle missing data	NAV PDA not initialized at mint creation	Re-run NAV oracle initialization for the affected mint.
Module 3 mint frozen with Error 6042	Federal action detected	Verify in classification-relay logs. Confirm action reference. Coordinate with Legal Counsel.
Module 3 mint flagged for enhanced review	Classification stale	Check pm2 status classification-relay. Verify federal-source feeds operational.

15.2 Diagnostic Commands

# Check custody oracle freshness
anchor account oracle-aggregator CustodyOracle \
  --provider.cluster mainnet | jq '.attestationSlot'
# Compare with: solana slot

# Check OFAC oracle age
anchor account oracle-aggregator OFACOracle \
  --provider.cluster mainnet | jq '.lastRefresh'

# Check AML score for a wallet
curl https://api.cedex.market/v1/oracle/aml/9aB2xY... | jq

# Module 2: Check NAV oracle for a mint
curl https://api.cedex.market/v1/oracle/{mint}/nav | jq

# Module 3: Check Classification oracle for a mint
curl https://api.cedex.market/v1/oracle/{mint}/classification | jq

# Check all oracle health
curl https://api.cedex.market/v1/health | jq '.oracle_status'

# View relay service logs
pm2 logs custody-relay --lines 100
pm2 logs ofac-indexer --lines 100
pm2 logs aml-bridge --lines 100
pm2 logs nav-relay --lines 100
pm2 logs classification-relay --lines 100

---

Related Documentation

• Smart Contract Reference — Oracle account schemas and update instructions.

• Transfer Hook Reference — Standalone reference for the 42 controls including module-aware extensions.

• Security Model — Oracle attack-surface analysis and fail-safe design; module-specific threat surfaces.

• Deployment Guide — Oracle relay service deployment, including Module 2 NAV oracle and Module 3 Classification oracle initialization.

• Incident Response Playbook — P0 through P3 runbooks; Module 3 federal-action freeze runbook (§13).

• Empire Stock Transfer Integration — Custody architecture, Ed25519 attestation lifecycle, MSF, and module-aware custody coverage.

• CEDEX API Reference — Public oracle endpoints (/oracle/{mint}/custody, /oracle/{mint}/nav, /oracle/{mint}/classification).

• Issuer Onboarding Guide — Module-specific oracle initialization at mint creation.

• Network Configuration — Oracle PDAs and oracle-relay endpoints.

---

RWA Tokens · Oracle Integration Guide · Groovy Company, Inc.