🔐 Section 3: SPL Token-2022 Transfer Hooks — Layer 2

The Reconciliation Invariant

At every Solana slot, the following invariant MUST hold for every active ST22 mint:

on_chain_token_supply(mint)circulating_supply <=≤ empire_custodied_shares(mint)custodied_shares

Any condition where on-chain supply EXCEEDSexceeds custodied shares is an immediate critical alert (Error 6001 — all transfers halted). The system is designed so that equality (1:1 backing) is the steady state and— a deficit on the custody sidedeficit is impossible under normal operations because shares must be deposited BEFOREbefore tokens are minted.

/// Canonical signed attestation payload from Empire Stock Transfer API
/// Received by the primary Oracle and published on-chain each slot
#[derive(BorshSerialize, BorshDeserialize, Debug)]
pub struct EmpireCustodyAttestation {
    /// Schema version — must match EMPIRE_SCHEMA_VERSION constant
    pub schema_version: u8,                    // Currently: 1

    /// The ST22 mint this attestation covers
    pub mint: Pubkey,

    /// CUSIP of the underlying Series M preferred share class
    pub cusip: [u8; 9],

    /// Total shares of Series M held in irrevocable custody at Empire
    /// This is the authoritative backing figure
    pub custodied_shares: u64,

    /// Total shares ever deposited (monotonically increasing)
    pub total_deposited_lifetime: u64,

    /// Solana slot number at time of attestation
    pub slot: u64,

    /// Unix timestamp at time of attestation
    pub timestamp: i64,

    /// Attestation expiry — slot after which Hook 1 rejects this message
    pub expiry_slot: u64,

    /// Monotonically increasing sequence number (replay prevention)
    pub sequence_number: u64,

    /// SHA-256 hash of Empire's internal ledger state at this slot
    /// Enables independent verification against Empire's published quarterly hash
    pub ledger_state_hash: [u8; 32],

    /// Ed25519 signature over all fields above using Empire HSM key
    pub signature: [u8; 64],

    /// Empire's HSM public key (must match on-chain OracleRegistry entry)
    pub signer_pubkey: Pubkey,
}

/// On-chain custody cache — stores latest valid attestation per mint
#[account]
pub struct CustodyCache {
    pub version: u8,
    pub mint: Pubkey,
    pub custodied_shares: u64,
    pub last_updated_slot: u64,
    pub last_sequence_number: u64,
    pub ledger_state_hash: [u8; 32],
    pub bump: u8,
}

