Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion AMAZON-DESCRIPTION.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ Written for engineers shipping software that holds other people's money, and for

**Part I** builds the fundamentals: Solana's accounts, tokens, PDAs, and time, then financial software as a state machine, the arithmetic of money, offchain truth, the adversary, and operating a program in production. Exploit classes are taught through the incidents that made them famous, among them the $2.6B SPL token-lending rounding bug, Cashio ($52M), Wormhole ($325M), and Mango Markets ($116M).

**Part II** walks ten complete, tested programs end to end: an escrow, an all-or-nothing token fundraiser, a parimutuel betting market, an order book exchange with a critbit matching engine, a constant-product AMM, an oracle-priced proprietary AMM, a lending and borrowing market with per-second interest and a liquidation engine, an onchain index fund, a fully collateralized options venue, and a perpetual futures venue with funding, margin, and pre-funded solvency. Every chapter gives the account model, the instruction handlers walked as a story, the math in minor units with its rounding directions, the invariants, the failure modes, the tests that catch each one, and the incentives of everyone involved, operator and user alike. Account maps, state machines, and value flows are drawn in one visual language across all ten, so the programs can be read against each other. They have not been explained side by side in one place before.
**Part II** walks ten complete, tested programs end to end: an escrow, an all-or-nothing fundraiser, a parimutuel betting market, an order book exchange with a critbit matching engine, a constant-product AMM, an oracle-priced proprietary AMM, a lending and borrowing market with per-second interest and a liquidation engine, a managed fund (what Solana platforms often call a vault strategy), a fully collateralized options venue, and a perpetual futures venue with funding, margin, and pre-funded solvency. Every chapter gives the account model, the instruction handlers walked as a story, the math in minor units with its rounding directions, the invariants, the failure modes, the tests that catch each one, and the incentives of everyone involved, operator and user alike. Account maps, state machines, and value flows are drawn in one visual language across all ten, so the programs can be read against each other. They have not been explained side by side in one place before.

In the tradition of *TCP/IP Illustrated*, the book teaches the layer that does not change. Frameworks churn. The account model has been stable since Solana launched, the arithmetic of money will not change, and neither will the desire of adversaries to take your assets.

