# Transfer Hook Reference

### Transfer Hook Reference <a href="#transfer-hook-reference" id="transfer-hook-reference"></a>

**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 <a href="#why-this-page-exists" id="why-this-page-exists"></a>

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 <a href="#the-foundational-property" id="the-foundational-property"></a>

The Transfer Hook is the platform's foundational security guarantee. It rests on three properties of the SPL Token-2022 standard:

1. **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.
2. **Permanent attachment.** A Transfer Hook cannot be removed from a mint after creation. SPL Token-2022 has no `removeTransferHook` instruction. Anyone — including Groovy Company, Inc. itself — is structurally incapable of detaching the hook.
3. **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 <a href="#how-the-hook-executes" id="how-the-hook-executes"></a>

The 42 controls execute in two phases on every transfer:

<a class="button secondary">Copy</a>

```
PHASE 1 — SEQUENTIAL (critical path):
  CV-01 through CV-06   →   Custody verification
  IV-07 through IV-14   →   Investor eligibility
  HP-24                 →   Holding period

PHASE 2 — PARALLEL (any failure reverts atomically):
  PL-15 through PL-19   →   Position limits
  CB-20 through CB-23   →   Circuit breakers
  SC-30 through SC-34   →   Sanctions compliance
  PC-35 through PC-38   →   Protective conversion
  RK-39 through REG-42  →   Audit trail and governance

EMIT:
  TransferValidated event with all 42 results
```

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) <a href="#section-1-custody-verification-cv-01-through-cv-06" id="section-1-custody-verification-cv-01-through-cv-06"></a>

**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) <a href="#section-2-investor-verification-iv-07-through-iv-14" id="section-2-investor-verification-iv-07-through-iv-14"></a>

**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) <a href="#section-3-position-limits-pl-15-through-pl-19" id="section-3-position-limits-pl-15-through-pl-19"></a>

**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) <a href="#section-4-circuit-breakers-cb-20-through-cb-23" id="section-4-circuit-breakers-cb-20-through-cb-23"></a>

**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)**

<a class="button secondary">Copy</a>

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

***

#### Section 5 — Holding Period Enforcement (HP-24 through HP-29) <a href="#section-5-holding-period-enforcement-hp-24-through-hp-29" id="section-5-holding-period-enforcement-hp-24-through-hp-29"></a>

**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) <a href="#section-6-sanctions-compliance-sc-30-through-sc-34" id="section-6-sanctions-compliance-sc-30-through-sc-34"></a>

**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) <a href="#section-7-protective-conversion-pc-35-through-pc-38" id="section-7-protective-conversion-pc-35-through-pc-38"></a>

**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) <a href="#section-8-record-keeping-and-governance-rk-39-through-reg-42" id="section-8-record-keeping-and-governance-rk-39-through-reg-42"></a>

**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)**

<a class="button secondary">Copy</a>

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

***

#### Adjustable vs Immutable Parameters <a href="#adjustable-vs-immutable-parameters" id="adjustable-vs-immutable-parameters"></a>

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 <a href="#errors-summary" id="errors-summary"></a>

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 <a href="#module-aware-summary" id="module-aware-summary"></a>

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 <a href="#cross-reference" id="cross-reference"></a>

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.*


---

# Agent Instructions: Querying This Documentation

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

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

```
GET https://bitbook.rwatokens.net/compliance_and_custody/compliance-and-custody/transfer-hook-reference.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

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