/// Hook 1: Full supply reconciliation on every transfer
pub fn verify_custody_hook(verify_custody(
    ctx:             Context,Context<CustodyVerification>,
    transfer_amount: u64,
) -> Result<()> {
    // ---1. STEPVerify 1:oracle Validatesignature attestationauthenticity
    schemaverify_ed25519_signature(
        version&oracle_data.attestation_signature,
        ---&EMPIRE_PUBLIC_KEY,
        &oracle_data.serialize(),
    )?;

    // 2. Reject stale attestations (>10 minutes)
    require!(
        ctx.accounts.oracle_attestation.schema_versioncurrent_time =- oracle_data.attestation_timestamp <= EMPIRE_SCHEMA_VERSION,600,
        OracleError:CustodyError::SchemaMismatchStaleAttestation  // 6001
    );

    // ---3. STEPCheck 2:discrepancy Verifywithin Ed255190.01% signaturetolerance
    ---require!(
        discrepancy_bps <= MAX_DISCREPANCY_BPS,
        CustodyError::CustodyDiscrepancy  // Signature covers all fields except `signature` itself
    let attestation_bytes = ctx.accounts.oracle_attestation
        .try_to_vec_without_signature()?;
    verify_ed25519_signature(
        &attestation_bytes,
        &ctx.accounts.oracle_attestation.signature,
        &ctx.accounts.oracle_registry.empire_primary_pubkey,
    ).map_err(|_| error!(OracleError::InvalidSignature))?;

    // --- STEP 3: Verify attestation is not stale ---
    let current_slot = Clock::get()?.slot;
    require!(
        current_slot <= ctx.accounts.oracle_attestation.expiry_slot,
        OracleError::StaleAttestation   // Error 60196001
    );

    // ---4. STEPConfirm 4: Verify sequence number (replay prevention) ---
    require!(
        ctx.accounts.oracle_attestation.sequence_number
            > ctx.accounts.custody_cache.last_sequence_number,
        OracleError::ReplayAttack
    );

    // --- STEP 5: THE CORE INVARIANT CHECK ---
    // Get current on-chain circulating supply from mint account
    let on_chain_supply = ctx.accounts.mint.supply;

    // Getsufficient custodied shares fromfor verifiedtransfer
    attestationrequire!(
        letoracle_data.custodied_balance custodied_shares >= ctx.accounts.oracle_attestation.custodied_shares;transfer_amount,
        CustodyError::InsufficientCustody  // Verify invariant: supply <= custody
    // Allow 0.01% tolerance for timing edge cases (MAX_DISCREPANCY_BPS = 1)
    let max_allowed_supply = custodied_shares
        .checked_add(
            custodied_shares
                .checked_mul(MAX_DISCREPANCY_BPS)
                .ok_or(OracleError::Overflow)?
                .checked_div(10_000)
                .ok_or(OracleError::Overflow)?
        )
        .ok_or(OracleError::Overflow)?;

    require!(
        on_chain_supply <= max_allowed_supply,
        TransferHookError::CustodyDiscrepancy   // Error 6001 — HALT
    );

    // --- STEP 6: Verify post-transfer supply still within bounds ---
    // After this transfer, supply does not change (it's a transfer not a mint)
    // But verify amount_in does not exceed available custodied backing
    let post_transfer_supply = on_chain_supply; // transfers don't change supply
    require!(
        post_transfer_supply <= custodied_shares,
        TransferHookError::CustodyDiscrepancy
    );

    // --- STEP 7: Update on-chain cache with latest attestation ---
    // CEI pattern: all checks complete — now write state
    let cache = &mut ctx.accounts.custody_cache;
    cache.custodied_shares = custodied_shares;
    cache.last_updated_slot = current_slot;
    cache.last_sequence_number = ctx.accounts.oracle_attestation.sequence_number;
    cache.ledger_state_hash = ctx.accounts.oracle_attestation.ledger_state_hash;

    Ok(())
}

pub const MAX_DISCREPANCY_BPS: u64 = 1;  // 0.01% maximum discrepancy

Public Verification Procedure:

bash

# Anyone can verify the 1:1 backing at any point in time:

# Step 1 — Query on-chain supply for a specific ST22 mint
spl-token supply

# Step 2 — Fetch latest custody attestation from on-chain cache
solana account  --output json

# Step 3 — Verify Empire signature using public key
otcm-verify-custody   --attestation    --pubkey

# Step 4 — Compare: on-chain supply <= custodied_shares
# Any discrepancy should be reported immediately to security@otcm.io

🔹 3.3.3 Discrepancy Detection

The hook implements strict discrepancy detection with configurable thresholds:

// Custody Verification Implementation (Rust/Anchor)

pub const MAX_DISCREPANCY_BPS: u64 = 1; // 0.01% maximum discrepancy

pub fn verify_custody(

oracle_data: &CustodyOracleData,

transfer_amount: u64,

) -> Result<()> {

// Verify signature authenticity

verify_ed25519_signature(

&oracle_data.attestation_signature,

&EMPIRE_PUBLIC_KEY,

&oracle_data.serialize(),

)?;

// Check attestation freshness (max 10 minutes old)
let current_time = Clock::get()?.unix_timestamp;
require!(

current_time - oracle_data.attestation_timestamp <= 600,

CustodyError::StaleAttestation // 6001

);

// Calculate discrepancy
let expected_tokens = oracle_data.custodied_balance;
let actual_tokens = oracle_data.circulating_tokens;
let discrepancy = if expected_tokens > actual_tokens {

expected_tokens - actual_tokens

} else {

actual_tokens - expected_tokens

};

let discrepancy_bps = discrepancy * 10000 / expected_tokens;
require!(

discrepancy_bps <= MAX_DISCREPANCY_BPS,

CustodyError::CustodyDiscrepancy // 6001

);

// Verify sufficient custody for this transfer
require!(

oracle_data.custodied_balance >= transfer_amount,

CustodyError::InsufficientCustody // 6001

);

Ok(())

}

📋 Regulatory Reference: 17 CFR Section 240.17a-1 et seq. — Transfer Agent Custody Requirements

✗ Error Code 6001: CUSTODY_VERIFICATION_FAILED

— Indicates custody verification failure. Possible causes: stale attestation (>10 min), discrepancy >0.01%, insufficient custodied shares, or invalid Empire signature. User should wait for fresh attestation or contact issuer.

🔗 3.4 Hook 2: OFAC Sanctions Screening

The OFAC Sanctions Screening hook prevents transactions to or from wallets associated with the Office of Foreign Assets Control's Specially Designated Nationals (SDN) list, implementing federal sanctions law requirements at the protocol level.

🔹 3.4.1 SDN List Integration

OTCM maintains an on-chain oracle updated hourly from OFAC's official SDN list, supplemented by blockchain-specific address intelligence:

// OFAC Screening Implementation

pub struct OfacOracleData {

/// Merkle root of current SDN list

pub sdn_merkle_root: [u8; 32],

/// Number of entries in SDN list

pub sdn_entry_count: u32,

/// Blockchain-specific blocked addresses

pub crypto_sdn_addresses: Vec<Pubkey>,

/// Last update timestamp

pub last_update: i64,

/// OFAC publication reference

pub publication_id: [u8; 16],

}

// Screening checks BOTH sender and recipient
pub fn screen_ofac(

sender: &Pubkey,

recipient: &Pubkey,

oracle: &OfacOracleData,

) -> Result<OfacScreeningResult> {

// Direct address matching
let sender_blocked = oracle.crypto_sdn_addresses.contains(sender);
let recipient_blocked = oracle.crypto_sdn_addresses.contains(recipient);

if sender_blocked || recipient_blocked {

return Err(OfacError::SanctionedAddress.into()); // 6002

}

// Address clustering analysis (see 3.4.2)

check_cluster_association(sender, recipient, oracle)?;

Ok(OfacScreeningResult::Clear)

}

🔹 3.4.2 Address Clustering Analysis

Beyond direct SDN address matching, OTCM implements sophisticated address clustering analysis to detect wallets associated with sanctioned entities:

• Funding Source Analysis:Analysis — Traces wallet funding sources to identify indirect SDN connections
• Common Ownership Detection:Detection — Identifies wallets controlled by the same entity through transaction pattern analysis
• Mixer/Tumbler Detection:Detection — Flags wallets with significant exposure to known mixing services
• High-Risk Jurisdiction Exposure:Exposure — Elevated scrutiny for wallets with connections to OFAC-sanctioned jurisdictions

🔹 3.4.3 Screening Implementation

// Cluster Analysis Implementation
pub fn check_cluster_association(

sender: &Pubkey,

recipient: &Pubkey,

oracle: &OfacOracleData,

) -> Result<()> {

// QueryDirect clusteringSDN oracleaddress formatch
    bothif addressessender_blocked let|| sender_clusterrecipient_blocked ={
        get_cluster_data(sender)?;return let recipient_cluster = get_cluster_data(recipient)?Err(OfacError::SanctionedAddress.into());  // Check6002
    for}

    SDN// clusterCluster membership

scoring (threshold: 70) if sender_cluster.sdn_association_score > 70 {

return Err(OfacError::ClusterAssociation {

address: *sender,

score: sender_cluster.sdn_association_score,

reason: "High SDN cluster association".to_string(),

}.into());

}

if recipient_cluster.sdn_association_score > 70 {

return Err(OfacError::ClusterAssociation {

address: *recipient,

score: recipient_cluster.sdn_association_score,

reason: "High SDN cluster association".to_string(),

}.into());

}

Ok(())
}

}

📋 Regulatory Reference: 31 CFR § 500-500–598 — OFAC Sanctions Administration Regulations

✗ Error Code 6002: OFAC_SANCTIONS_MATCH

Indicates— wallet isWallet blocked due to OFAC sanctions. This is a PERMANENT block—block — the wallet cannot transact ST22 tokens. There is no appeal process through OTCM; affected parties must resolve sanctions status with OFAC directly.

🔗 3.5 Hook 3: Blockchain Analytics / AML Screening

The Blockchain Analytics Screening hook implements Bank Secrecy Act Anti-Money Laundering (AML)AML requirements through machine learning-based risk assessment,assessment, analyzing 200+ transaction features to identify money laundering patterns, sanctions evasion, theft proceeds, and coordinated suspicious activity.

🔹 3.3.5.1 ML Risk Assessment

OTCM integrates with institutional-grade blockchain analytics providers to execute real-time risk assessment on every transfer:

// AML Risk Assessment Data Structure

pub struct AmlRiskAssessment {

    
/// Overall risk score (0-100)

pub risk_score:      u8,
    
/// Risk category breakdown

pub categories:      AmlRiskCategories,
    
/// Specific risk flags triggered

pub triggered_flags: Vec<AmlFlag>,
    
/// Confidence in assessment

pub confidence:      u8,
    
/// Model version used

pub model_version:   [u8; 8],
}

pub struct AmlRiskCategories {
    
pub sanctions_evasion:     u8,  // 0-0–100
    
pub money_laundering:      u8,  // 0-0–100
    
pub theft_proceeds:        u8,  // 0-0–100
    
pub darknet_exposure:      u8,  // 0-0–100
    
pub mixer_exposure:        u8,  // 0-0–100
    
pub gambling_exposure:     u8,  // 0-0–100
    
pub coordinated_activity:  u8,  // 0-0–100
}

🔹 3.3.5.2 Risk Scoring ModelTiers

The risk scoring model classifies transactions into three tiers with automated responses:

🔹 3.5.3.3 Chainalysis/TRMAnalytics Provider Integration

OTCM integrates with industry-leading blockchain analytics providers:

• Chainalysis KYT (Know Your Transaction): — Real-time transaction screening with 15-second SLA
• TRM Labs Forensics:Forensics — Deep historical analysis and entity resolution
• Elliptic Navigator:Navigator — Cross-chain exposure analysis for multi-chain actors

🔹 3.5.3.4 Implementation

// AML Screening Implementation

pub const LOW_RISK_THRESHOLD: u8 = 30;

pub const HIGH_RISK_THRESHOLD: u8 = 71;

pub fn screen_aml(

sender: &Pubkey,

recipient: &Pubkey,

amount: u64,

) -> Result<AmlScreeningResult> {

// Query analytics providers
let sender_risk = query_chainalysis(sender)?;
let recipient_risk = query_chainalysis(recipient)?;
// Use higher of two risk scores
let max_risk = sender_risk.risk_score.max(recipient_risk.risk_score);

match max_risk {

0..=30 => Ok(AmlScreeningResult::AutoApprove),

31..=70 => {

//queue_enhanced_review(sender, Queuerecipient, foramount);
            enhanced review but allow transaction
emit!(EnhancedReviewQueued {

sender: *sender,

recipient: *recipient,

risk_score: max_risk,

amount,

});

Ok(AmlScreeningResult::ApproveWithReview)

},

71..=100 => {

// Auto-reject high-risk transactions

Err(AmlError::RiskThresholdExceeded {

score: max_risk,

threshold: HIGH_RISK_THRESHOLD,

}.into()), // 6003

},

_ => unreachable!(),

}

}

📋 Regulatory Reference: 31 CFR § 1010 — Bank Secrecy Act AML Requirements

✗ Error Code 6003: AML_RISK_EXCEEDED

— Transaction rejected due to high AML risk score (71-71–100). Wallet may have exposure to:to money laundering, sanctions evasion, theft proceeds, darknet markets, or coordinated suspicious activity. Appeal requires compliance review.

🔗 3.6 Hook 4: Redemption Eligibility Verification

The Redemption Eligibility Verification hook implements a critical distinction in OTCM's compliance architecture: while permissionless trading allows any verified wallet to purchase and transfer ST22 tokens, redemption (conversion to underlying equity shares) requires full investor verification in accordance with federal securities law.

🔹 3.6.1 KYC/AML Requirements

Before a wallet can redeem ST22 tokens for underlying shares, the beneficial owner must complete comprehensive verification:

🔹 3.6.2 Accredited Investor Verification

For offerings conducted under SEC Regulation D Rule 506(c), additional accreditation verification is required:

// Accreditation Status Types

pub enum AccreditationStatus {

///NotVerified,
    Not verified - cannot redeem Reg D offerings

NotVerified,

/// Verified accredited investor

Accredited {

method: AccreditationMethod,

verification_date: i64,

expiration_date: i64, // Typically 90 days

verifier: String, // e.g., "VerifyInvestor.com"

},

/// Non-accredited but permitted (Reg A+ or Reg CF)

NonAccreditedPermitted {

regulation: OfferingRegulation,

investment_limit: u64,

},

}

pub enum AccreditationMethod {

Income, // $200K/200K / $300K annual income

NetWorth, // $1M+ net worth excluding primary residence

Professional, // Series 7, 65, or 82 license

Entity, // Qualified entity (bank, trust, etc.)

KnowledgeTest, // SEC proposed "accreditation exam"

}

🔹 3.6.3 Implementation

// Redemption Eligibility Verification
pub fn verify_redemption_eligibility(

wallet: &Pubkey,

token_mint: &Pubkey,

amount: u64,

) -> Result<()> {

// Load investor record
let investor = get_investor_record(wallet)?;
    // Check KYC completionmust be verified
    require!(

investor.kyc_status == KycStatus::Verified,

RedemptionError::KycIncomplete // 6004

);

// Check 72-hour sanctions cooling period
    let current_time = Clock::get()?.unix_timestamp;
let cooling_period = 72 * 60 * 60;  // 72 hours in seconds
require!(

current_time - investor.sanctions_clear_timestamp >= cooling_period,

RedemptionError::SanctionsCoolingPeriod // 6004

);

// Load offering details
let offering = get_offering_details(token_mint)?;

    // Check accreditation if Reg D 506(c)

accreditation required if offering.regulation == Regulation::RegD506c {

match &investor.accreditation {

AccreditationStatus::Accredited { expiration_date, .. } => {

require!(

current_time < *expiration_date,

RedemptionError::AccreditationExpired // 6004

);

},

_ => {

return Err(RedemptionError::AccreditationRequired.into());

}

}

}

Ok(())
}

}

📋 Regulatory Reference: 17 CFR 230.506(c) — Regulation D Accredited Investor Requirements

✗ Error Code 6004: REDEMPTION_ELIGIBILITY_FAILED

— Wallet not eligible for redemption. Possible causes: KYC incomplete, sanctions cooling period active (<72h), accreditation expired/expired or missing for Reg D offerings. Note: TradingRegular isST22 stilltrading permitted;remains permitted — only redemption to underlying shares is blocked.

🔗 3.7 Hook 5: Price Impact Circuit Breaker

The Price Impact Circuit Breaker prevents single transactions from causing excessive market movement, implementing regulatory objectives prohibiting manipulative trading devices. Any transaction causing greater than 2% price movement against the Time-Weighted Average Price (TWAP) oracle is automatically rejected.

🔹 3.7.1 TWAP Oracle Integration

The TWAP oracle provides manipulation-resistant reference pricing:

// TWAP Oracle Implementation

pub struct TwapOracle {

pub token_mint: Pubkey,

/// Rolling 1-hour TWAP

pub twap_1h: u64,

/// Rolling 24-hour TWAP

pub twap_24h: u64,

/// Number of observations in window

pub observation_count: u32,

/// Minimum observations required

pub min_observations: u32,

/// Last update slot

pub last_update_slot: u64,

}

impl TwapOracle {

pub fn get_reference_price(&self) -> Result {
// Use shorter TWAP for more responsive circuit breakers
// but require minimum observations to prevent manipulation
require!(

self.observation_count >= self.min_observations,

OracleError::InsufficientObservations

);

Ok(self.twap_1h)

}

}

🔹 3.7.2 2% Threshold Enforcement

The 2% threshold forces large market participants to execute trades gradually, preventing sudden price dislocations:

// Price Impact Circuit Breaker Implementation

pub const MAX_PRICE_IMPACT_BPS: u64 = 200; // 2.00%

pub fn check_price_impact(

pool: &LiquidityPool,

trade_amount: u64,

trade_direction: TradeDirection,

) -> Result<()> {

// Get TWAP reference price
let twap = pool.twap_oracle.get_reference_price()?;
// Calculate expected post-trade price using CPMM formula
    let (new_sol_reserve,post_sol_reserve, new_token_reserve)post_token_reserve) = match trade_direction {

TradeDirection::Buy => (

pool.sol_reserve + trade_amount,

pool.token_reserve - calculate_output(trade_amount, pool)?,

),

TradeDirection::Sell => (

pool.sol_reserve - calculate_output(trade_amount, pool)?,

pool.token_reserve + trade_amount,

),

};

let post_trade_price = new_sol_reservepost_sol_reserve * 1_000_000_0001_000_000 / new_token_reserve;
// Calculate deviation from TWAPpost_token_reserve;
    let deviation = if post_trade_price > twap {

(post_trade_price - twap) * 10000 / twap

} else {

(twap - post_trade_price) * 10000 / twap

};

require!(

deviation <= MAX_PRICE_IMPACT_BPS,

CircuitBreakerError::PriceImpactExceeded {

expected_impact_bps: deviation,

max_allowed_bps: MAX_PRICE_IMPACT_BPS,

} // 6006

);

Ok(())
}

}

