Status State Machines

All status fields and their valid transitions across the system.

Deposit Status deposits.status

Deposit flow differs by pool type. Both share the same 5-state enum but trigger different sub-steps.

AS Pool (Pool Smart Contract — non-custodial)

PENDING → PROCESSING → COMPLETED

PROCESSING → FAILED (transfer or mint error)

🟢 System Flow

USDC enters Pool Contract → LP auto-minted (PLATFORM_ISSUED) → COMPLETED. No receipt token.

Fund Pool (Fund Manager-managed)

PENDING → PROCESSING → COMPLETED

PENDING → REFUNDED (D+7, LP not issued)

🟣 FM Flow

USDC deposited → FM notified (fm_notified_at) → FM issues LP (FUND_ISSUED) → LP minted (lp_minted_at) → receipt burned (receipt_burned_at) → COMPLETED.

Status Definitions

Status	Description
PENDING	Deposit received, awaiting LP issuance.
PROCESSING	LP issuance or transfer in progress.
COMPLETED	LP issued, receipt burned, USDC released to pool/fund.
REFUNDED	LP not issued within 7 days (D+7 rule), USDC returned to investor.
FAILED	Transfer, mint, or notification error. failure_type + error_message logged.

KYC Status users.kyc_status

NOT_STARTED → IN_REVIEW → APPROVED

IN_REVIEW → REJECTED

Status Definitions

Status	Description
NOT_STARTED	User registered, KYC not yet initiated.
IN_REVIEW	SumSub verification underway.
APPROVED	KYC passed, SBT minted on-chain.
REJECTED	Failed verification. See reject_type (RETRY / FINAL).

Redemption Request Status redemption_requests.status

Redemption flow differs by pool type and escrow model. All flows start with REQUESTED and end with COMPLETED or FAILED.

Fund Pool

FM acknowledges → sends funds directly

REQUESTED → FM_ACCEPTED → PROCESSING → COMPLETED

🟣 FM Flow

FM sees request → acknowledges (FM_ACCEPTED) → sends USDC from fund wallet → payout_tx_hash confirmed → COMPLETED. transfer_source = 'FUND'

AS Pool — Smart Contract Escrow

REQUESTED → PROCESSING → COMPLETED

🟢 System Flow

Contract validates LP burn → auto-releases USDC → PROCESSING → on-chain confirmation → COMPLETED. transfer_source = 'PLATFORM' · Timeline: contract_validated_at → auto_released_at

AS Pool — Multi-Sig Escrow Deprecated

REQUESTED → PROCESSING → COMPLETED

Approval requested to co-signers → M-of-N threshold met → USDC released → COMPLETED. transfer_source = 'PLATFORM' · Timeline: approval_requested_at → cosigned_at

Fund Pool — No Escrow Deprecated

REQUESTED → PROCESSING → COMPLETED

Fund notified → fund sends USDC directly → transfer confirmed on-chain → COMPLETED. transfer_source = 'FUND' · Timeline: fund_notified_at → fund_sent_at → transfer_confirmed_at

🚨 Failure Path (all flows)

PROCESSING → FAILED (transfer error, timeout, or notification failure)

failure_type + error_message logged. Admin can retry or escalate.

Status Definitions

Status	Description
REQUESTED	Investor submitted request. nav_at_request locked. Display as "Pending".
FM_ACCEPTED	Fund Manager acknowledged (Fund Pool only).
PROCESSING	Funds being sent (escrow release or direct transfer).
COMPLETED	USDC received by investor. payout_tx_hash recorded.
REJECTED	Legacy failed status (display as "Failed", kept for backward compat).
FAILED	Transfer or notification error (R15 new, preferred over REJECTED).

Pool Status Flags pools table

Two flags control pool behavior — investment stays open during NAV changes.

