Architecture

The protocol lives on two chains. Ethereum carries the launchpad, the pools and the vaults; Robinhood Chain carries the tokenized stocks.

The contracts

Proxies and upgrades

Since 2026-10-02 every module is an ERC-1967 proxy in front of an implementation, upgraded through UUPS. The proxy holds the address and the state; the implementation holds the code, and an upgrade replaces it. An implementation can never be initialized: each proxy is initialized inside its own constructor.

Every module asks one contract who may upgrade it, its upgrade authority, fixed in its implementation: the factory on Ethereum, which answers with its owner, and the remote hub on Robinhood Chain, which answers with its emergency admin, the Ethereum owner as the last bridge batch carried it. A transfer of the factory's ownership therefore moves the upgrade power of every Ethereum module at once, and that of the Robinhood Chain modules with the next batch. An upgrade is refused if the new implementation names another authority; the hook's and the holding recorder's must also keep the same PoolManager.

Not upgradeable: the tokens, the liquidity lock and, on Robinhood Chain, the remote vault deployer, from whose address every mirror vault's address is derived. MarketDeployer and VaultDeployer hold no state: the factory replaces them (setDeployers) rather than upgrading them.

The storage is appended to, never reordered: each module's layout is recorded in contracts/storage-layouts/, and contracts/script/check-storage-layouts.sh compares it before every upgrade. Since 2026-10-05 it compares every depth of every struct, sizes included, and refuses any change to a struct that is the element of a storage array: only a struct that is a mapping's value, or the last state variable, may grow, at its end.

An implementation contract is never used directly, but whatever is sent to its own address by mistake has a lever too. Most implementations read their authority from an immutable, so the protocol owner moves it out; the factory's and the remote hub's keep their admin in the proxy's storage, so on their implementations the lever is the address that deployed them.

Who can upgrade, and how fast: see Trust model.

The airdrop contract

Since 2026-10-04, AirdropDistributor distributes each treasury's stocks on Ethereum. It is an upgradeable module like the others, a proxy whose upgrade authority is the factory. The factory names it (setAirdropDistributor) and the vaults read it live; a replaced distributor keeps every cycle claimable where it is. It reads the holdings from the holding recorder, and its rules are on The airdrop.

Two paths reach it, and nothing else credits a cycle:

• The bridge rail. The mirror vault's sendToAirdrop sends each listed stock through that stock's LayerZero adapter, which the remote hub names (setStockAdapter), to the distributor the remote hub names (setAirdrop), with the market's id as payload. On Ethereum the stock's OFT mints the wrapped stock to the distributor, and LayerZero's endpoint calls it. It credits the delivery only from a stock OFT the owner registered, from Robinhood Chain, sent by the mirror vault the bridge hub derives for that market.
• The local rail. The Ethereum vault's sendToAirdrop approves the exact amounts, the distributor pulls them, from the market's own vault only, and credits what it received; the approvals are closed again. A vault wired to the bridge hub refuses this call.

The keeper triggers both, and decides only when; on the bridge rail, since 2026-10-06, also the gas each delivery gets on Ethereum, which the remote hub holds within the bounds StockFun's owner sets there.

Structural properties

The hook is a singleton. One contract serves every pool, which avoids mining an address per market — a v4 hook's address encodes its permissions in its low bits, and finding one costs compute. Since 2026-10-02 it is a proxy whose address carries all 14 v4 permissions: an upgrade keeps that address, and a later implementation can use any callback.

Liquidity is not an NFT. It is held directly in the PoolManager, keyed by the lock's address. There is no position to transfer, no approve to revoke, no tokenId to lose. The only liquidity operations the contract can perform are a modifyLiquidity with a delta of exactly zero, to collect fees, and, through the end mode, the removal of every position of a pool, 30 days after the end is announced.

Only the lock adds liquidity. Since 2026-10-01 the hook refuses any other position on a StockFun pool, so every trade is a swap against the locked positions, and pays the tax.