📋 Regulatory Reference: 17 CFR 240.10b-5(b) — Prohibition on Manipulative Trading Devices

✗ Error Code 6006: PRICE_IMPACT_EXCEEDED

— Transaction would cause >2% price movement from TWAP. User should reduce trade size or split into multiple smaller transactions. This protects all market participants from sudden price manipulation.

🔗 3.8 Hook 6: Liquidity Pool Sufficiency

The Liquidity Pool Sufficiency hook ensures the OTCM Liquidity Pool maintains adequate reserves to support all outstanding ST22 Digital Securities tokens. The hook confirms the pool maintains a minimum 150% ratio of locked capital to circulating ST22 value before allowing redemption transactions.

🔹 3.8.1 150% Ratio Requirement

The 150% over-collateralization provides a safety buffer ensuring redemptions can always be honored:

🔹 3.8.2 Implementation

// Liquidity Sufficiency Check

pub const MIN_SUFFICIENCY_RATIO_BPS: u64 = 15000; // 150%

pub fn check_liquidity_sufficiency(

pool: &UnifiedLiquidityPool,

redemption_amount: u64,

) -> Result<()> {

// Calculate current ratio
let locked_capital = pool.total_sol_reserve;
let circulating_value = calculate_total_circulating_value(pool)?;
// Add redemption impact
let post_redemption_capital = locked_capital - redemption_amount;
let post_redemption_ratio = post_redemption_capital * 10000 / circulating_value;
    require!(

post_redemption_ratio >= MIN_SUFFICIENCY_RATIO_BPS,

LiquidityError::InsufficientLiquidity {

current_ratio: post_redemption_ratio,

required_ratio: MIN_SUFFICIENCY_RATIO_BPS,

} // 6007

);

Ok(())
}

}

