Controllers
Controllers bridge the Express routes and CapTable.sol. They convert OCF data into the structs the contract expects and send the transaction; the event poller then syncs the resulting events back into MongoDB.
⚠️
Quantities and prices are scaled by 1e10 (10_000_000_000) via toScaledBigNumber(). Divide raw onchain values by 1e10 to match the numbers in API examples.
Conversion
Lifecycle
Common patterns
- Convert IDs and numbers first:
convertUUIDToBytes16(),toScaledBigNumber(). - Wait for confirmation:
const tx = await contract.method(...); await tx.wait();. - Logs use ✅ and ⏳ prefixes.
seed.jsholds legacy bulk helpers (open TODO on dates).
Controller Reference
| Area | Main Functions | What It Does | Contract Method |
|---|---|---|---|
| Issuer | convertAndAdjustIssuerAuthorizedSharesOnChain | Scales shares and adjusts issuer authorized amount | adjustIssuerAuthorizedShares |
| Stakeholder | convertAndReflectStakeholderOnchain, addWalletToStakeholder, removeWalletFromStakeholder, getters | Creates stakeholder + manages wallets | createStakeholder, addWalletToStakeholder, getStakeholderById, etc. |
| Stock Class | convertAndReflectStockClassOnchain, convertAndAdjustStockClassAuthorizedSharesOnchain, getters | Creates class and adjusts authorized shares | createStockClass, adjustStockClassAuthorizedShares |
| Transactions | convertAndCreate*Onchain (one per file) | Full equity lifecycle (issue, transfer, cancel, repurchase, reissue, retract, accept) | issueStock, transferStock, cancelStock, repurchaseStock, etc. |
Notes on Transactions:
issuanceController.jsis the most complex (uses helper for defaults).- Most pair 1:1 with an OCF schema and a Solidity function.
- Equity compensation and convertible issuances are offchain-only (no controller).
How a POST route uses a controller
- Issuer middleware attaches
req.contract. - The OCF body is validated.
- The matching controller converts and sends the transaction.
- The OCF record is saved to MongoDB.
- The poller backfills anything emitted by the contract.
For walkthroughs see Create Stakeholder, Create Stock Class, Issue Stock, and Transfer Stock. For the contract-side reference see Solidity Reference and Stock Library.