Transfer Hook Reference
Transfer Hook Reference
The 42 Security Controls · SPL Token-2022 · Module-Aware
A standalone reference for the platform's Transfer Hook program — the single most consequential security primitive in the RWA Tokens architecture. This page documents what each of the 42 controls does, when it triggers, what it returns when it fails, and how it differs across the three production modules: Equities (Module 1), Real Estate (Module 2), and CORECM — Carbon Ore, Rare Earth, and Critical Minerals (Module 3).
For program-level documentation (instruction signatures, account schemas, PDA registry, event registry, state machines), see the Smart Contract Reference. For the formal specification submitted to regulators and auditors, see the SPL Token-2022 Transfer Hook Technical Specification.
Why This Page Exists
The 42 controls are referenced in dozens of platform documents — the Whitepaper, the Compliance Integration Guide, the Security Model, the Empire Stock Transfer Integration, the Architecture Decisions, the Incident Response Playbook, and the Smart Contract Reference. Each document covers the controls from its own angle.
This page is the canonical reference. When a control number appears anywhere in platform documentation, this is the page that defines it.
The Foundational Property
The Transfer Hook is the platform's foundational security guarantee. It rests on three properties of the SPL Token-2022 standard:
Mandatory invocation. Once a Token-2022 mint specifies a Transfer Hook program, the SPL Token-2022 runtime invokes the hook on every transfer of that token. The runtime — not the platform — enforces this.
Permanent attachment. A Transfer Hook cannot be removed from a mint after creation. SPL Token-2022 has no
removeTransferHookinstruction. Anyone — including Groovy Company, Inc. itself — is structurally incapable of detaching the hook.Atomic revert. If the hook returns an error, the entire transfer transaction reverts. There is no path to a partially-completed transfer.
The combination means: every ST22 token transfer ever, for the entire existence of every ST22 mint, is validated against the 42 controls. There is no bypass. There is no exception. There is no override at the mint level.
How the Hook Executes
The 42 controls execute in two phases on every transfer:
Phase 1 controls are evaluated in order — each must pass before the next is evaluated. Phase 2 controls are evaluated together; a failure in any one reverts the whole transfer.
The hook reads multiple state accounts during validation: SecurityConfig, HoldingPeriodAccount, CustodyOracle, OFACOracle, AMLOracle, and (for Module 2 and Module 3) NAVOracle and ClassificationOracle. All reads are deterministic — the hook does not perform off-chain calls during execution.
Section 1 — Custody Verification (CV-01 through CV-06)
Purpose. Verify that every ST22 transfer is backed 1:1 by Common Class B shares held in Empire Stock Transfer custody. This is the structural difference between an ST22 and a synthetic on-chain token: the underlying shares physically exist, are held by a §17A-registered transfer agent, and are continuously attested.
Mechanism. Empire signs an Ed25519 attestation on every Solana block (~400ms). The attestation contains the custodied Common Class B balance for the affected mint. The Transfer Hook reads this attestation on every transfer and verifies the 1:1 invariant.
IDControlTriggerError
CV-01
Custody balance match
Empire-attested Common B balance is less than on-chain ST22 supply
6001 — CustodyDiscrepancy
CV-02
1:1 ratio confirmation
Token supply exceeds custodied Common B for the affected mint
6001 — CustodyDiscrepancy
CV-03
Empire operational status
Empire reports degraded or suspended state
6038 — CustodyDiscrepancyHalt
CV-04
Ed25519 oracle health
Oracle attestation is stale beyond 1 Solana slot
6002 — CustodyOracleUnavailable
CV-05
Asset-identifier match
Custodied shares do not match the assigned identifier (CUSIP, property ID, or basin ID)
6038 — CustodyDiscrepancyHalt
CV-06
MSF wallet registration
Sender or receiver wallet not registered in Empire's Master Securityholder File
6007 — InvalidSigner
Production record. Across three beta issuances and over $7M of processed liquidity, zero custody discrepancy events have been recorded. The 1:1 backing invariant has been maintained at every Solana block.
Module behavior. Identical across all three modules. CV-05 verifies the assigned identifier — CUSIP for Module 1, property identifier for Module 2, basin identifier for Module 3.
Section 2 — Investor Verification (IV-07 through IV-14)
Purpose. Verify that the sender and receiver wallets are linked to Empire-verified identities meeting the appropriate offering exemption criteria. KYC, KYB, AML scoring, and OFAC screening are performed exclusively by Empire Stock Transfer — the platform does not perform investor onboarding.
Mechanism. Empire's Master Securityholder File (MSF) is the authoritative record of which wallets are registered, what jurisdiction the wallet's owner falls under, and what offering exemption applies. The Transfer Hook reads MSF state via the AML oracle and the SecurityConfig blacklist.
IDControlTriggerError
IV-07
KYC required
Wallet has no Empire KYC verification
6007 — InvalidSigner
IV-08
Accreditation eligibility
Investor not eligible under the mint's exemption — Reg D (US accredited), Reg S (non-US), Reg CF (US retail)
6007 — InvalidSigner
IV-09
AML risk score
Risk score above 70/100 (Chainalysis KYT or TRM Labs)
6006 — AMLHighRisk
IV-10
Identity-wallet linkage
Verified identity not linked to the wallet
6007 — InvalidSigner
IV-11
Jurisdiction
Wallet's jurisdiction is comprehensively sanctioned (Iran, North Korea, Syria, Cuba, Crimea, etc.)
6007 — InvalidSigner
IV-12
Age verification
Wallet owner under 18
6007 — InvalidSigner
IV-13
Investor classification
Track investor classification (accredited / institutional / non-US / Reg CF)
(Tracking only — no error)
IV-14
KYC expiry
KYC verification expired (annual re-verification required)
6007 — InvalidSigner
Module behavior. Module 1 and Module 2 share identical investor verification. Module 3 (CORECM) requires enhanced KYC depth — beneficial-ownership disclosure to ultimate owner is required for entity investors, given the federal-action sensitivity of critical-minerals assets.
Section 3 — Position Limits (PL-15 through PL-19)
Purpose. Enforce wallet concentration, velocity, and clustering limits to prevent market manipulation and coordinated activity.
Mechanism. SecurityConfig stores per-mint position parameters. The Transfer Hook reads these parameters on every transfer and rejects any transfer that would breach a position limit.
IDControlDefaultAdjustable RangeError
PL-15
Wallet whitelist
Wallet must be MSF-registered
Not adjustable
6007 — InvalidSigner
PL-16
Concentration cap
4.99% of supply (499 bps)
1.00% – 9.99% (100 – 999 bps)
6020 — WalletLimitExceeded
PL-17
Velocity cap
50 tx/hour per wallet
Governance-adjustable
6022 — VelocityExceeded
PL-18
Cross-wallet clustering
2-hop graph analysis
Not adjustable
6023 — CrossWalletDetected
PL-19
Cumulative position
Aggregate across linked wallets
Not adjustable
6020 — WalletLimitExceeded
Module behavior. Module 1 and Module 3 use the standard 4.99% cap. Module 2 (Real Estate) uses an issuer-configurable cap up to 9.99% — single-asset real-estate offerings often have natural concentration patterns where a single institutional investor holds a significant share.
Section 4 — Circuit Breakers (CB-20 through CB-23)
Purpose. Halt trading on extreme price movements, excessive single-trade impact, and oracle failures.
Mechanism. SecurityConfig stores per-mint circuit-breaker thresholds and cooldown durations. The Transfer Hook reads the TWAP from Pyth Network on every transfer and compares the proposed trade against the threshold.
IDControlDefaultAdjustable RangeError
CB-20
Price halt
30% move in 5 minutes; 24h cooldown
10% – 50%; 1h – 72h cooldown
6005 — CircuitBreakerActive
CB-21
Price impact cap
2% vs TWAP
1% – 5%
6021 — PriceImpactExceeded
CB-22
Velocity halt
Wallet > 30% daily sell
Not adjustable
6037 — DailySellLimitExceeded
CB-23
Oracle failure halt
Halt on custody oracle stale beyond 1 slot
Not adjustable
6038 — CustodyDiscrepancyHalt
Module behavior.
Module 1 — standard circuit breakers.
Module 2 — adds NAV-deviation breaker as part of CB-21. When the on-chain price deviates from the appraised NAV by more than
nav_deviation_max_bps, the affected mint is paused on the AMM until a fresh appraisal restores the price within bounds. Returns Error 6021.Module 3 — CB-23 also pauses on Classification oracle failure beyond
classification_max_age_secs.
NAV-Deviation Breaker State Machine (Module 2)
Section 5 — Holding Period Enforcement (HP-24 through HP-29)
Purpose. Enforce statutory holding periods at the Solana runtime level. Investors cannot transfer ST22 tokens before the holding period elapses, regardless of platform state, governance action, or counterparty agreement.
Mechanism. Each investor-mint pair has a HoldingPeriodAccount PDA. The PDA records the purchase timestamp (set by the Solana runtime clock — never user input), the jurisdiction flag (US, Non-US, or Reg CF), and the holding period in seconds.
IDControlTriggerError
HP-24
Holding period elapsed
(now - purchase_timestamp) < holding_period_secs
6024 — TokensLocked
HP-25
Jurisdiction flag verification
Jurisdiction flag does not match HoldingPeriodAccount config
6007 — InvalidSigner
HP-26
Purchase timestamp immutability
Verified at PDA creation; cannot be modified post-creation
(Verified once)
HP-27
Timer non-shortenable
Holding period seconds are hard-coded constants
(Verified at compile time)
HP-28
Per-investor-mint tracking
One HoldingPeriodAccount per (investor, mint) pair
(Verified at PDA derivation)
HP-29
Reg S US-person check
Reg S investor attempting flowback to US person before period elapses
6024 — TokensLocked
Holding period values (immutable program constants):
JurisdictionHolding PeriodStatutory Basis
US Reg D (accredited)
15,778,800 seconds (~6 months)
SEC Rule 144(d)(1)(ii)
Non-US Reg S
31,536,000 seconds (~12 months)
SEC Regulation S Category 2
US Reg CF (retail)
31,536,000 seconds (~12 months)
SEC Regulation Crowdfunding §227.501
Module behavior. Identical across all three modules. The same holding-period constants apply to Equities, Real Estate, and CORECM ST22 tokens.
Section 6 — Sanctions Compliance (SC-30 through SC-34)
Purpose. Enforce OFAC sanctions screening on every transfer using continuous re-screening against the current SDN list.
Mechanism. The OFAC Oracle aggregator service polls the U.S. Treasury OFAC SDN list hourly (with emergency push on Treasury-flagged updates). The Transfer Hook reads the OFAC oracle and the SecurityConfig blacklist on every transfer.
IDControlTriggerError
SC-30
Exact address match
Sender or receiver Solana wallet matches an SDN-listed wallet
6003 — SenderSanctioned, 6004 — ReceiverSanctioned
SC-31
Fuzzy entity match
Entity name or alias matches an SDN entity (for entity investors)
6003 / 6004
SC-32
2-hop graph clustering
Transaction graph analysis for proxy-wallet detection
6003 / 6004
SC-33
Continuous re-screening
Re-screen every wallet on every transfer against current SDN list
6005 — OfacOracleStale (if oracle stale > threshold)
SC-34
Blacklist enforcement
Confirmed matches added to per-mint blacklist; permanent block
6003 / 6004
Production record. Zero false-positive OFAC blocks across the beta period; one true-positive block (Iranian corporate structure mid-2025).
Module behavior. Identical across all three modules. Treasury maintains a special interest in critical-minerals supply-chain sanctions; Module 3 incidents may trigger coordinated regulatory action under §13.
Section 7 — Protective Conversion (PC-35 through PC-38)
Purpose. Automatically convert ST22 tokens to underlying common stock upon defined adverse events, ensuring investors retain genuine equity ownership even if the platform fails.
Mechanism. The Transfer Hook reads the protective_conversion_triggered flag on the SecurityConfig. When set, the hook prevents transfers and signals Empire Stock Transfer to begin the conversion procedure documented in the Empire Integration §11.
IDControlTriggerBehavior
PC-35
Issuer bankruptcy
Issuer files Chapter 7 or Chapter 11
Automatic conversion to common stock
PC-36
SEC enforcement / criminal indictment
SEC enforcement action or criminal indictment against officer or director
Automatic conversion
PC-37
Empire service loss
Empire Stock Transfer ceases providing custody services for any reason
Automatic conversion
PC-38
Tripartite breach
Material breach of the Issuer–Empire–Platform tripartite agreement
Discretionary conversion (Legal Counsel + 3-of-5)
Mechanism detail. The protective-conversion controls do not block transfers in normal operation. They activate only when the SecurityConfig flag is set by Legal Counsel plus 3-of-5 multi-signature. Once set, the conversion procedure is triggered, custody is preserved, and ST22 tokens are converted to physical common stock certificates issued by the appropriate transfer agent.
Module behavior. Module 1 and Module 2 use the same protective-conversion logic. Module 3 adds an additional implicit trigger: a federal action that effectively prohibits operation of the underlying basin asset can trigger PC-37 via Empire's discretion.
Section 8 — Record-Keeping and Governance (RK-39 through REG-42)
Purpose. Provides immutable audit trail and emergency containment authority.
IDControlTriggerBehavior
RK-39
On-chain audit trail
Every transfer (success or failure)
TransferValidated event emitted
RK-40
Hash-chain integrity
Audit-record hash chain
Prevents retroactive modification
GOV-41
Controlled migration
Program upgrade in progress
6041 — ControlledMigration
REG-42
Regulatory freeze
Legal Counsel + 3-of-5 multi-sig authority
6042 — RegulatoryOverride
REG-42 (Regulatory Freeze) properties.
No timelock — immediate execution on multi-signature approval.
Per-mint scope by default; can be platform-wide if requested.
Reversible — the same multi-signature can lift the freeze.
Logged on chain with the freezing authority's identity and timestamp.
Module-specific automation. Module 3 has automatic federal-action freeze coordination. The platform's federal-action monitoring service polls the Federal Register, DOE program announcements, and USGS classification updates on a 5-minute cadence. Detected federal actions matching a basin or mineral class associated with an issued Module 3 mint trigger an automatic P0 incident, and Legal Counsel plus 3-of-5 multi-signature execute REG-42 on each affected mint within 60 minutes per the Incident Response Playbook §13.
Federal-Action Freeze State Machine (Module 3)
Adjustable vs Immutable Parameters
A complete summary of which parameters are adjustable through governance and which are hard-coded program constants.
Governance-Adjustable
ParameterDefaultMinMax
Wallet concentration cap
4.99% (499 bps)
1.00% (100 bps)
9.99% (999 bps)
Circuit breaker threshold
30% (3000 bps)
10% (1000 bps)
50% (5000 bps)
Circuit breaker cooldown
24h (86,400s)
1h (3,600s)
72h (259,200s)
Price impact maximum
2% (200 bps)
1% (100 bps)
5% (500 bps)
TWAP window
30m (1,800s)
15m (900s)
1h (3,600s)
Velocity cap
50 tx/hr
(governance-set)
(governance-set)
Module 2: NAV deviation max
(per-mint)
(governance-set)
(governance-set)
Module 2: NAV reappraisal max age
(per-mint)
(governance-set)
(governance-set)
Module 3: Classification max age
(per-mint)
(governance-set)
(governance-set)
Immutable (Hard-Coded Program Constants)
ParameterValue
Holding period — Reg D (Rule 144)
15,778,800 seconds (6 months)
Holding period — Reg S
31,536,000 seconds (12 months)
Holding period — Reg CF
31,536,000 seconds (12 months)
TWAP minimum observations
60
Cross-wallet clustering algorithm
2-hop graph analysis
Liquidity Pool — withdrawal
(No function exists)
Why immutability matters. The hard-coded constants are outside the parameter space governance can adjust. Even with full multi-signature authority and 100% supermajority, governance cannot reduce a Reg D holding period below six months. Any upgrade attempting this fails Certora invariant E.4 verification at the formal-verification gate, before being executable.
Errors Summary
The Transfer Hook returns one of the following errors when a control fails. Application clients should map error codes to user-facing messages; the codes themselves are stable across program versions.
CodeNameMost Likely Cause
6001
CustodyDiscrepancy
Empire-attested balance below on-chain supply (incident escalation)
6002
CustodyOracleUnavailable
Empire relay outage; oracle stale beyond 1 slot
6003
SenderSanctioned
Sender on OFAC SDN list
6004
ReceiverSanctioned
Receiver on OFAC SDN list
6005
OfacOracleStale
OFAC oracle has not refreshed within the staleness threshold
6006
AMLHighRisk
Risk score from Chainalysis or TRM Labs above 70/100
6007
InvalidSigner
KYC missing, expired, jurisdiction-blocked, or wallet not registered in MSF
6020
WalletLimitExceeded
Receiving wallet would exceed concentration cap
6021
PriceImpactExceeded
Single trade exceeds price-impact cap vs TWAP (Module 2: vs NAV)
6022
VelocityExceeded
Per-wallet transaction rate exceeded
6023
CrossWalletDetected
Multiple wallets cluster as a single position above the limit
6024
TokensLocked
Holding period (Reg D, Reg S, or Reg CF) has not elapsed
6037
DailySellLimitExceeded
Wallet daily sell volume above 30% threshold
6038
CustodyDiscrepancyHalt
Awaiting custody oracle consensus
6041
ControlledMigration
Program upgrade in progress
6042
RegulatoryOverride
Legal Counsel + 3-of-5 freeze active
Module-Aware Summary
For each module, this is the relationship between the 42 controls and module-specific behavior.
Module 1 — Equities
All 42 controls apply identically.
No additional oracles.
EDGAR pipeline supplies issuer-disclosure intelligence to Layer 9 IDOS off-chain compliance system.
Module 2 — Real Estate
All 42 controls apply.
Adds NAV Oracle (per mint).
CB-21 enforces NAV-deviation circuit breaker.
PL-16 concentration cap may be issuer-configured up to 9.99%.
Module 3 — CORECM (Carbon Ore, Rare Earth, and Critical Minerals)
All 42 controls apply.
Adds Classification Oracle (per mint).
IV-08 requires enhanced KYC depth (beneficial-ownership to ultimate owner).
REG-42 has automatic federal-action freeze coordination.
Federal action sources: Federal Register, DOE Critical Materials Strategy program announcements, USGS Critical Minerals List updates, Department of Defense procurement directives, executive orders, court orders.
Cross-Reference
TopicDocument
Program-level documentation (instructions, account schemas, PDA registry)
Smart Contract Reference
Formal specification (auditor and regulator audience)
SPL Token-2022 Transfer Hook Technical Specification
Regulatory mapping (which control satisfies which regulation)
Compliance Integration Guide §3
Threat model (what each control defends against)
Security Model §4
Custody attestation lifecycle
Empire Stock Transfer Integration §5
Federal-action runbook
Incident Response Playbook §13
NAV oracle architecture (Module 2)
Oracle Integration Guide §6
Classification oracle architecture (Module 3)
Oracle Integration Guide §7
Architecture decisions (why these controls, why this architecture)
Architecture Decisions ADR-001 through ADR-012
RWA Tokens · Transfer Hook Reference · Groovy Company, Inc.
Last updated
Was this helpful?