📋 Regulatory Reference: Securities Exchange Act Rule 15c2-11 — Capital Adequacy Requirements

✗ Error Code 6007: LIQUIDITY_INSUFFICIENT

— Pool ratio below 150% threshold. Redemptions temporarily paused until trading volume rebuilds reserves. Regular ST22 trading (non-redemption) remains permitted.

🛡️ 3.9 Thirty-Six Supplementary Security Controls

Beyond the six primary Transfer Hooks, OTCM implements thirty-six supplementary security controls integrated into the transfer hook logic,logic — creating a comprehensive 42-point security framework.framework.

🔹 3.9.1 Smart Contract Controls (1-1–6)

🔹 3.9.2 Access Control Framework (7-7–12)

🔹 3.9.3 Transaction Integrity Controls (13-13–18)

• Atomic Execution:Execution — All-or-nothing transaction commitment
• Orphan Prevention:Prevention — No partial execution states possible
• Replay Protection:Protection — Unique transaction signatures prevent replay
• Deadline Enforcement:Enforcement — Transactions expire after specified block height
• Slippage Protection:Protection — User-configurable maximum price deviation

🔹 3.9.4 Oracle & Data Controls (19-19–24)

• Multi-Oracle Consensus:Consensus — Cross-reference multiple data sources
• Staleness Detection:Detection — Reject data older than threshold (10 min)
• Signature Verification:Verification — Ed25519 verification of all oracle data
• Rate Limiting:Limiting — Maximum oracle queries per block per mint
• Fallback Oracles:Oracles — Automatic failover to backup data sources
• Data Freshness Proofs:Proofs — On-chain attestation of data recency