Vaults have no withdrawal. No function lets anyone send a vault's assets to an address of their choosing. The two exits are the airdrop, whose only destination is the airdrop contract the protocol names, which pays the token's holders pro rata under a rule nobody chooses, and emergency mode, by which StockFun's owner moves an asset to any address, at once. Those are the rules of the current implementation: StockFun's owner can upgrade a vault, with immediate effect.

The bounds are settings, the feeds are not. The vaults' price bounds, 50 and 200 basis points by default, are settings of StockFun's owner, read live by every vault; the keeper can only tighten them. The feed registry writes each feed once; the feeds' heartbeats are settings, and so, since 2026-10-06, are its two guards, which can only hold a price back, never change one: the sequencer check (off on Robinhood Chain until Chainlink publishes an uptime feed for it) and each stock's oracle pause (on for every Robinhood Chain stock; see The Robinhood rail). Emergency mode touches neither: it moves assets, it does not change execution rules. The registry, like the vaults, can be upgraded by StockFun's owner.

Isolation and levers

On 2026-10-05 the founder set a design rule: when something makes one function fail, the other functions must not pay for it; everything must be able to keep working, and everything must have a lever to recover lost funds and take the fix. The fourth audit loop of that day put it in the code, and since then the audit loops count any breach of its two parts as a defect.

Isolation. A failure in one function, market, stock, cycle, record or recipient never blocks the others: the item is skipped, kept as owed or deferred, with an event, and the rest goes on.

• A bridge batch leaves out a market whose vault cannot release its cash (MarketSkipped), and the others cross. A delivery the cash token refuses to one mirror vault stays on the remote hub, owed to that market (DeliveryRefused), and the other markets are paid
• A purchase runs each stock's leg on its own (LegFailed), and a send to the airdrop each stock on its own (AirdropSendFailed)
• A claim pays every stock it can and defers the others (ClaimDeferred)
• A vault that refuses ETH no longer halts its market's trading: the hook keeps what it could not pay as owed to that vault (treasuryOwed), and the lock keeps a refused share of a fee collection for its recipient (vaultOwed, creatorOwed). Anyone pays them once the recipient takes ETH again (payTreasury, payOwed), and the keeper does so every cycle
• The Lens reads each vault in its own call, so a vault that cannot answer leaves the others readable (vaultReadable). Since 2026-10-06 that call also carries the vault's rail, pause and bridged USDC, and the page what the hook and the lock owe the vault: the app's data service reads nothing else per market, so one vault that burns its gas fails only its own figures. Since the seventh audit loop it also reads each upgradeable module (the hook, the oracle, the airdrop contract, the two bridge hubs) and the protocol token in a group of its own, so one module that burns its gas, after a faulty upgrade, fails only its own figures

Levers. Every contract that can hold ETH or tokens, even in passing or by mistake, has a lever to move out what is stuck, and every module can take a fix: an upgrade, or a setter that swaps the module.

• The modules that keep nothing of anyone's between transactions — the factory, the Lens, the oracles, the holding recorder, the stock routers, the official swap router and the bridge adapters — have the protocol owner's rescue(asset, amount, to)
• The modules that keep books of their own — the vaults, the two hubs and the airdrop contract — have emergency mode
• The hook's rescue takes only what was sent to it by mistake, never what it owes. The lock's never takes the shares it keeps, nor the positions, which only the end mode reaches. The BuybackBurner's takes its ETH only once no burn could spend it. The tokens, which cannot be upgraded, can move out what was sent to their own address
• Without a lever, by design: the two deployers on Ethereum and the remote vault deployer, which hold no state, accept no ETH and have no owner

Detail in Emergency mode.

The one deliberate exception. A token's report to its holding recorder stays blocking: if the report fails, the transfer fails. A report allowed to fail would let a holder starve it of gas on their own transfer, so that the record skips the move and their airdrop share grows. The lever is immediate, one transaction each: setRecorder(0) on the token, which stops its record, or an upgrade of the recorder in place. See The airdrop.

Offchain packages