Offer Status Transition

This document defines the state machine for the Offer entity. The lifecycle governs an offer 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 offer's operational journey.

Lifecycle Diagram

The standard path for an offer 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:

DRAFT → LEGAL-REVIEW → LEGAL-ACCEPTED → PUBLISHED → LEGALLY-CLOSED → CLOSED-SUCCESSFULLY → EXITED/REPAID

Alternative Paths:

• LEGAL-REVIEW → LEGAL-DECLINED → DRAFT (Rejection Loop)

• PUBLISHED → CLOSED-UNSUCCESSFULLY (Failure Path)

Status Definitions

Status	Description
New	The initial state after an Offer is created.
DRAFT	Some changes were already made after creation. It is being configured by an administrator and is not visible to the legal providers or investors.
LEGAL-REVIEW	The Offer has been submitted for compliance and legal approval. The offer's core terms are locked and cannot be edited. Note: now the reviewers are escrow provider and electronic wallet provider.
LEGAL-DECLINED	The legal side has rejected the Offer. It is returned to the DRAFT state for modification, with the reason for rejection logged.
LEGAL-ACCEPTED	The Offer has been approved by the legal side and is now staged and ready for publication.
PUBLISHED	The Offer is live on the investor portal and is actively accepting investments.
LEGALLY-CLOSED	The Offer is no longer accepting new investments. The legal and financial teams are finalizing all documentation.
CLOSED-SUCCESSFULLY	The funding goal was met, all funds have been settled, and all legal closing procedures are complete. The tokens representing ownership in the RWA have been distributed. The asset is now officially under management. The RWA is now operating and generating returns.
CLOSED-UNSUCCESSFULLY	The Offer did not meet its funding goal. In this state, the process to return all committed funds to investors is initiated and tracked.
EXITED/REPAID	The lifecycle is complete. The underlying asset has been sold or the loan has been fully repaid. Final capital and profit distributions are made to the token holders. The Offer is complete.

Key Transitions

Transitions are the actions or system events that move an offer from one state to the next.

• Submit for Review (DRAFT → LEGAL-REVIEW)

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

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

• Decline Offer (LEGAL-REVIEW → LEGAL-DECLINED)

  • Trigger: The legal side rejects the offer.

  • Action: The system requires a reason for the rejection, which is logged. The offer status is changed to LEGAL-DECLINED. The fields are unlocked for editing.

• Approve Offer (LEGAL-REVIEW → LEGAL-ACCEPTED)

  • Trigger: The legal side approves the offer.

  • Action:

    • The status is updated to LEGAL-ACCEPTED. The offer remains locked, but the "Publish" action now becomes available to administrators.
    • A wallet is created for the offer (wallet-api).
    • A smart contract is deployed for the offer (evm-api).
    • A crypto wallet is created for the offer (evm-api) to collect paymnet with stable coins.
    • Notification/Email is sent to issuer informing them about legal approval (notification-api).

• Publish Offer (LEGAL-ACCEPTED → PUBLISHED)

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

  • Action:

    • The system sets the publication_date to the current time.
    • The offer becomes visible on the public-facing investor portal.
    • All tokens are minted.

• 100% Funded (PUBLISHED → LEAGALLY-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 automatically changes the status to LEAGALLY-CLOSED and removes the offer from the active marketplace. No new investments are permitted.

• Close on Success (LEAGALLY-CLOSED → CLOSED-SUCCESSFULLY)

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

  • Action:

    • The status is updated to CLOSED-SUCCESSFULLY.
    • The tokens representing ownership in the RWA are distributed. The RWA is now operating and generating returns.

• Close on Failure (PUBLISHED → CLOSED-UNSUCCESSFULLY)

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

  • Action: The status is updated to CLOSED-UNSUCCESSFULLY, removes the offer from the marketplace, and initiates the workflow to return all committed funds to investors.

• Mark as Exited (CLOSED-SUCCESSFULLY → EXITED/REPAID)

  • Trigger: An administrator manually triggers this state change after all off-platform business activities are concluded (e.g., property sold, loan principal returned).

  • Action: The system marks the offer as complete. The offer is moved to an archival view.