🔹 3.9.5 Monitoring & Alerting (25-25–30)

• Real-Time Monitoring:Monitoring — 24/7 transaction pattern analysis
• Anomaly Detection:Detection — ML-based unusual activity identification
• SEC Notification:Notification — Automatic reporting of compliance failures
• Compliance Dashboard:Dashboard — Real-time visibility for regulators
• Audit Log Export:Export — On-demand historical data retrieval
• Alert Escalation:Escalation — Tiered notification for severity levels

🔹 3.9.6 Governance & Recovery (31-31–36)

• Proposal System:System — On-chain governance for parameter changes
• Voting Mechanism:Mechanism — Token-weighted voting with delegation
• Quorum Requirements:Requirements — Minimum participation thresholds
• Veto Power:Power — Compliance officer veto on security-relevant proposals
• Migration Capability:Capability — Controlled upgrade path for critical fixes
• Disaster Recovery:Recovery — Documented procedures for catastrophic scenarios

❌ 3.10 Error Handling and Recovery

⚡ 3.11 Performance Specifications

🔒 CROSS-PROGRAMCross-Program INVOCATIONInvocation (CPI) SECURITYSecurity SPECIFICATIONSpecification

CPI Boundary Map

Every CPI call in OTCM Transfer Hook programs is documented below. For each boundary, the privilege model, account validation, and escalation prevention mechanism is specified.

