Stock Functions

Every lifecycle write follows the same shape: validate an active security, mutate active positions, encode the transaction, and emit an event for the poller. Partial operations may also create a new balance security.

StockLib is chain/src/lib/Stock.sol. CapTable calls it for stock lifecycle writes.

Library functions

Function	Called by	Checks	Changes	Tx
`createIssuance`	`issueStock`	Quantity and price.	Adds position; increments issued shares.	`STOCK_ISSUANCE`
`createTransfer`	`transferStock`	Buyer verified; enough stock.	Moves shares; may create balance/resulting issuances.	`STOCK_TRANSFER`
`createCancellation`	`cancelStock`	Position exists; enough quantity.	Removes original; may create balance; subtracts issued shares.	`STOCK_CANCELLATION`
`createReissuance`	`reissueStock`	Position exists.	Records reissue; removes original.	`STOCK_REISSUANCE`
`createRepurchase`	`repurchaseStock`	Position exists; enough quantity.	Records repurchase; may create balance; subtracts issued shares.	`STOCK_REPURCHASE`
`createRetraction`	`retractStockIssuance`	Position exists.	Records retraction; removes original.	`STOCK_RETRACTION`
`createAcceptance`	`acceptStock`	Checked by `CapTable`.	Records acceptance only.	`STOCK_ACCEPTANCE`

Helpers

Helper	Purpose
`_updateContext`	Write position, track security ID, record issuance, update issued shares.
`_safeNow`	Cast `block.timestamp` to `uint40`.
`_subtractSharesIssued`	Decrement issuer and class issued shares.
`_transferSingleStock`	Move one active security.
`_checkInvalidQuantityOrPrice`	Reject zero quantity or price.
`_checkInsuffientAmount`	Reject insufficient shares.
`_checkActivePositionExists`	Reject zero-quantity position.
`_checkBuyerVerified`	Reject unverified transfer buyer.

Errors

Error	Trigger
`InsufficientShares`	Requested quantity exceeds active shares.
`InvalidQuantityOrPrice`	Quantity or price is zero.
`UnverifiedBuyer`	Transfer buyer is unverified.
`ActivePositionNotFound`	Active position has no quantity.

Balance securities

Action	Behavior
Transfer	Walks live lots; salts ids with `issuanceOrdinal`. Partial transfer creates a transferor balance issuance. `balance_security_id` is that remainder certificate, or zero when the lot is fully moved.
Cancellation	Partial cancellation creates a balance issuance (remainder certificate).
Repurchase	Partial repurchase creates a balance issuance (remainder certificate).
Retraction/reissuance	Original position is removed.

Server-side controllers convert UUIDs to bytes16 and scale quantities/prices through @tap/units (convertUUIDToBytes16 / toScaledBigNumber wrappers). Raw onchain values are scaled by 1e10 (10,000,000,000) — divide by 1e10 to get human values. The poller unscales automatically before writing to MongoDB. The /app wallet path uses the same @tap/units helpers.