Fund Status Transition

This document defines the state machine for the Fund entity. The lifecycle governs a fund from its initial creation to its final conclusion, ensuring that all actions and data modifications occur in a controlled, compliant, and logical sequence. Each state represents a distinct phase in the fund's operational journey.

Lifecycle Diagram

The standard path for a fund is a linear progression from creation to a successful closing. However, loops and alternative paths exist for scenarios like legal rejection or unsuccessful funding.

Primary Flow:

new → draft → legal_review → legal_accepted → published → legal_closed → closed_successfully

Alternative Paths:

• legal_review → legal_declined → draft or legal_review (Rejection Loop)

• legal_closed → closed_unsuccessfully (Failure Path)

Status Definitions

Status	Description
new	The initial state after a Fund is created.
draft	The fund is being configured by an administrator and is not visible to legal reviewers or investors.
legal_review	The Fund was submitted for compliance and legal approval. Its core terms are locked during review.
legal_declined	The legal side rejected the Fund. The rejection reason is logged before the fund returns to an editable state.
legal_accepted	The Fund was approved by the legal side and is staged for publication.
published	The Fund is live on the investor portal and accepts investments.
legal_closed	The Fund no longer accepts new investments.
closed_successfully	The fund closed successfully after its closing conditions were met.
closed_unsuccessfully	The Fund closed without meeting its funding conditions, and committed-fund return processing begins.

Fund status is separate from the Investment status and its funding_status; neither investment lifecycle adds a Fund status. Both closed_successfully and closed_unsuccessfully are terminal Fund statuses.

Key Transitions

Transitions are the actions or system events that move a fund from one state to the next.

• Create Fund (new → draft or legal_review)

  • Trigger: A fund is created through the fund service.

  • Action: The fund starts in new and enters draft for configuration or legal_review when submitted with the required fields.

• Submit for Review (draft → legal_review)

  • Trigger: An administrator clicks the "Send for Approval" button on the fund details page in the issuer portal.

  • Action: The system validates that all mandatory fields are complete. The fund's financial and legal fields are locked to prevent changes during review.

• Decline Fund (legal_review → legal_declined)

  • Trigger: The legal side rejects the fund.

  • Action: The system requires a reason for the rejection, which is logged. The fund status changes to legal_declined, and the fields are unlocked for editing.

• Approve Fund (legal_review → legal_accepted)

  • Trigger: The legal side approves the fund.

  • Action:

    • The status changes to legal_accepted. The fund remains locked, but the "Publish" action becomes available to administrators.
    • A wallet is created for the fund (wallet-api).
    • A smart contract is deployed for the fund (evm-api).
    • A crypto wallet is created for the fund (evm-api) to collect stablecoin payments.
    • Notification/Email is sent to the issuer (notification-api).

• Publish Fund (legal_accepted → published)

  • Trigger: An administrator clicks the "Publish" button.

  • Action:

    • The system rejects the transition unless exact decimal fields use their canonical string form, price_per_share is positive, and the fund satisfies its fund-structure-specific share-capacity invariants.
    • The system sets the publication_date to the current time.
    • The fund becomes visible on the public-facing investor portal.
    • All tokens are minted.

• 100% Funded (published → legal_closed)

  • Trigger: This is an automated system event. It occurs when the total value of confirmed_shares equals the total_shares available.

  • Action: The system changes the status to legal_closed and removes the fund from the active marketplace. No new investments are permitted.

• Close on Success (legal_closed → closed_successfully)

  • Trigger: An administrator clicks the "Close Successfully" button.

  • Action:

    • The status changes to closed_successfully.
    • The tokens representing ownership in the RWA are distributed. The RWA is now operating and generating returns.

• Close on Failure (legal_closed → closed_unsuccessfully)

  • Trigger: An administrator clicks the "Close Unsuccessfully" button.

  • Action: The status changes to closed_unsuccessfully, removes the fund from the marketplace, and initiates the workflow to return all committed funds to investors.