Add the Fairmint OCF improvements index - #5
Conversation
Point write-ups at the dev-docs schema-gaps log and keep IDs 001-007 in sync, including reservation and the not-OCF line. Co-authored-by: Cursor <cursoragent@cursor.com>
There was a problem hiding this comment.
Pull request overview
Adds Fairmint’s internal OCF improvement backlog and staging index.
Changes:
- Indexes OCF-IMP-001–007.
- Documents identified schema gaps and proposed directions.
- Links related internal documentation.
Suppressed comments (2)
fairmint-ocf-improvements.md:24
- This table-of-contents link similarly misses the double hyphen generated from the spaced
/, so it will not navigate to the OCF-IMP-006 heading.
| [OCF-IMP-006](#ocf-imp-006-nominee-omnibus-capacity) | C | Open | No nominee / omnibus capacity on `STAKEHOLDER` |
fairmint-ocf-improvements.md:158
- The consume field list repeats the contradictory issuance case even though reservations hold already-outstanding shares. An issuance creates shares and cannot consume quantity from such a reservation; restrict this reference to transfer/cancellation objects that operate on existing shares.
- Existing transfer / issuance / cancellation objects gain an optional `reservation_id` (or list).
Quantity consumed cannot exceed remaining reserved quantity on that reservation.
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
| | [OCF-IMP-002](#ocf-imp-002-structured-consideration-on-secondary-transfers) | A | Open | No structured consideration on secondary transfers | | ||
| | [OCF-IMP-003](#ocf-imp-003-transaction-date-is-calendar-day-only) | A | Open | Transaction `date` is calendar-day only | | ||
| | [OCF-IMP-004](#ocf-imp-004-position-reservation-and-release) | B | Open | No reservation / release transactions for a hold on outstanding shares | | ||
| | [OCF-IMP-005](#ocf-imp-005-legend-restriction-change) | B | Open | No legend / restriction change without cancel-reissue | |
| ## OCF-IMP-004: Position reservation and release | ||
|
|
||
| **Affects:** Official projection (free vs reserved quantity). Needed so a hold is reconstructible | ||
| from the constitutive event log, not only painted on a committed view. |
| | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | ||
| | `TX_STOCK_RESERVATION` | Lock quantity. Free down, reserved up. Shares remain outstanding. | | ||
| | `TX_STOCK_RESERVATION_RELEASE` | Unlock some or all of a reservation (deal dies, expiry processed, TA voids the hold). Reserved down, free up. | | ||
| | Consume-by-reference | A later `TX_STOCK_TRANSFER` / issuance / cancellation that **settles** the hold points at `reservation_id`. That consume is not a fourth "unlock" type. The transfer (or issuance) is the consume. Reserved quantity is released because the lots moved, not because a release was posted. | |
| Expiry is either a TA-posted `TX_STOCK_RESERVATION_RELEASE` with reason `EXPIRED`, or a | ||
| deterministic rule that extractors apply when `expires_at` has passed and no consume has posted. | ||
| Prefer an explicit release event so the log does not depend on wall-clock interpretation. |
|
|
||
| ```text | ||
| outstanding = f(issuances, transfers, cancellations, …) | ||
| reserved = sum(active reservations) − sum(releases) − sum(consumes) |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 3c7fa39164
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | ||
| | `TX_STOCK_RESERVATION` | Lock quantity. Free down, reserved up. Shares remain outstanding. | | ||
| | `TX_STOCK_RESERVATION_RELEASE` | Unlock some or all of a reservation (deal dies, expiry processed, TA voids the hold). Reserved down, free up. | | ||
| | Consume-by-reference | A later `TX_STOCK_TRANSFER` / issuance / cancellation that **settles** the hold points at `reservation_id`. That consume is not a fourth "unlock" type. The transfer (or issuance) is the consume. Reserved quantity is released because the lots moved, not because a release was posted. | |
There was a problem hiding this comment.
When a reservation covers shares that are already outstanding, settling it with an issuance creates additional shares instead of moving or extinguishing the reserved shares. Under the extractor formula below, such an event both increases outstanding and decreases reserved; for example, consuming a 100-share reservation with a 100-share issuance turns 100 outstanding shares into 200. Limit consumption to transactions that act on the reserved position, or define a separate non-stock issuance mechanism that does not alter outstanding stock.
Useful? React with 👍 / 👎.
|
|
||
| ```text | ||
| outstanding = f(issuances, transfers, cancellations, …) | ||
| reserved = sum(active reservations) − sum(releases) − sum(consumes) |
There was a problem hiding this comment.
If “active reservations” means reservations with a remaining balance, this formula double-counts releases and consumes. After a 100-share reservation is fully released, it is no longer active, so the expression computes 0 - 100 = -100 reserved shares. Either sum every posted reservation quantity before subtracting releases and consumes, or sum the remaining balances of active reservations without the subtractions.
Useful? React with 👍 / 👎.
Summary
fairmint-ocf-improvements.mdas the short Fairmint staging index for OCF-IMP-001–007.Test plan
ocf-schema-gaps.md.Made with Cursor