Solidity Cap Table
Contracts store issuer, stock class, stakeholder, position, and transaction state. The API calls them. The poller syncs their events to MongoDB.
- CapTable.sol
- CapTableFactory.sol
Roles
| Role | Holder | Power |
|---|---|---|
ADMIN_ROLE | Issuer or asset manager (wallet that called createCapTable). | Manage roles; adjust authorized shares. Admins count as operators. |
OPERATOR_ROLE | Transfer-agent server wallet or delegate. | Day-to-day writes: classes, stakeholders, issue/transfer stock, etc. |
| Factory owner | Wallet that deployed that CapTableFactory. | Upgrade the beacon implementation for all of that factory’s cap tables. |
Business reading: protocol builder owns IP and any demo factory; a licensed transfer agent should own their factory; issuers own ADMIN on each issuer table. Mongo factory registration is offchain config only.
How these roles map to local env vars (PRIVATE_KEY, NEXT_PUBLIC_OPERATOR_ADDRESS, browser wallet) is documented under Three wallets / keys.
createCapTable is permissionless. It makes msg.sender admin and can grant an operator in the same transaction. It does not make the caller the factory owner.
Upgrade model
| Contract | Pattern | Notes |
|---|---|---|
CapTableFactory | Ownable UpgradeableBeacon factory. | One beacon, many proxies. |
CapTable | Beacon implementation. | Initialized per issuer. |
| Cap table proxy | BeaconProxy. | Reads implementation from the beacon. |
Only the factory owner can upgrade the implementation.
Surfaces
| Surface | File | Purpose |
|---|---|---|
CapTable | chain/src/CapTable.sol | Issuer-level state and writes. |
CapTableFactory | chain/src/CapTableFactory.sol | Proxy creation and beacon upgrades. |
ICapTable | chain/src/interfaces/ICapTable.sol | Cap table interface. |
ICapTableFactory | chain/src/interfaces/ICapTableFactory.sol | Factory interface. |
Structs | chain/src/lib/Structs.sol | Shared structs. |
StockLib | chain/src/lib/Stock.sol | Stock lifecycle logic. |
TxHelper | chain/src/lib/TxHelper.sol | Transaction payloads and TxCreated. |
DeleteContext | chain/src/lib/DeleteContext.sol | Active position deletes. |
Adjustment | chain/src/lib/transactions/Adjustment.sol | Authorized-share changes. |