Privilege Escalation Prevention: All OTCM programs use invoke_signed only when the signing PDA is owned by the calling program. No OTCM instruction passes a user-provided signer to a CPI target. TheClient-supplied remaining_accountsaccounts fieldnot in Transfer Hook extra account metas is validated against an on-chainthe ExtraAccountMetaList PDA — client-supplied accounts that are not in this registry cause immediate instruction failure.

PDA Derivation Canonical Reference

All Program Derived Addresses used by OTCM Protocol follow strict canonical derivation paths. Canonical bump enforcement (using the first valid bump, not a client-supplied bump) is enforced on every instruction.

rust

// --- TRANSFER HOOK PDAs ---

/// Extra account metas list — required by SPL Token-2022 Transfer Hook spec
pub fn extra_account_metas_pda(mint: &Pubkey, program_id: &Pubkey) -> (Pubkey, u8) {
    Pubkey::find_program_address(
        &[b"extra-account-metas", mint.as_ref()],
        program_id,
    )
}

/// Per-token compliance state account
pub fn compliance_state_pda(mint: &Pubkey, program_id: &Pubkey) -> (Pubkey, u8) {
    Pubkey::find_program_address(
        &[b"compliance-state", mint.as_ref()],
        program_id,
    )
}

/// Per-wallet KYC/accreditation record
pub fn investor_record_pda(wallet: &Pubkey, program_id: &Pubkey) -> (Pubkey, u8) {
    Pubkey::find_program_address(
        &[b"investor-record", wallet.as_ref()],
        program_id,
    )
}

// --- ORACLE PDAs ---

/// Oracle sequence number registry — per oracle type
pub fn oracle_sequence_pda(oracle_type: u8, program_id: &Pubkey) -> (Pubkey, u8) {
    Pubkey::find_program_address(
        &[b"oracle-sequence", &[oracle_type]],
        program_id,
    )
}

/// Cached oracle attestation — latest valid message per oracle type
pub fn oracle_cache_pda(oracle_type: u8, mint: &Pubkey, program_id: &Pubkey) -> (Pubkey, u8) {
    Pubkey::find_program_address(
        &[b"oracle-cache", &[oracle_type], mint.as_ref()],
        program_id,
    )
}

// --- LIQUIDITY POOL PDAs ---

/// Sovereign LP pool state — per ST22 mint
pub fn lp_pool_state_pda(mint: &Pubkey, program_id: &Pubkey) -> (Pubkey, u8) {
    Pubkey::find_program_address(
        &[b"lp-pool-state", mint.as_ref()],
        program_id,
    )
}

/// Permanently locked LP token account — receives burned LP tokens
pub fn dead_lp_account_pda(mint: &Pubkey, program_id: &Pubkey) -> (Pubkey, u8) {
    Pubkey::find_program_address(
        &[b"dead-lp", mint.as_ref()],
        program_id,
    )
}

// --- AUDIT LOG PDAs ---

/// Audit log entry — per transaction signature
pub fn audit_log_pda(tx_sig: &[u8; 64], program_id: &Pubkey) -> (Pubkey, u8) {
    Pubkey::find_program_address(
        &[b"audit-log", &tx_sig[..32]],
        program_id,
    )
}

Account Discriminator Registry

Anchor-generated 8-byte discriminators for all OTCM account types. Type confusion attacks (passing a valid account of the wrong type) are prevented by discriminator validation on every instruction.

Privileged Key Inventory

Freeze Authority Specification

The Freeze Authority key grants the ability to freeze any ST22 token account, preventing outbound transfers while allowing inbound transfers. This is the most operationally sensitive key in the system.

Holder: Compliance Multisig — 3-of-5 threshold

Permitted Use Cases:

