Create new vesting transaction to represent stopped / resumed vesting

[pjohnmeyer]

Why

Currently, there is no way to represent a stopped or resume vesting event in the transaction log.

Proposal

Create two new events, similar to VestingStart:

{
  "object_type": "TX_VESTING_STOP", // required, const
  "reason_text": "some platform provided reason, not enumerated", // optional, string
  "date": "2022-02-02", // required, date
  ... remainder of Object / Transaction / SecurityTransaction fields
}

Question: Do we also need to specify in this event if vesting to that point is pro-rated for partial periods? Or should that be part of the terms / triggers?

{
  "object_type": "TX_VESTING_RESUME", // required, const
  "reason_text": "some platform provided reason, not enumerated", // optional, string
  "date": "2022-02-22", // required, date
  ... remainder of Object / Transaction / SecurityTransaction fields
}

Alternatives Considered

Do nothing

If we do not create a VestingStop event, then any security that has vesting stopped will need to create a new VestingTerms object unique to that security. While this is a valid alternative, stopping vesting is a common enough occurrence that I believe the schema should natively support it.

If the security has had vesting resumed, on the other hand, it could still refer to the original VestingTerms -- but then there would be no record in the transaction log that stop / resume had happened.

Represent vesting stopped as an event in the VestingTerms

We could add a new trigger and represent stop vesting as an event-based VestingCondition. Doing this, however, would greatly complicate the graph, and would require more parameterization of the condition. Take for example an extremely simple schedule that vests 25% annually for 4 years. Right now that can be represented with two nodes:

25% for 4 years today

      "vesting_conditions": [
        {
          "id": "vesting-start",
          "quantity": "0",
          "trigger": {
            "type": "VESTING_START_DATE"
          },
          "next_condition_ids": ["yearly"]
        },
        {
          "id": "yearly",
          "description": "25% payout each year",
          "portion": { "numerator": "1", "denominator": "4" },
          "trigger": {
            "type": "VESTING_SCHEDULE_RELATIVE",
            "period": {
              "length": 1,
              "type": "YEARS",
              "occurrences": 4,
              "day_of_month": "VESTING_START_DAY_OR_LAST_DAY_OF_MONTH"
            },
            "relative_to_condition_id": "vesting-start"
          },
          "next_condition_ids": []
        }
      ]

If we add stop vesting to this, we now have to break out each yearly tranche into its own node, and put in a "resume vesting" event as well. (some fields omitted for brevity). This is far more complex, and even here there are open questions. Imagine this with 48 monthly tranches and some additional milestone events and you can see how this could get very complex:

25% for 4 years with stop/resume vesting as conditions in the tree

      "vesting_conditions": [
        {
          "id": "vesting-start",
          "quantity": "0",
          "trigger": {
            "type": "VESTING_START_DATE"
          },
          "next_condition_ids": ["yearly"]
        },
        {
          "id": "year1",
          "portion": { "numerator": "1", "denominator": "4" },
          "trigger": {
            "type": "VESTING_SCHEDULE_RELATIVE",
            "period": {
              "length": 1,
              "type": "YEARS",
              "occurrences": 1,
              "day_of_month": "VESTING_START_DAY_OR_LAST_DAY_OF_MONTH"
            },
            "relative_to_condition_id": "vesting-start"
          },
          "next_condition_ids": ["stop-vesting", "year2"]
        },
        {
          "id": "year2",
          "portion": { "numerator": "1", "denominator": "4" },
          "trigger": {
            "type": "VESTING_SCHEDULE_RELATIVE",
            "period": {
              "length": 2,
              "type": "YEARS",
              "occurrences": 1,
              "day_of_month": "VESTING_START_DAY_OR_LAST_DAY_OF_MONTH"
            },
            "relative_to_condition_id": "vesting-start"
          },
          "next_condition_ids": ["stop-vesting", "year2"]
        },
        {
          "id": "year3",
          "portion": { "numerator": "1", "denominator": "4" },
          "trigger": {
            "type": "VESTING_SCHEDULE_RELATIVE",
            "period": {
              "length": 3,
              "type": "YEARS",
              "occurrences": 1,
              "day_of_month": "VESTING_START_DAY_OR_LAST_DAY_OF_MONTH"
            },
            "relative_to_condition_id": "vesting-start"
          },
          "next_condition_ids": ["stop-vesting", "year3"]
        },
        {
          "id": "year4",
          "portion": { "numerator": "1", "denominator": "4" },
          "trigger": {
            "type": "VESTING_SCHEDULE_RELATIVE",
            "period": {
              "length": 4,
              "type": "YEARS",
              "occurrences": 1,
              "day_of_month": "VESTING_START_DAY_OR_LAST_DAY_OF_MONTH"
            },
            "relative_to_condition_id": "vesting-start"
          },
          "next_condition_ids": ["stop-vesting", "year4"]
        },
        {
          "id": "stop-vesting",
          "portion/quantity": // I don't think either of these can represent this correctly currently
          "trigger": {
            "type": "VESTING_EVENT"
          },
          "next-condition-ids": ["resume-vesting"]
        },
        {
          "id": "resume-vesting",
          "portion/quantity": // I don't think either of these can represent this correctly currently
          "trigger": {
            "type": "VESTING_EVENT"
          },
          "next-condition-ids": ["year1", "year2", "year3", "year4"] // must be able to navigate back to any periodic event that hasn't happened yet
        }
      ]

I don't think this is a good approach because of the complication of the tree, and the fact that it introduces cycles to the tree that have to be understood with a particular meaning.

[pjohnmeyer]

@JSv4 should I convert this to an issue? It would be easy enough for somebody to follow the pattern I implemented in #319 to add these.