> For the complete documentation index, see [llms.txt](https://docs.familio.trade/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.familio.trade/the-product/how-a-family-works.md). # How a family works A family is a smart contract (`FamilyVault`) that holds one **quote** asset — WETH (you send plain ETH) or USDG — plus up to 30 tracked token bags. Members hold **non-transferable shares**. There is no NAV oracle. Entry is priced by actual swaps; exit is an in-kind slice. ## Deposits and shares ### Founding deposit The first deposit mints shares 1:1 with the quote, scaled to 18 decimals (`amount × 10^(18 − quoteDecimals)`). For ETH that is one share per wei. It is made **inside the creation transaction** (`found`), so opening a family and putting the first ETH in is one confirmation. Shares go to the head. After that the factory has no way in; everyone, head included, uses `join`. Joins into a vault with fewer than `1e9` total shares (1 gwei of ETH, or 0.001 USDG of founding) are refused, so a dust-supply vault cannot be donation-inflated. ### Empty pool (everything distributed) If the vault still has **outstanding shares** but **zero value** — every bag sold and every payout distributed, so nothing is left to price against — new joins revert (`BadLeg`). The contract cannot mint a fair slice from thin air. The UI blocks the flow with "pool is empty — joins paused". The head can **revive** the vault by sending quote directly to the vault address (plain ETH on WETH families wraps into pool quote). Once there is value again, mirror-entry joins work. On approval-mode doors, escrowed join requests are **refundable via `cancelRequest` at any time** while the pool is empty. ### Later joins (mirror-buy) A later deposit must arrive holding the **same mix** the vault already holds, so it cannot dilute existing members or be diluted by them. The app quotes one swap **leg** per live bag (quote → token) sized to buy the same fraction of each position. On-chain the vault pulls the quote, executes each leg through an allow-listed router into a token it already tracks (and has not ignored), then mints `totalShares × min(quote added / quote before, acquiredᵢ / heldᵢ)` shares. Any surplus from an imperfect fill stays with existing members. The joiner bears their own slippage (`minShares` reverts a bad quote). A flat vault (quote only) mints on the quote ratio alone. The head can mark a bag **ignored** (rugged, illiquid). Ignored bags drop out of the entry ratio so a dead token cannot block joins, but they are still paid on exit. New joiners therefore get a free claim on an ignored bag — the switch is for worthless bags only. ## Buys and sells Only the head and co-pilots can call `swap`. Trades are **quote → token** (buy) or **token → quote** (sell) through an allow-listed router. Arbitrary router calldata is accepted; safety is the balance-delta check: * Input may fall by at most `amountIn`. * Output must rise by at least `minOut`. * No other tracked bag may fall. The vault approves the router for exactly `amountIn` (Permit2 for the Universal Router, a plain allowance otherwise) and revokes it afterwards. Blocked tokens (Stock Tokens) cannot be bought or sold. Buys are capped at `maxTradeBps` of free quote per swap; **sells are never capped**. Heads and co-pilots trade from a collapsed **trade** bar on the family page (tap to expand) or from **Manage → trade**. See [Trading](/the-product/trading.md) for venues, clips, and optional **turbo mode** (popup-free trading with a browser session key). ## In-kind exits `leave(shares)` burns those shares and sends you `shares / totalShares` of: * free quote (WETH vaults unwrap to ETH; if the recipient rejects ETH, you get WETH), * every tracked bag. The vault never sells on a leaver's behalf, so remaining members never eat a leaver's slippage. You sell the tokens from your own wallet if you want cash. ### The crew leaves last (v2 families) Families opened on the second factory hold the people at the wheel to a stricter exit. The head and the co-pilots **cannot take a slice while the family holds a token**: they sell everything to quote first — which sells every member out with them, so nobody is left holding what the trader walked away from — and only then take their slice, which is then quote only. A bag that will not sell can be quarantined (`setIgnored`), forfeiting the trader's share of it to the members. This also holds for **7 days after** handing the seat over or being removed as co-pilot, so a head cannot pass the seat to a spare wallet and walk out as a "member". Someone who owns every share of the family leaves nobody behind and may take it all in kind. Members are never bound by this. First-factory families keep the original rule: anyone, head included, may leave in kind at any time. `leave()` ignores every vault-level lock. The head can lock joins and pause trading; they cannot lock exits. The only exit pause is a protocol emergency, capped at 72 hours with a enforced 72-hour open-exit cooldown before another pause can start. See [Rules and safety rails](/the-product/rules-and-safety-rails.md). ### `leaveWith(shares, skipMask, extra)` Two escape hatches so no token can hold a member hostage: * Bit `i` of `skipMask` skips held token `i` (index matches `heldTokens()`). That slice stays in the vault. Use it when a bag reverts on transfer (frozen, blacklisting, broken `balanceOf`). * `extra` is a strictly ascending list of **untracked** tokens (not the quote, not already held). You also receive a pro-rata slice of each. That is how airdrops and "strays" leave with you. The app's leave drawer simulates first: if a bag is frozen it asks you to forfeit it; if strays will not transfer it leaves them behind rather than blocking the exit. The head can **evict** a member. Eviction is a full in-kind `leave` of that member's shares. Nothing is withheld. Evict does not take the skip-mask path — a frozen bag can block an eviction, which is why members should leave themselves if a token is broken. ## Distributions and claims `distribute(amount)` moves free quote into a **per-share accumulator**. It is not a fee. It does not take a cut. It just earmarks quote that already sits in the vault so members can claim it without leaving. Each member's claimable amount is: `stored pending + shares × accPerShare / 1e18 − rewardDebt` When you join, leave, or top up, the vault settles your pending first, then updates `rewardDebt`. Joining after a payout does not steal a share of it; leaving after a payout does not forfeit what you already accrued. * **Claim** — you pull your quote from the vault. * **Auto-send off (default)** — payouts wait in the vault as **claimable** until you claim. * **Auto-send on** — you flip a flag on-chain with one small transaction (`setAutoSend`). A keeper (every \~10 minutes) may then call `claimFor` and the quote is pushed to your wallet. The keeper key holds gas money and cannot move funds anywhere except to the member. Flip it off any time; claiming yourself always works. ## The accumulator in plain words `accPerShare` is "quote paid out, per share, since day one." Distribute 1 ETH across 10 shares and each share is owed 0.1 ETH. Your `rewardDebt` is a bookmark at the last line you were credited. The difference is claimable. Shares minted after a distribution start at the current line, so they are not owed yesterday's payout. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.familio.trade/the-product/how-a-family-works.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.