Flag	Description
is_paused	Manual admin toggle. Paused pools hidden from dashboard (unless user has position). No new deposits allowed. The only way to block investment — NAV changes never auto-block.
nav_per_token	Decimal (default $1.00, capped at $1.00 max, no floor). Updated by Oracle via updateNAV() with 24h timelock for decreases; increases apply immediately. Drives token minting and redemption payout calculations.

Fund Status funds.status

ACTIVE ↔ INACTIVE

Status Definitions

Status	Description
ACTIVE	Fund operational, pools visible and accepting investments.
INACTIVE	Fund suspended. Existing positions remain. Reversible by admin.

R15 Change

Replaced old 3-state issuer status (ACTIVE/PAUSED/OFFBOARDED) with simpler 2-state fund status. "Offboarded" is now handled by setting INACTIVE + closing all associated pools via lifecycle_status = 'CLOSED'.

NAV Update Status nav_history.status

PENDING → APPLIED

Status Definitions

Status	Description
PENDING	NAV decrease submitted. 24h timelock active. Admin can cancel during this window.
APPLIED	Timelock expired, new NAV applied to pool. NAV increases skip PENDING and apply immediately.

Yield Distribution Status yield_distributions.status

Yield distribution flow. Applies to both yield_distributions (pool-level) and yield_distribution_investors (per-investor).

DISTRIBUTING Model (auto pro-rata) Deprecated

PENDING → PROCESSING → DISTRIBUTED

Admin creates distribution → system calculates pro-rata shares → tx submitted (tx_submitted_at) → on-chain confirmed → DISTRIBUTED.

MANUAL_CLAIM Model (investor-initiated)

PENDING → PROCESSING → DISTRIBUTED

🔵 Investor Flow

Admin creates distribution → yields available for claim → investor claims (claimed_at) → DISTRIBUTED.

🚨 Failure Path

PROCESSING → FAILED

failure_type: FM_NOTIFICATION_FAILED, DISTRIBUTION_TX_FAILED, CLAIM_PROCESSING_FAILED. Admin can retry.

Status Definitions

Status	Description
PENDING	Distribution created, awaiting processing.
PROCESSING	Transaction being submitted or claim being processed.
DISTRIBUTED	Yield confirmed delivered/claimed.
FAILED	Transaction or notification error. failure_type + error_message logged.

SBT (Soulbound Token) Status users.sbt_status

NOT_MINTED → MINTED

NOT_MINTED → FAILED (mint tx reverted or timed out)

Status Definitions

Status	Description
NOT_MINTED	KYC not approved or mint not triggered yet.
MINTED	On-chain confirmed, sbt_tx_hash stored.
FAILED	Mint tx reverted or timed out. sbt_error logged. Admin can retry.

R15 Note

MINTING intermediate state removed — near-instant on Base L2. reject_type: RETRY (user can resubmit) vs FINAL (permanently rejected).

Pool Lifecycle Status pools.lifecycle_status

DRAFT → UPCOMING → ACTIVE → MATURED

ACTIVE + writedown (NAV < 1.0) + is_paused toggle replaces former DISTRESSED state

Any state → CLOSED (admin manual close)

Status Definitions

Status	Description
DRAFT	Saved, not published. Editable + deletable.
UPCOMING	Published, visible to investors, before start_date.
ACTIVE	Open for investment. start_date reached. Writedown scenario: NAV < 1.0 → "Active + Writedown" badge + alert banner. Severe: admin sets is_paused = true → "Paused" banner + invest/redeem blocked.
CLOSED	Admin manually closed.
MATURED	end_date reached. Auto-redemption triggered.

Auto-Transitions (Scheduler)

Transition	Trigger
DRAFT → UPCOMING	🔴 Admin clicks "Publish" → published_at set. Requires start_date.
UPCOMING → ACTIVE	🟢 Scheduler checks daily — when start_date reached, auto-transitions.
ACTIVE → MATURED	🟢 When end_date reached (if set), auto-transitions. Auto-redemption triggered.
Any → CLOSED	🔴 Admin manually closes pool. display_after_close determines visibility.