• OFAC SDN list match — mandatory freeze, no discretion
• Active law enforcement hold order — mandatory freeze
• Court-ordered asset freeze — mandatory freeze
• SAR-trigger investigation hold — discretionary, compliance officer approval required

Prohibited Use Cases:

• Competitive, commercial, or operational reasons
• Retaliation or dispute resolution
• Any use not related to regulatory compliance

Audit Requirement: Every freeze action generates an immutable on-chain audit record (Control 28) and a concurrent off-chain report to Empire Stock Transfer within 24 hours.

4-of-7 Admin Multisig Composition Requirements

The 7 keyholders for program upgrade and emergency override authority must satisfy the following distribution requirements to prevent simultaneous compromise:

Oracle Key Rotation Procedure

Oracle key rotation must occur without creating a gap in Transfer Hook validation. The following zero-downtime rotation procedure is mandatory:

PHASE 1 — Preparation (T-7 days):
  1. Generate new Ed25519 keypair in HSM — new_pubkey
  2. Submit on-chain governance transaction to ADD new_pubkey to oracle registry
  3. Oracle registry accepts both old_pubkey and new_pubkey for 7-day overlap window

PHASE 2 — Dual-Sign Period (T-0 to T+7 days):
  4. Oracle begins signing ALL attestations with BOTH old_key and new_key
  5. Both signatures included in attestation payload
  6. Transfer Hooks accept either signature during overlap window

PHASE 3 — Cutover (T+7 days):
  7. Submit on-chain governance transaction to REMOVE old_pubkey from oracle registry
  8. Oracle ceases signing with old_key
  9. old_key private key material destroyed via HSM key destruction ceremony
  10. HSM destruction certificate published on-chain as audit record

PHASE 4 — Verification (T+8 days):
  11. Verify 24-hour post-rotation: zero rejected transactions due to signature validation
  12. Rotation complete — update Key Custodianship Register

Rotation Window Safety: During Phase 2, if any Transfer Hook rejects a valid transaction due to key mismatch, the oracle immediately reverts to old_key exclusively and the rotation procedure restarts from Phase 1.

🧪 SMARTSmart CONTRACTContract TESTTest COVERAGECoverage SPECIFICATIONSpecification

Version: 6.01 | Status: Pre-Mainnet Requirements — Must Be Met Before Launch Certification

// --- TRANSFER HOOK — Required Test Cases ---

#[cfg(test)]
mod transfer_hook_tests {
    // Hook 1 — Custody
    fn test_hook1_valid_custody();
    fn test_hook1_supply_exceeds_custody();      // Must reject with Error 6001
    fn test_hook1_oracle_unavailable();           // Must reject with Error 6002
    fn test_hook1_stale_attestation();            // Must reject with Error 6019
    fn test_hook1_replay_attack();                // Must reject with Error 6019

    // Hook 2 — OFAC
    fn test_hook2_clean_sender_receiver();
    fn test_hook2_sanctioned_sender();            // Must reject with Error 6003
    fn test_hook2_sanctioned_receiver();          // Must reject with Error 6004
    fn test_hook2_fuzzy_name_match();             // Near-match must trigger

    // Hook 5 — Price Impact
    fn test_hook5_within_2pct_limit();
    fn test_hook5_exceeds_2pct_limit();           // Must reject with Error 6026
    fn test_hook5_twap_unavailable();             // Must reject with Error 6040

    // Cross-hook interaction
    fn test_all_hooks_pass_valid_transfer();
    fn test_atomic_revert_on_hook3_fail();        // Hooks 1-2 pass, Hook 3 fails
    fn test_hook_ordering_enforced();             // Out-of-order hook call must fail

    // Controls 7–42
    fn test_control_7_invalid_signer();
    fn test_control_14_zero_amount();
    fn test_control_15_self_transfer();
    fn test_control_22_concentration_limit();
    fn test_control_36_global_circuit_breaker();
    // ... one test per control (42 total mandatory)
}

// --- CPMM AMM — Required Test Cases ---

#[cfg(test)]
mod amm_tests {
    fn test_swap_invariant_maintained();          // k must not decrease
    fn test_u128_no_overflow_at_max_reserves();  // MAX_SAFE_RESERVE × MAX_SAFE_RESERVE
    fn test_rounding_direction_floor_output();
    fn test_fee_calculation_accuracy();
    fn test_graduation_atomic_migration();
    fn test_lp_tokens_burned_to_dead_address();
    fn test_permanent_lock_no_withdrawal();       // Attempt withdrawal must fail
}

# Cargo.toml fuzz configuration
[workspace.metadata.fuzz]
targets = [
    "fuzz_transfer_hook",     # Fuzz all 42 controls with random account states
    "fuzz_cpmm_swap",         # Fuzz reserve values from 1 to MAX_SAFE_RESERVE
    "fuzz_oracle_attestation",# Fuzz oracle payloads including malformed signatures
    "fuzz_bonding_curve",     # Fuzz token amounts across full price range
]
minimum_corpus_size = 10_000
max_total_time_seconds = 3_600  # 1 hour minimum per target pre-launch
crash_on_oom = true

