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:

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

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

Key Transitions

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

• Create Offer (new → draft or legal_review)

  • Trigger: An offer is created through the offer API.

  • Action: The offer 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 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 changes to legal_declined, and the fields are unlocked for editing.

• Approve Offer (legal_review → legal_accepted)

  • Trigger: The legal side approves the offer.

  • Action:

    • The status changes to legal_accepted. The offer remains locked, but the "Publish" action 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 stablecoin payments.
    • Notification/Email is sent to the issuer (notification-api).

• Publish Offer (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 offer satisfies its fund-structure-specific share-capacity invariants.
    • 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 → 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 offer 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 offer from the marketplace, and initiates the workflow to return all committed funds to investors.