Investment Status Transition

This document defines the state machine for the Investment entity. It governs the lifecycle of an investment commitment, tracking it from the initial application, through legal and financial confirmation, to its final closing or cancellation.

Lifecycle Diagram

The investment lifecycle follows a primary success path, but includes several paths for cancellation depending on when the action is taken.

Primary Flow: NEW → CONFIRMED → LEGALLY_CONFIRMED → SUCCESSFULLY_CLOSED

Alternative Paths:

• NEW → CANCELLED_BY_INVESTOR (Cancellation before submission)

• CONFIRMED / LEGALLY_CONFIRMED → CANCELLATION_REQUESTED (Request after submission)

• CANCELLATION_REQUESTED → CANCELLED_BY_MANAGER (Admin approval of cancellation)

• LEGALLY_CONFIRMED → UNSUCCESSFULLY_CLOSED ( Offer fails)

Status Definitions

Status	Description
NEW	The initial status when an Investment record is first created as a user progresses through the investment steps. The application has not yet been submitted.
CONFIRMED	The investor has successfully completed all steps of the investment flow and submitted the application for processing.
LEGALLY_CONFIRMED	The investor's profile has passed all necessary KYC and Accreditation checks required for this specific offer, and the payment process has been initiated.
SUCCESSFULLY_CLOSED	The investment is complete, and the parent offer was successfully funded. Funds have been transferred to the issuer.
UNSUCCESSFULLY_CLOSED	The parent offer was not successfully funded. The investment has been terminated, and funds have been refunded to the investor.
CANCELLATION_REQUESTED	The investor has requested to cancel their investment after submitting it. This requires manual review and approval by an administrator.
CANCELLED_BY_INVESTOR	The investor cancelled the investment before completing the final submission step.
CANCELLED_BY_MANAGER	The investment has been cancelled by an administrator, either by request or for other operational reasons.

Key Transitions

• Submit Investment (NEW → CONFIRMED)

  • Trigger: An investor successfully completes the final "Review" step of the investment flow.

  • Action: The system updates the status to CONFIRMED and sets the submitted_at timestamp. The investment appears in the user's portfolio.

• Confirm Legal Readiness (CONFIRMED → LEGALLY_CONFIRMED)

  • Trigger: An automated system check confirms the investor's Profile has passed all required KYC and Accreditation checks for the associated Offer.

  • Action: The status is updated to LEGALLY_CONFIRMED. The system initiates the payment transfer.

• Pre-Investment Legal Readiness (NEW → LEGALLY_CONFIRMED)

  • Trigger: An automated system check confirms the investor's Profile has passed all required KYC and Accreditation checks for the associated Offer before the investment was submitted.

  • Action: The status is updated to LEGALLY_CONFIRMED. The system initiates the payment transfer.

• Finalize Success (LEGALLY_CONFIRMED → SUCCESSFULLY_CLOSED)

  • Trigger: The parent Offer that this investment is linked to closes successfully.

  • Action:

    • The system updates the investment status to SUCCESSFULLY_CLOSED.
    • This triggers the release of funds to the issuer.
    • The system initiates tokens distribution.

• Finalize Failure (LEGALLY_CONFIRMED → UNSUCCESSFULLY_CLOSED)

  • Trigger: The parent Offer that this investment is linked to closes unsuccessfully.

  • Action: The status is updated to UNSUCCESSFULLY_CLOSED, and the refund workflow is initiated to return funds to the investor.

• Request Cancellation (CONFIRMED / LEGALLY_CONFIRMED → CANCELLATION_REQUESTED)

  • Trigger: The investor clicks the "Cancel Investment" button after submitting their application.

  • Action: The status is updated to CANCELLATION_REQUESTED, and the investment is flagged in the admin panel for manual review.

• Approve Cancellation (CANCELLATION_REQUESTED → CANCELLED_BY_MANAGER)

  • Trigger: An administrator manually approves an investor's cancellation request.

  • Action: The status is updated to CANCELLED_BY_MANAGER. The system initiates the cancellation of the payment transfer, triggering a refund if necessary.