# Reference implementation for differential testing
def calculate_swap_output_reference(amount_in, reserve_in, reserve_out, fee_bps):
    fee_numerator = 10000 - fee_bps
    amount_in_with_fee = amount_in * fee_numerator
    numerator = amount_in_with_fee * reserve_out
    denominator = reserve_in * 10000 + amount_in_with_fee
    return int(numerator / denominator)  # floor division matches Rust behavior

HOOK EXECUTION MODEL:

  Transaction Input Accounts (immutable snapshot for all hooks)
         │
         ├---──► Hook 1  reads: oracle_cache_pda (readonly), compliance_state (readonly)
         │    Hook 1           writes: audit_log_pda (append-only)
         │
         ├---──► Hook 2  reads: ofac_oracle_pda (readonly), · investor_record (readonly)
         │    Hook 2           writes: audit_log_pda (append-only)
         │
         ├---──► Hook 3  reads: aml_oracle_pda (readonly), · investor_record (readonly)
         │    Hook 3           writes: audit_log_pda (append-only)
         │
         ├---──► Hook 4  reads: investor_record (readonly), · compliance_state (readonly)
         │    Hook 4           writes: audit_log_pda (append-only)
         │
         ├---──► Hook 5  reads: price_oracle_pda (readonly), · lp_pool_state (readonly)
         │    Hook 5           writes: audit_log_pda (append-only)
         │
         └---──► Hook 6  reads: lp_pool_state (readonly)
              Hook 6
                     writes: audit_log_pda (append-only)

KEY PROPERTY: All cross-hook reads are from (readonly) accounts.
              No hook reads data that a prior hook has written in the same transaction.written.
              audit_log_pda is append-only — no hook reads what another hook wrote.

/// CORRECT — CEI pattern enforced
pub fn process_swap(ctx: Context, amount_in: u64) -> Result<()> {
    // --- CHECKS ---
    // 1. Validate all account constraints (Anchor #[account] macros)
    // 2. Verify oracle data freshness and consensus
    // 3. Compute output amount — read-only, no state changes
    let amount_out = calculate_swap_output(
        amount_in,
        ctx.accounts.pool.sol_reserve,
        ctx.accounts.pool.token_reserve,
        ctx.accounts.pool.fee_bps,
    )?;

    // Verify circuit breaker — no state write yet
    let price_impact = compute_price_impact(amount_in, ctx.accounts.pool.sol_reserve)?;
    require!(price_impact <= MAX_PRICE_IMPACT_BPS, AmmError::PriceImpactExceeded);

    // --- EFFECTS ---
    // 4. Write ALL state mutations BEFORE any CPI calls
    // State is fully consistent before any external call can observe it
    let pool = &mut ctx.accounts.pool;
    pool.sol_reserve = pool.sol_reserve
        .checked_add(amount_in)
        .ok_or(AmmError::Overflow)?;
    pool.token_reserve = pool.token_reserve
        .checked_sub(amount_out)
        .ok_or(AmmError::Underflow)?;
    pool.k_invariant = (pool.sol_reserve as u128)
        .checked_mul(pool.token_reserve as u128)
        .ok_or(AmmError::Overflow)?;
    pool.last_swap_slot = Clock::get()?.slot;

    // --- INTERACTIONS ---
    // 5. Execute CPIs ONLY after all state mutations are complete
    // If CPI calls back into this program, state is already correct
    token::transfer(
        CpiContext::new(
            ctx.accounts.token_program.to_account_info(),
            token::Transfer {
                from: ctx.accounts.pool_token_account.to_account_info(),
                to: ctx.accounts.user_token_account.to_account_info(),
                authority: ctx.accounts.pool_authority.to_account_info(),
            },
        ),
        amount_out,
    )?;

    // Emit audit event last — read-only CPI, no state impact
    emit!(SwapExecuted {
        user: ctx.accounts.user.key(),
        amount_in,
        amount_out,
        slot: Clock::get()?.slot,
    });

    Ok(())
}

/// INCORRECT pattern — NEVER use this
/// pub fn process_swap_WRONG(ctx: Context, amount_in: u64) -> Result<()> {
///     let amount_out = calculate_swap_output(...)?;
///     // CPI BEFORE state mutation — reentrancy window open
///     token::transfer(cpi_ctx, amount_out)?;  // <-- WRONG
///     pool.sol_reserve += amount_in;           // <-- state written after CPI
///     Ok(())
/// }

#[account]
pub struct PoolState {
    // ... other fields ...
    /// Reentrancy guard — set to true on entry, false on exit
    /// Prevents recursive invocation of pool instructions
    pub locked: bool,
}

/// Reentrancy guard macro — wrap any instruction using CPIs
macro_rules! reentrancy_guard {
    ($account:expr, $body:block) => {{
        require!(!$account.locked, AmmError::ReentrantCall);
        $account.locked = true;
        let result = { $body };
        $account.locked = false;
        result
    }};
}

// Usage in instruction handler:
pub fn complex_operation(ctx: Context) -> Result<()> {
    reentrancy_guard!(ctx.accounts.pool, {
        // ... instruction body with CPIs ...
        Ok(())
    })
}