Expand Down
4 changes: 2 additions & 2 deletions TABLE-OF-CONTENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,13 +28,13 @@
Each chapter explains one complete, tested program from the [companion repository](https://github.com/quicknode/solana-program-examples).

- [Chapter 11: Escrow](building-financial-products-in-solana/escrow.md) - two strangers swap without trusting each other
- [Chapter 12: Token Fundraiser](building-financial-products-in-solana/token-fundraiser.md) - onchain crowdfunding
- [Chapter 12: The Fundraiser](building-financial-products-in-solana/fundraiser.md) - onchain crowdfunding
- [Chapter 13: The Betting Market](building-financial-products-in-solana/betting-market.md) - a parimutuel pool with no bookmaker
- [Chapter 14: The Order Book Exchange](building-financial-products-in-solana/order-book.md) - a traditional NYSE/NASDAQ/CME style exchange
- [Chapter 15: The Constant-Product AMM](building-financial-products-in-solana/constant-product-amm.md) - instant swaps priced by a formula
- [Chapter 16: The Prop AMM](building-financial-products-in-solana/prop-amm.md) - a market maker quoting its own capital at oracle prices
- [Chapter 17: Lending and Borrowing](building-financial-products-in-solana/lending.md) - deposits, collateral, interest, liquidation, and cranks
- [Chapter 18: The Vault Strategy](building-financial-products-in-solana/vault-strategy.md) - an onchain index fund
- [Chapter 18: The Managed Fund](building-financial-products-in-solana/managed-fund.md) - an onchain mutual fund, also called a vault strategy
- [Chapter 19: Options](building-financial-products-in-solana/options.md) - calls and puts, fully collateralized and physically settled
- [Chapter 20: Perpetual Futures](building-financial-products-in-solana/perpetual-futures.md) - leveraged bets on a price, and the last of the ten programs

Expand Down
6 changes: 3 additions & 3 deletions WRITING-PLAN.md
Original file line number Diff line number Diff line change
Expand Up @@ -57,7 +57,7 @@ Each incident is researched from primary sources and placed inside the chapter n
- SPL token-lending rounding (about $2.6B at risk): the rounding section of The Arithmetic of Money
- Cashio ($48M kept after refunds, unvalidated account chain): the validation section of The Adversary
- Wormhole ($326M, bypassed signature verification): the validation section of The Adversary
- First-depositor inflation incidents (the ERC-4626 class): named incidents are the Hundred and Sonne stories below (their setup is the inflation attack); the empty-pool section of The Adversary teaches the class, The Constant-Product AMM chapter teaches the locked-minimum defense without an incident box, and The Vault Strategy chapter teaches ignoring donations
- First-depositor inflation incidents (the ERC-4626 class): named incidents are the Hundred and Sonne stories below (their setup is the inflation attack); the empty-pool section of The Adversary teaches the class, The Constant-Product AMM chapter teaches the locked-minimum defense without an incident box, and The Managed Fund chapter teaches ignoring donations
- Mango Markets ($116M): the price-manipulation section of The Adversary
- The Hundred and Sonne precision drains: the precision-exploits section of The Adversary

Expand All @@ -74,7 +74,7 @@ Steps currently missing their per-step diagram, to be drawn in the visual pass:
- Lending and Borrowing: Carol's short; Bob's repayment and collateral withdrawal.
- Perpetual Futures: Alice's `close_position` payout.
- The Prop AMM: Maria's `deposit_inventory` and `withdraw_inventory`.
- The Vault Strategy: Bob's deposit at the new share price.
- The Managed Fund: Bob's deposit at the new share price.

## Reviewers, Feedback, and Editions

Expand All @@ -85,7 +85,7 @@ Steps currently missing their per-step diagram, to be drawn in the visual pass:
## Milestones

- **Voice samples first** (drafted): the Introduction, Escrow, and The Order Book Exchange lock voice, depth, and template.
- The remaining program chapters, one per example, in table-of-contents order (all ten drafted: Escrow, Token Fundraiser, The Betting Market, The Order Book Exchange, The Constant-Product AMM, The Prop AMM, Lending and Borrowing, The Vault Strategy, Options, Perpetual Futures). They run as three groups: custody and pooling, then market making, then credit and derivatives. A chapter's place is set by what it assumes the reader already has, so The Betting Market sits third, where its only prerequisite is Escrow, and Options sits just before Perpetual Futures, because a fully collateralized derivative is the case the leveraged one relaxes.
- The remaining program chapters, one per example, in table-of-contents order (all ten drafted: Escrow, The Fundraiser, The Betting Market, The Order Book Exchange, The Constant-Product AMM, The Prop AMM, Lending and Borrowing, The Managed Fund, Options, Perpetual Futures). They run as three groups: custody and pooling, then market making, then credit and derivatives. A chapter's place is set by what it assumes the reader already has, so The Betting Market sits third, where its only prerequisite is Escrow, and Options sits just before Perpetual Futures, because a fully collateralized derivative is the case the leveraged one relaxes.
- The two Fundamentals sections (Solana Building Blocks; Financial Programming Concepts in Solana), with technical reviewers engaged per chapter as each completes.
- The remaining appendices. The Glossary is drafted.
- The placeholder front-matter pages last.
Expand Down
22 changes: 13 additions & 9 deletions appendices/glossary.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ A market maker's structural loss: the trades that find you when your quote is wr

### all-or-nothing

A fundraising rule under which contributions bind only if the full target is reached by the deadline; otherwise every contributor is refunded in full. The *Token Fundraiser* chapter builds it onchain.
A fundraising rule under which contributions bind only if the full target is reached by the deadline; otherwise every contributor is refunded in full. The *Fundraiser* chapter builds it onchain.

### American option / European option

Expand Down Expand Up @@ -159,7 +159,7 @@ A binary tree keyed on the first bit where entries differ. Used for order books

### curator

In a fund, the authority that decides which assets may be held at all and which price feed prices each one, kept separate from the [manager](#manager) who picks the allocation. The split is what stops a manager listing a token they minted themselves, or pairing a real asset with a feed they control. See the *Vault Strategy* chapter.
In a fund, the authority that decides which assets may be held at all and which price feed prices each one, kept separate from the [manager](#manager) who picks the allocation. The split is what stops a manager listing a token they minted themselves, or pairing a real asset with a feed they control. See the *Managed Fund* chapter.

### custody

Expand Down Expand Up @@ -377,9 +377,13 @@ The human-scale denomination of an asset: the dollar, the SOL, the whole share.

The maker posted the resting order; the taker crossed the spread to hit it. Fills execute at the maker's posted price, and fee schedules usually distinguish the two roles.

### managed fund

The onchain equivalent of a mutual fund: pooled deposits, a mandate fixing which assets may be held, a [manager](#manager) who sets the allocation, and shares priced against [NAV](#nav-net-asset-value). Several Solana platforms call it a [vault strategy](#vault-strategy). Distinct from a [vault](#vault), which in this book is only ever the token account the money sits in. See the *Managed Fund* chapter.

### manager

In a fund, the authority that sets the allocation and earns the management fee, and that can do nothing else: no instruction handler gives them a path to the assets. What a careless manager can still cost depositors is churn, rebalancing that pays [slippage](#slippage) for nothing. See [curator](#curator) and the *Vault Strategy* chapter.
In a fund, the authority that sets the allocation and earns the management fee, and that can do nothing else: no instruction handler gives them a path to the assets. What a careless manager can still cost depositors is churn, rebalancing that pays [slippage](#slippage) for nothing. See [curator](#curator) and the *Managed Fund* chapter.

### mantissa

Expand Down Expand Up @@ -523,7 +527,7 @@ The thing a market states its prices in (USDC), and the unit a **quote amount**

### rebalance

Trading a fund back toward its target weights after prices have moved it away. In this book's fund every leg routes through the same swap program at oracle-anchored minimums, so a rebalance cannot be dressed up as a withdrawal. See the *Vault Strategy* chapter.
Trading a fund back toward its target weights after prices have moved it away. In this book's fund every leg routes through the same swap program at oracle-anchored minimums, so a rebalance cannot be dressed up as a withdrawal. See the *Managed Fund* chapter.

### receipt

Expand Down Expand Up @@ -617,10 +621,6 @@ A token designed to hold a fixed value, usually one dollar. The quote asset of n

A technique for storing bulk data offchain with onchain proofs, used for things like very large NFT collections. It is the reason "nearly all", rather than "all", data on Solana lives in accounts; none of the financial state in this book uses it.

### strategy

The fund-shaped product: pooled deposits, a mandate fixing which assets may be held, a [manager](#manager) who sets the allocation, and shares priced against [NAV](#nav-net-asset-value). Distinct from a [vault](#vault), which in this book is only ever the token account the money sits in. See the *Vault Strategy* chapter.

### strike

The price at which an [option](#option) trades if its holder exercises. The *Options* chapter stores it as an amount of the quote token per contract rather than as a price, so every settlement is a multiplication with no division to round.
Expand Down Expand Up @@ -675,7 +675,11 @@ A computer running the Solana software: it executes transactions, votes on block

### vault

A token account whose authority is a program's PDA, where a program holds funds mid-lifecycle. In this book, always the token account, never the whole product; the fund-shaped product is a [strategy](#strategy).
A token account whose authority is a program's PDA, where a program holds funds mid-lifecycle. In this book, always the token account, never the whole product; the fund-shaped product is a [managed fund](#managed-fund).

### vault strategy

Another name for a [managed fund](#managed-fund), used by several Solana platforms, and the name this book's managed-fund example had before it took the finance term. This book avoids it because a [vault](#vault) here is a token account, not a product. See the *Managed Fund* chapter.

### WAD

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -140,4 +140,4 @@ Six concepts came with the curve:
- **The inflation-attack defense.** A locked minimum of LP supply, never minted to anyone and counted in the divisor on the way in and on the way out, keeps the share divisor from ever being dust-sized.
- **Impermanent loss.** An LP is a bet on trading volume, not price direction, and nobody should provide liquidity without being able to draw the diagram.

In the *Prop AMM* chapter we will build a market maker that quotes its own capital at prices taken from an oracle. There is no curve, so a trade does not move the price and there is no impermanent loss, but the firm carries a different risk: the traders who arrive while its quote is stale know something it does not. The *Vault Strategy* chapter, later in the book, uses venues like these to trade other people's money, and the question there is what the manager is allowed to do with it.
In the *Prop AMM* chapter we will build a market maker that quotes its own capital at prices taken from an oracle. There is no curve, so a trade does not move the price and there is no impermanent loss, but the firm carries a different risk: the traders who arrive while its quote is stale know something it does not. The *Managed Fund* chapter, later in the book, uses venues like these to trade other people's money, and the question there is what the manager is allowed to do with it.
2 changes: 1 addition & 1 deletion building-financial-products-in-solana/escrow.md
Original file line number Diff line number Diff line change
Expand Up @@ -151,6 +151,6 @@ The escrow gave you five concepts:
- **An exit from every state.** `take_offer()` and `cancel_offer()` both empty and close everything, returning the tokens and the account rent deposits to whoever they belong to, so neither is stranded.
- **Minor units.** Every amount is an integer at the mint's declared scale, and identical integers can mean entirely different things.

In the *Token Fundraiser* chapter we will build an escrow with many depositors instead of one maker. Contributions collect in one vault until a deadline, and the deadline decides which exit opens: the money goes to the person raising it if the target was reached, and back to every contributor if it was not. Most programs in the rest of this part keep this chapter's shape, a vault owned by a data account with an exit from every state, and change what decides the exit.
In the *Fundraiser* chapter we will build an escrow with many depositors instead of one maker. Contributions collect in one vault until a deadline, and the deadline decides which exit opens: the money goes to the person raising it if the target was reached, and back to every contributor if it was not. Most programs in the rest of this part keep this chapter's shape, a vault owned by a data account with an exit from every state, and change what decides the exit.

[^remittance-cost]: The World Bank's figures for the third quarter of 2025, which put the global average near 6.5% with thirteen corridors above 20%. See [remittanceprices.worldbank.org](https://remittanceprices.worldbank.org).
Loading
Loading