@typesol/cli 0.24.0 → 0.25.0

package/docs/case-study-escrow.md

@@ -0,0 +1,224 @@
+# Case study: porting Anchor's escrow
+
+This page follows one complete Anchor program into TypeSOL: the token escrow from
+[solana-developers/program-examples](https://github.com/solana-developers/program-examples/tree/de090195e4de698e150572c4f886c333323a64a5/tokens/escrow/anchor)
+(`tokens/escrow`, commit `de09019`). It shows the original and the port side by side, what changed, how the two were
+checked against each other, where they still differ, and what the port costs to run. The port is
+[`test/ports/tokens/escrow.ts`](../test/ports/tokens/escrow.ts); [Migrate from Anchor](migrate-from-anchor.md) is the
+general reference.
+
+## The program
+
+A maker offers an amount of token A for an amount of token B.
+
+- `make_offer(id, token_a_offered_amount, token_b_wanted_amount)` creates the offer account, a PDA at
+  `["offer", maker, id]`, creates the vault (the offer's associated token account for mint A) and moves the offered
+  tokens into it.
+- `take_offer()` sends token B from the taker to the maker, releases the vault to the taker, closes the vault and the
+  offer, and returns their rent to the maker. It creates the taker's mint A account and the maker's mint B account if
+  they do not exist.
+- `refund_offer()` returns the vault to the maker and closes both accounts.
+
+Upstream, this is 398 lines of Rust in ten files. The port is one 95-line TypeScript file.
+
+## Side by side
+
+### State
+
+```rust
+#[account]
+#[derive(InitSpace)]
+pub struct Offer {
+    pub id: u64,
+    pub maker: Pubkey,
+    pub token_mint_a: Pubkey,
+    pub token_mint_b: Pubkey,
+    pub token_b_wanted_amount: u64,
+    pub bump: u8,
+}
+```
+
+```ts
+export interface Offer {
+  id: u64;
+  maker: Pubkey;
+  tokenMintA: Pubkey;
+  tokenMintB: Pubkey;
+  tokenBWantedAmount: u64;
+  bump: u8;
+}
+```
+
+The account has the same discriminator and the same Borsh bytes: an Anchor client decodes a TypeSOL offer unchanged.
+Field names are camelCase in TypeScript and snake_case in the IDL, as Anchor writes them.
+
+### make_offer
+
+Anchor declares the accounts in a struct with constraint attributes, then splits the work into helper functions:
+
+```rust
+#[derive(Accounts)]
+#[instruction(id: u64)]
+pub struct MakeOffer<'info> {
+    #[account(mut)]
+    pub maker: Signer<'info>,
+    #[account(mint::token_program = token_program)]
+    pub token_mint_a: InterfaceAccount<'info, Mint>,
+    #[account(mint::token_program = token_program)]
+    pub token_mint_b: InterfaceAccount<'info, Mint>,
+    #[account(mut, associated_token::mint = token_mint_a, associated_token::authority = maker,
+              associated_token::token_program = token_program)]
+    pub maker_token_account_a: InterfaceAccount<'info, TokenAccount>,
+    #[account(init, payer = maker, space = ANCHOR_DISCRIMINATOR + Offer::INIT_SPACE,
+              seeds = [b"offer", maker.key().as_ref(), id.to_le_bytes().as_ref()], bump)]
+    pub offer: Account<'info, Offer>,
+    #[account(init, payer = maker, associated_token::mint = token_mint_a, associated_token::authority = offer,
+              associated_token::token_program = token_program)]
+    pub vault: InterfaceAccount<'info, TokenAccount>,
+    pub associated_token_program: Program<'info, AssociatedToken>,
+    pub token_program: Interface<'info, TokenInterface>,
+    pub system_program: Program<'info, System>,
+}
+// + send_offered_tokens_to_vault (a TransferChecked CPI through a shared transfer_tokens helper)
+// + save_offer (offer.set_inner(Offer { … bump: context.bumps.offer }))
+```
+
+In TypeSOL the accounts are the function's parameters, in the same order, and each constraint is part of the
+parameter's type:
+
+```ts
+export function makeOffer(
+  maker: Mut<Signer>,
+  tokenMintA: MintOf<Mint, never, never, "tokenProgram">,
+  tokenMintB: MintOf<Mint, never, never, "tokenProgram">,
+  makerTokenAccountA: Ata<Mut<TokenAccount>, "maker", "tokenMintA">,
+  offer: Init<Offer>,
+  vault: Ata<Init<TokenAccount>, "offer", "tokenMintA">,
+  associatedTokenProgram: AssociatedTokenProgram,
+  tokenProgram: TokenInterface,
+  systemProgram: SystemProgram,
+  id: u64,
+  tokenAOfferedAmount: u64,
+  tokenBWantedAmount: u64,
+): void {
+  offer.bump = offer.create(maker, ["offer", maker.key, id]);
+  vault.create(maker);
+  tokenProgram.transferChecked(makerTokenAccountA, tokenMintA, vault, maker, tokenAOfferedAmount);
+  offer.id = id;
+  offer.maker = maker.key;
+  offer.tokenMintA = tokenMintA.key;
+  offer.tokenMintB = tokenMintB.key;
+  offer.tokenBWantedAmount = tokenBWantedAmount;
+}
+```
+
+`MintOf<Mint, never, never, "tokenProgram">` is `mint::token_program = token_program`: the mint must be owned by
+the token program passed (2022 otherwise). `offer.create` finds the canonical bump, creates the PDA with the computed space and returns the bump, which Anchor
+exposes as `context.bumps.offer`. `transferChecked` reads the mint's decimals itself.
+
+### take_offer and refund_offer
+
+The offer is checked declaratively, as in Anchor: the seeds come from the maker account and the offer's own `id`
+field, and the stored bump is used.
+
+```rust
+#[account(mut, close = maker, has_one = maker, has_one = token_mint_a, has_one = token_mint_b,
+          seeds = [b"offer", maker.key().as_ref(), offer.id.to_le_bytes().as_ref()], bump = offer.bump)]
+offer: Account<'info, Offer>,
+```
+
+```ts
+offer: Seeds<CloseTo<HasOne<Mut<Offer>, "maker" | "tokenMintA" | "tokenMintB">, "maker">, ["offer", "@maker", "@offer.id"], "bump">,
+```
+
+The body signs for the vault with the offer's seeds, where Anchor builds a `signer_seeds` array and a
+`CpiContext::new_with_signer` for each call:
+
+```ts
+takerTokenAccountA.createIfNeeded(taker);
+makerTokenAccountB.createIfNeeded(taker);
+tokenProgram.transferChecked(takerTokenAccountB, tokenMintB, makerTokenAccountB, taker, offer.tokenBWantedAmount);
+tokenProgram.transferChecked(vault, tokenMintA, takerTokenAccountA, offer, vault.amount, ["offer", maker.key, offer.id, offer.bump]);
+tokenProgram.closeAccount(vault, maker, offer, ["offer", maker.key, offer.id, offer.bump]);
+```
+
+`CloseTo<…, "maker">` closes the offer after the body returns, as Anchor's `close = maker` does.
+
+## What changed
+
+| Anchor | Port |
+| --- | --- |
+| `Signer`, `SystemAccount` (`#[account(mut)]`) | `Mut<Signer>`, `Mut<SystemAccount>` |
+| `InterfaceAccount<Mint>`, `InterfaceAccount<TokenAccount>` | `Mint`, `TokenAccount` |
+| `mint::token_program = token_program` | `MintOf<Mint, never, never, "tokenProgram">` |
+| `associated_token::mint = m, associated_token::authority = a` | `Ata<TokenAccount, "a", "m">` |
+| `init` / `init_if_needed` on an associated token account | `Ata<Init<…>>` + `vault.create(payer)` / `Ata<InitIfNeeded<…>>` + `createIfNeeded(payer)` |
+| `init, seeds, bump` + `context.bumps.offer` | `Init<Offer>` + `offer.bump = offer.create(maker, seeds)` |
+| `seeds = […], bump = offer.bump` | `Seeds<…, ["offer", "@maker", "@offer.id"], "bump">` |
+| `has_one`, `close` | `HasOne<…>`, `CloseTo<…>` |
+| `transfer_checked(CpiContext::new_with_signer(…), amount, decimals)` | `tokenProgram.transferChecked(from, mint, to, authority, amount, seeds)` |
+| `ErrorCode::CustomError` (unused upstream) | `enum ErrorCode`, the same code 6000 |
+
+Nothing in the program needed a construct TypeSOL lacks, and every account constraint has its TypeSOL form; the port
+is marked PORTED in [the ports table](../test/ports/README.md).
+
+## Same inputs, same results
+
+Two independent checks run the original and the port against each other.
+
+- **The port's own test** ([`test/ports-tokens.test.ts`](../test/ports-tokens.test.ts)) runs the upstream flow with SPL
+  Token mints and again with Token-2022 mints: make, take (creating the taker's and the maker's missing token accounts),
+  make again, a refund attempt by someone other than the maker, and the refund. It checks balances, the decoded offer
+  and that offer and vault are closed.
+- **The four-way comparison** in [typesol/benchmarks](https://github.com/typesol/benchmarks) builds the upstream Anchor,
+  native and Pinocchio versions unmodified and sends all four the same 21 offers (ten taken, ten refunded, one left
+  open). The decoded open offer, every token balance, the vault's authority and which accounts were closed must be
+  identical before any number is reported. They are.
+
+Both implementations refuse the hostile calls the comparison makes:
+
+| Hostile call | Anchor | TypeSOL |
+| --- | --- | --- |
+| refund_offer signed by someone other than the maker | 2006 ConstraintSeeds | 2006 ConstraintSeeds |
+| take_offer naming the taker as the maker | 2015 ConstraintTokenOwner | 2040 ConstraintDuplicateMutableAccount |
+
+TypeSOL checks each account's constraints in Anchor's order, so a refused transaction usually gets the same error
+code (see [which error a transaction gets](errors.md#which-error-a-transaction-gets)). The second call differs on
+purpose: taker and maker are then the same writable account, which TypeSOL refuses for any two writable parameters,
+where Anchor only compares program and token accounts and fails later, on the maker's token account. A client that
+matches on this code needs to accept either.
+
+## Cost
+
+Mean compute units per instruction in LiteSVM (21 make_offer, 10 take_offer and 10 refund_offer calls), and the
+program size, from typesol/benchmarks (TypeSOL at this version; Anchor 1.0.2). Lower is better.
+
+| | TypeSOL | Anchor | Native Rust | Pinocchio |
+| --- | ---: | ---: | ---: | ---: |
+| make_offer | **19,697** | 35,726 | 33,206 | 20,581 |
+| take_offer | **7,053** | 29,235 | 24,995 | 21,606 |
+| refund_offer | **4,271** | 15,326 | 12,477 | 8,137 |
+| Binary | 32.0 KB | 244.5 KB | 120.4 KB | **25.1 KB** |
+
+Most of `make_offer` in every version is the Associated Token Account program creating the vault. The native and
+Pinocchio versions are teaching code with fewer checks (no owner or type check on the offer, `Transfer` instead of
+`TransferChecked`; Pinocchio takes the offer's bump from the client).
+
+The same program, built with an earlier TypeSOL, runs on mainnet next to the other three; the transactions are listed
+with their Solscan links in the [performance report](https://typesol.com/report/) and the
+[README](../README.md#on-mainnet).
+
+## Porting your own program
+
+The steps this port followed, in order:
+
+1. Generate the skeleton from the Anchor IDL: `npx typesol port target/idl/escrow.json --out programs/escrow.ts`. It
+   keeps instruction names, discriminators, account order and error codes.
+2. Turn each `#[account(...)]` into the parameter's type, using the table above and
+   [Accounts and constraints](migrate-from-anchor.md#accounts-and-constraints). Keep the account order: it is the
+   wire format.
+3. Port the bodies. Helpers like `transfer_tokens` usually disappear into one call; `signer_seeds` arrays become the
+   last argument of the CPI.
+4. Run the upstream test flow against the port with `typesol/testing`, including the failure paths, and compare the
+   decoded accounts.
+5. Compare the IDLs, and check the error codes your clients match on (the table above shows how they can differ).

package/docs/errors.md

@@ -5,6 +5,7 @@ Framework errors use Anchor's numbers where Anchor has the same check, so client
 | Code | Meaning |
 | --- | --- |
 | 100 / 101 / 102 | instruction data missing / unknown instruction / malformed arguments (InstructionMissing / FallbackNotFound / DidNotDeserialize) |
+| 2000 | a `Mut<…>` / `Init<…>` account passed read-only (ConstraintMut) |
 | 2001 | HasOne constraint failed (ConstraintHasOne) |
 | 2002 | event authority did not sign (ConstraintSigner) |
 | 2004 | Owner constraint failed (ConstraintOwner) |
@@ -15,6 +16,7 @@ Framework errors use Anchor's numbers where Anchor has the same check, so client
 | 2012 | not the expected address (ConstraintAddress) |
 | 2014 / 2015 | token account mint / owner mismatch (ConstraintTokenMint / ConstraintTokenOwner) |
 | 2016 / 2017 / 2018 | mint authority / freeze authority / decimals mismatch (2018: an existing mint `createIfNeeded` found) |
+| 2021 / 2022 | token account / mint not owned by the token program `TokenOf` / `MintOf` names (ConstraintTokenTokenProgram / ConstraintMintTokenProgram) |
 | 2024–2039 | an existing mint `createIfNeeded` found lacks a Token-2022 extension it was given, or holds other keys in it: group pointer 2024–2026, group member pointer 2027–2029, metadata pointer 2030–2032, close authority 2033–2034, permanent delegate 2035–2036, transfer hook 2037–2039 (the first code of each: the extension is missing; the next: the authority / address differs) (ConstraintMint…Extension…) |
 | 2040 | the same account passed in two writable slots (ConstraintDuplicateMutableAccount) |
 | 3000 | account already exists / initialized (AccountDiscriminatorAlreadySet) |
@@ -22,7 +24,7 @@ Framework errors use Anchor's numbers where Anchor has the same check, so client
 | 3003 | data too small, not an initialized token account / mint, a read past the end, or a `@layout borsh` account whose bytes are not a valid Borsh value (AccountDidNotDeserialize) |
 | 3004 | a `@layout borsh` account too small for the value it would now hold (AccountDidNotSerialize) |
 | 3005 | not enough accounts (AccountNotEnoughKeys) |
-| 3006 | account must be writable (AccountNotMutable) |
+| 3006 | a remaining account or CPI account the program needs writable was passed read-only (AccountNotMutable) |
 | 3007 | wrong owner program (AccountOwnedByWrongProgram) |
 | 3008 / 3009 | wrong program address / not executable (InvalidProgramId / InvalidProgramExecutable) |
 | 3010 | account must sign (AccountNotSigner; also a new keypair account a `create(payer, null, …)` makes) |
@@ -47,3 +49,26 @@ Framework errors use Anchor's numbers where Anchor has the same check, so client
 
 Any of Anchor's own codes can be raised directly: `require(cond, AnchorError.RequireKeysEqViolated)` fails with 2502,
 as `require_keys_eq!` does.
+
+## Which error a transaction gets
+
+A transaction can break several checks; it fails with the first. Within each account's constraints the checks run in
+the order Anchor's generated code runs them, so a transaction gets the same code under both:
+
+1. The account count (3005), then each account in parameter order: its type, signer (3010), `Mut` (2000), owner,
+   discriminator and size of a program account (3007 / 3012 / 3002 / 3003), token account or mint, program address.
+2. Two writable parameters naming one account (2040).
+3. The instruction's arguments (102).
+4. Each account in parameter order, its constraints in Anchor's order: seeds (2006), associated token account (owner
+   2015, then address 2009), `has_one` (2001), owner (2004), executable (2007), address (2012), then `TokenOf` /
+   `MintOf` (2015, 2014, 2021 / 2016, 2017, 2022).
+
+Where TypeSOL's order differs, only a transaction that breaks two of these checks at once sees it:
+
+- Anchor decodes the arguments first, and checks `mut` with the constraints (after seeds and the associated token
+  account). TypeSOL keeps both earlier and later as above, which keeps binaries smaller.
+- Too few accounts fails with 3005 before any account is checked; Anchor fails on the first account it cannot find.
+- Accounts the instruction creates (`Init<…>`, `create(…)`) are created in the body, after every other check, where
+  Anchor creates them before checking the other accounts.
+- TypeSOL refuses any two writable parameters naming one account (2040), where Anchor only compares program and token
+  accounts: a signer passed as two writable parameters fails with 2040 here and later, or not at all, under Anchor.

package/docs/language.md

@@ -38,8 +38,8 @@ The full reference. For a tour, start with the [README](../README.md).
 | Option of structs | `home: Option<Point>` in account data — `=== null`, `p.home.x` after narrowing, `p.home = null` / `{ x, y }` |
 | Strings at runtime | `"hello, " + name`, `` `#${n}` ``, `` `owner ${acct.owner}` `` (a Pubkey or Hash as base58) — built on the 32 KiB heap (5110 when full): a template is joined in one allocation, text known at compile time (literals, string and Pubkey constants) is folded in, and `s += …` grows the newest heap string in place |
 | `switch` | on integers (128-bit ones too), enums and data-enum `.kind`, with JS `break` / fallthrough; case labels are literals, constants or enum members |
-| Hashing & signatures | `sha256(...)`, `keccak256(...)` → `Hash`; `findProgramAddress(seeds, program)` → the canonical PDA of any program (Rust `Pubkey::find_program_address(..).0`, e.g. a Bubblegum asset id); `merkleVerify(leaf, proof: Vec<Hash>, root)` (sorted-pair keccak, OpenZeppelin convention); `verifyEd25519(instructionsSysvar, signer, message)` checks an Ed25519 precompile instruction in the same transaction; `verifySecp256k1(keccak256(...message) | ethMessageHash(message), recoveryId, r, s, ethAddress)` (the hash must be computed in the program; a passed-in hash could be forged) |
-| Oracles | `pythPrice(update: PythPriceUpdate, feedId, maxAgeSeconds)` (fully verified, feed-matched, fresh); raw `update.price / conf / exponent / publishTime`; `switchboardValue(feed: SwitchboardFeed, expectedFeed, maxStaleSlots, decimals)` (the feed must be the expected one: anyone can create feeds) (mainnet program unless `SwitchboardFeed<"devnet">`) |
+| Hashing & signatures | `sha256(...)`, `keccak256(...)` → `Hash`; `findProgramAddress(seeds, program)` → the canonical PDA of any program (Rust `Pubkey::find_program_address(..).0`, e.g. a Bubblegum asset id); `merkleVerify(leaf, proof: Vec<Hash>, root)` (sorted-pair keccak, OpenZeppelin convention; inner nodes and leaves are hashed alike, so hash leaves as OpenZeppelin does, `keccak256(keccak256(data))`, and never take the leaf itself from the arguments: an inner node would pass as a leaf); `verifyEd25519(instructionsSysvar, signer, message)` checks an Ed25519 precompile instruction in the same transaction; `verifySecp256k1(keccak256(...message) | ethMessageHash(message), recoveryId, r, s, ethAddress)` (the hash must be computed in the program; a passed-in hash could be forged) |
+| Oracles | `pythPrice(update: PythPriceUpdate, feedId, maxAgeSeconds, exponent?)` (fully verified, feed-matched, fresh; with `exponent`, a feed at another scale is refused); raw `update.price / conf / exponent / publishTime` are unchecked (any feed, partially verified or stale: check `feedId`, `fullyVerified` and the age yourself, or use `pythPrice`); `switchboardValue(feed: SwitchboardFeed, expectedFeed, maxStaleSlots, decimals, minSamples?)` (the feed must be the expected one: anyone can create feeds; `minSamples`, default 1, the fewest oracle samples accepted) (mainnet program unless `SwitchboardFeed<"devnet">`) |
 | Multiple files | `import { Side, min } from "./math"` — structs, enums, constants and helpers can live in other files; only the entry file's exported functions are instructions; names are program-wide, so imports from TypeSOL files cannot be renamed; error codes number imported files first |
 | Loops | `for (let i = 0n; i < n; i++)`, `while`, `do … while`, `for (const x of list)` over a `Vec` or `FixedArray` (each `x` is what `list.get(i)` gives: a value, or a reference into account data for structs; the length is read again every step, as in JS), `break`, `continue` — bounded by the compute budget. Remaining accounts are iterated by index |
 | Helpers | non-exported functions (and every function of an imported file): take values, structs, Vec arguments, `SignerSeeds` and accounts the instruction already checked (`Signer`, `AccountInfo`/`AccountMeta`, `Mut<T>`, token accounts, programs); return `void`, a scalar, a `string`, a function (see below) or a fixed-size struct (`function at(x: u64, y: u64): Point { return { x, y }; }`: the caller gets its own copy, to bind, store with `acct.home = at(…)` / `arr.set(i, at(…))` or read as `at(…).x`); no recursion. A helper that takes a struct account as `Mut<T>` can grow its Vec (`push(value, payer)`: the account's size at instruction entry is passed along) |
@@ -65,9 +65,9 @@ The full reference. For a tour, start with the [README](../README.md).
 | `Signer` / `Mut<Signer>` | signed (and writable) |
 | `Account<T>` / `Mut<T>` | owned by this program, 8-byte discriminator matches, data large enough (and writable) |
 | `Init<T>` | writable; `create(payer, seeds)` derives the PDA, verifies it, funds rent, writes the discriminator (up to 10 KiB); `create(payer, null)` creates a new keypair account that signs the transaction instead (3010 if it did not; a signer in the IDL); a third argument is Anchor's `space = …` (discriminator included, at least 8 + the struct's size) |
-| `InitIfNeeded<T>` | `const created = acct.createIfNeeded(payer, seeds)` — creates once; afterwards re-derives the PDA and checks owner, discriminator and size (Anchor `init_if_needed`); `acct.pdaBump` after create |
+| `InitIfNeeded<T>` | `const created = acct.createIfNeeded(payer, seeds)` — creates once; afterwards re-derives the PDA and checks owner, discriminator and size (Anchor `init_if_needed`); `acct.pdaBump` after create. An existing account is used as it is: check the fields you rely on |
 | `HasOne<A, "owner">`, `Seeds<A, ["vault", "@owner"], "bump">`, `CloseTo<A, "owner">` | declarative constraints like Anchor's `has_one`, `seeds`/`bump` and `close`: checked before the body (2001 / 2006), close runs when the instruction succeeds; `"@name"` = account key or argument bytes, `"@acct.field"` = a Pubkey, integer or unit enum field of a struct account parameter (also the account's own: `["offer", "@maker", "@offer.id"]`), other strings are literals; recorded as `relations` / `pda` in the IDL. `acct.pdaBump` is the bump (Anchor `ctx.bumps.acct`): the stored field when one is named, else the canonical bump the check found — use it to sign as the PDA |
-| `HasOne<TokenAccount, "mint" \| "owner">`, `HasOne<Mint, "mintAuthority" \| "freezeAuthority">` | token constraints (2014 / 2015 / 2016 / 2017) against the parameter with that name; `TokenOf<TokenAccount, "mintParam", "authorityParam">` / `MintOf<Mint, "authorityParam", "freezeParam">` name the parameters, as Anchor's `token::mint = …` / `mint::authority = …` do (`never` leaves one out) |
+| `HasOne<TokenAccount, "mint" \| "owner">`, `HasOne<Mint, "mintAuthority" \| "freezeAuthority">` | token constraints (2014 / 2015 / 2016 / 2017) against the parameter with that name; `TokenOf<TokenAccount, "mintParam", "authorityParam", "tokenProgramParam">` / `MintOf<Mint, "authorityParam", "freezeParam", "tokenProgramParam">` name the parameters, as Anchor's `token::mint = …` / `mint::authority = …` / `…::token_program = …` do (`never` leaves one out; the token program one: owned by that token program, 2021 / 2022) |
 | `Ata<TokenAccount, "owner", "mint">` | the account is the associated token account of those parameters (2009; ATA `pda` in the IDL) |
 | `Ata<Init<TokenAccount>, "owner", "mint">`, `Ata<InitIfNeeded<TokenAccount>, "owner", "mint">` | Anchor `init` / `init_if_needed` with `associated_token::…`: `acct.create(payer)` creates the ATA (fails if it exists); `const created = acct.createIfNeeded(payer)` creates it only when missing, otherwise checks it is that ATA (2009). Then it is a `TokenAccount` of that mint and owner (2014 / 2015). Needs `AssociatedTokenProgram`, `SystemProgram` and a token program parameter; call it at the top level before using the account |
 | `Address<A, "4Nd1…">` | exact address (2012; `address` in the IDL) |
@@ -77,8 +77,8 @@ The full reference. For a tour, start with the [README](../README.md).
 | `ProgramData` | this program's ProgramData (address derived from the program id, upgradeable-loader owner and state checked); `upgradeAuthority`, `deploySlot` — gate admin setup on `programData.upgradeAuthority === admin.key` |
 | `EventAuthority`, `SelfProgram` | Anchor's `["__event_authority"]` PDA, and this program's own address, for `emitCpi` |
 | `Zeroed<T>` | large accounts (up to 10 MiB) the client allocated with System `CreateAccount`: owned by this program, big enough, rent-exempt, discriminator still zero — then initialized; like Anchor's zero-copy `zero` |
-| `Init<Mint>`, `InitIfNeeded<Mint>` | Anchor `init` / `init_if_needed` with `mint::decimals` / `mint::authority` / `mint::freeze_authority`: `const bump = mint.create(payer, ["mint", payer.key], 6n, authority, freezeAuthority \| null)` creates the mint at that PDA of this program, or with `null` seeds as a new keypair account that signs (3010 if it did not), under the instruction's token program (its only token program parameter, or one passed as the last argument of `create` / `createIfNeeded`; plus `SystemProgram`). Token-2022 extensions (Anchor's `extensions::…`) go after the freeze authority: `mint.create(payer, null, 6n, authority, null, { metadataPointer: { authority, metadataAddress: mint.key }, transferHook: { authority, programId }, closeAuthority, permanentDelegate, nonTransferable: true, defaultAccountState: true, interestBearing: { rateAuthority, rate }, transferFee: { configAuthority, withdrawAuthority, basisPoints, maximumFee }, groupPointer, groupMemberPointer })` sizes the mint for them and initializes each before InitializeMint2. With `createIfNeeded` an existing mint must carry groupPointer / groupMemberPointer / metadataPointer / closeAuthority / permanentDelegate / transferHook with those keys (Anchor's 2024–2039). `createIfNeeded(…)` returns whether it created it; an existing one must be that PDA and have those decimals and authorities (2018 / 2016 / 2017) |
-| `Init<TokenAccount>`, `InitIfNeeded<TokenAccount>` (no `Ata<…>`) | Anchor `init` / `init_if_needed` with `token::mint` / `token::authority`: `vault.create(payer, ["vault", mint.key], mint, authority)` (the authority may be `vault.key` itself) creates a token account at that PDA (or a keypair account with `null`), sized for the mint's extensions under Token-2022. `createIfNeeded` checks an existing one has that mint and owner (2014 / 2015) |
+| `Init<Mint>`, `InitIfNeeded<Mint>` | Anchor `init` / `init_if_needed` with `mint::decimals` / `mint::authority` / `mint::freeze_authority`: `const bump = mint.create(payer, ["mint", payer.key], 6n, authority, freezeAuthority \| null)` creates the mint at that PDA of this program, or with `null` seeds as a new keypair account that signs (3010 if it did not), under the instruction's token program (its only token program parameter, or one passed as the last argument of `create` / `createIfNeeded`; plus `SystemProgram`). Token-2022 extensions (Anchor's `extensions::…`) go after the freeze authority: `mint.create(payer, null, 6n, authority, null, { metadataPointer: { authority, metadataAddress: mint.key }, transferHook: { authority, programId }, closeAuthority, permanentDelegate, nonTransferable: true, defaultAccountState: true, interestBearing: { rateAuthority, rate }, transferFee: { configAuthority, withdrawAuthority, basisPoints, maximumFee }, groupPointer, groupMemberPointer })` sizes the mint for them and initializes each before InitializeMint2. With `createIfNeeded` an existing mint must carry groupPointer / groupMemberPointer / metadataPointer / closeAuthority / permanentDelegate / transferHook with those keys (Anchor's 2024–2039); extensions not listed are not looked at, so an existing mint may carry others (a permanent delegate, say). `createIfNeeded(…)` returns whether it created it; an existing one must be that PDA and have those decimals and authorities (2018 / 2016 / 2017) |
+| `Init<TokenAccount>`, `InitIfNeeded<TokenAccount>` (no `Ata<…>`) | Anchor `init` / `init_if_needed` with `token::mint` / `token::authority`: `vault.create(payer, ["vault", mint.key], mint, authority)` (the authority may be `vault.key` itself) creates a token account at that PDA (or a keypair account with `null`), sized for the mint's extensions under Token-2022. `createIfNeeded` checks an existing one has that mint and owner (2014 / 2015), not its delegate or close authority (as Anchor) |
 | `TokenAccount` / `Mut<TokenAccount>` | owned by SPL Token or Token-2022 (extensions allowed, multisig accounts refused), initialized; `mint`, `owner`, `amount`, `delegate`, `delegatedAmount`, `isFrozen`, `isNative`, `closeAuthority`, `tokenProgram` |
 | `Mint` / `Mut<Mint>` | owned by SPL Token or Token-2022, initialized; `decimals`, `supply`, `mintAuthority`, `freezeAuthority`, `tokenProgram` |
 | `SystemProgram`, `TokenProgram`, `Token2022Program` | exact program address |
@@ -94,7 +94,9 @@ The full reference. For a tour, start with the [README](../README.md).
 Every account exposes `key`, `lamports`, `dataLen`, `isSigner`, `isWritable`. At most 32 accounts per instruction (more is refused, 5113).
 
 Two writable parameters can never be the same account: aliasing is refused with error 2040 (also when a remaining
-account written through `.lamports` or `loadAccountMut` is another account of the instruction).
+account written through `.lamports` or `loadAccountMut` is another account of the instruction). A remaining account
+can be loaded with `loadAccountMut` once per instruction: loading the same one again (`rest.get(i)` and `rest.get(j)`
+with `i == j`) is refused with 2040 too, since the two views would alias.
 
 ## Built-ins
 
@@ -106,7 +108,9 @@ account written through `.lamports` or `loadAccountMut` is another account of th
   `freezeAccount` / `thawAccount(account, mint, freezeAuthority)`, `syncNative(account)`, `initializeMint2(mint, decimals, mintAuthority, freezeAuthority | null)`,
   `initializeAccount3(account, mint, owner)`, and on Token-2022 `initializeMetadata(mint, updateAuthority, mintAuthority, name, symbol, uri)` (metadata extension) and the extension initializers to call between `createAccount` and `initializeMint2` / `initializeAccount3`: `initializeTransferFeeConfig(mint, configAuthority | null, withdrawAuthority | null, basisPoints, maximumFee)`, `initializeMintCloseAuthority(mint, authority | null)`, `initializeNonTransferableMint(mint)`, `initializePermanentDelegate(mint, delegate)`, `initializeDefaultAccountState(mint, frozen)`, `initializeMetadataPointer` / `initializeGroupPointer` / `initializeGroupMemberPointer` / `initializeTransferHook(mint, authority | null, address | null)`, `initializeInterestBearingMint(mint, rateAuthority | null, rate)`, `initializeImmutableOwner(account)`; the extension instructions `updateDefaultAccountState(mint, freezeAuthority, frozen)`, `updateTransferHook(mint, authority, programId | null)`, `enableRequiredMemoTransfers` / `disableRequiredMemoTransfers(account, owner)`, `updateInterestRate(mint, rateAuthority, rate)`, `transferCheckedWithFee(from, mint, to, authority, amount, fee)`, `harvestWithheldTokensToMint(mint, remainingAccounts())`, `withdrawWithheldTokensFromMint(mint, destination, authority)`, `setTransferFee(mint, authority, basisPoints, maximumFee)`; and the Token Metadata interface `updateMetadataField(mint, updateAuthority, field, value)` ("name" / "symbol" / "uri" or any other key), `removeMetadataKey(mint, updateAuthority, key, idempotent)`, `updateMetadataAuthority(mint, updateAuthority, next | null)`, `emitMetadata(mint)`. Each takes optional signerSeeds
 - `account.lamports` read/write on `Mut` accounts, `close(account, destination)` for program accounts
-- `requirePda(account, seeds, bump)`
+- `requirePda(account, seeds, bump)`: any bump that gives a valid PDA passes, as with Anchor's `bump = expr`. Use a bump
+  stored when the account was created (or `Seeds<…>`); one taken from the instruction's arguments lets the caller pick
+  among up to 256 addresses for the same seeds
 
 ## Implementing another program's interface (transfer hooks)
 

package/docs/migrate-from-anchor.md

@@ -2,7 +2,8 @@
 
 TypeSOL programs speak Anchor's wire format: the same instruction and account discriminators, Borsh arguments, an
 Anchor-format IDL, the same error numbering and event logs. A ported program can keep its clients. This page maps
-Anchor's constructs to TypeSOL's and shows the porting workflow.
+Anchor's constructs to TypeSOL's and shows the porting workflow. For one complete program ported this way, with the
+original side by side, the checks run against it and its cost, see [Case study: porting Anchor's escrow](case-study-escrow.md).
 
 ## Start from the IDL
 
@@ -50,6 +51,7 @@ and error codes. Its notes (on stderr) list what an existing Anchor client would
 | `Program<'info, Token>` / `Token2022` / `Interface<'info, TokenInterface>` | `TokenProgram` / `Token2022Program` / `TokenInterface` |
 | `Account<'info, TokenAccount>` / `Account<'info, Mint>` (`InterfaceAccount`) | `TokenAccount` / `Mint` (`Mut<…>` when written) |
 | `token::mint = m, token::authority = a` | `TokenOf<TokenAccount, "m", "a">` (2014 / 2015), or `HasOne<TokenAccount, "mint" \| "owner">` when the parameters have those names; `mint::authority = a, mint::freeze_authority = f` on an existing mint: `MintOf<Mint, "a", "f">` (2016 / 2017) |
+| `mint::token_program = tp` / `token::token_program = tp` | `MintOf<Mint, never, never, "tp">` / `TokenOf<TokenAccount, never, never, "tp">` (2022 / 2021) |
 | `extensions::metadata_pointer::authority = a, …` (with `mint::…`) | `mint.create(p, …, { metadataPointer: { authority: a.key, metadataAddress: mint.key }, … })`: transferHook, closeAuthority, permanentDelegate, nonTransferable, groupPointer, groupMemberPointer and more |
 | `#[account(init, payer = p, seeds = […], bump, mint::decimals = 6, mint::authority = a, mint::freeze_authority = f)]` | `Init<Mint>`, then `const bump = mint.create(p, […], 6n, a.key, f.key)` (`null` seeds: a keypair mint; `InitIfNeeded<Mint>` + `createIfNeeded`) |
 | `#[account(init, payer = p, seeds = […], bump, token::mint = m, token::authority = a)]` | `Init<TokenAccount>`, then `vault.create(p, […], m, a.key)` (`InitIfNeeded<TokenAccount>` + `createIfNeeded`) |

package/docs/runtime.md

@@ -0,0 +1,59 @@
+# The C runtime
+
+`runtime/typesol_rt.h` is included by every generated program. It holds what the emitted C calls: error codes, the
+entry point's input parser, account checks, checked arithmetic, Borsh helpers, CPIs, sysvars, strings and the heap.
+This page is for people changing it; programs never call it directly.
+
+## Conventions
+
+- **Header-only, `static inline`.** Each program compiles the header with its own code, and `--gc-sections` drops
+  what it does not use. `always_inline` marks the few helpers that must disappear into their caller (word loads and
+  stores, `ts_memcpy`, checked add/subtract); `noinline` marks the ones that should exist once per program because
+  many call sites would otherwise each grow the binary (`ts_fail`, the rent fallback `ts_rent_slow`, PDA search).
+- **Errors are return values.** A function that can fail returns `uint64_t`: `SUCCESS`, or an error code. Fail with
+  `TS_FAIL(code, "TypeSOL: …")` (logs the message, then returns the code) and propagate with `TS_TRY(call)`.
+  Nothing aborts: the instruction returns the code, and the runtime reports it as `Custom(code)`.
+- **Error codes follow Anchor.** Where Anchor has a framework error with the same meaning, its number is used (2006
+  ConstraintSeeds, 3003 AccountDidNotDeserialize, …), so Anchor and Codama clients name failures correctly.
+  TypeSOL-only conditions are 5100–5199; user errors start at 6000. Every code is listed in [errors.md](errors.md).
+- **No byte loops from the SDK.** The SDK's `sol_memcpy`, `sol_memcmp` and `SolPubkey_same` move one byte per
+  iteration. The runtime uses `ts_ld64` / `ts_st64` (unaligned 8-byte loads and stores, which SBF allows) in
+  `ts_memcpy`, `ts_memzero`, `ts_mem_eq`, `ts_key_eq` and `ts_memmove`.
+- **Same results as the reference.** Fast paths must give bit-identical results to what they replace: `ts_add_overflow_u64`
+  matches `__builtin_add_overflow`, the rent fast path and `ts_rent_slow` match the double computation, PDA search
+  matches `sol_try_find_program_address`. A change here needs a test against the reference, not only against itself.
+
+## Sections
+
+In file order:
+
+| Section | What it provides |
+| --- | --- |
+| Error codes, `TS_FAIL`, `TS_TRY` | The codes above and the two macros |
+| Word-wise memory helpers | `ts_ld64`, `ts_st64`, `ts_memcpy`, `ts_memmove`, `ts_memzero`, `ts_mem_eq`; checked u64 add/subtract/multiply |
+| Well-known program ids | System, Token, Token-2022, ATA, Metaplex and the other programs the language names |
+| Strings | `TS_Str` views (pointer, length), UTF-8 validation, comparison, `FixedString<N>` storage |
+| Entry point input | `TsAccount` (the loader's serialized account, read in place), `TsParams`, `ts_deserialize` |
+| Account checks | owner, discriminator, signer, writable, executable, address, size, uniqueness (`ts_check_*`), growable Vec lengths |
+| Little-endian IO | `ts_read_le` and friends for argument decoding and Borsh |
+| Sysvars | clock, rent (`ts_rent`, `ts_minimum_balance_of`, `ts_minimum_balance`), program data |
+| PDA | `ts_pda_hash`, `ts_create_pda_address`, `ts_find_pda` (canonical bump), `ts_require_pda` |
+| System program CPIs | create, assign, allocate, transfer, `ts_create_pda`, `ts_resize` / `ts_realloc`, close |
+| Token-2022 extensions | TLV walking for the extensions the language reads |
+| Metaplex Core and Bubblegum | account readers (`coreAssetOwner`, …) |
+| SPL Token / Token-2022 CPIs | transfer, mint, burn, approve, close, freeze and their checked forms |
+| Return data | `sol_set_return_data` wrappers |
+| Crypto | sha256, keccak256, ed25519 / secp256k1 verification helpers, Merkle proofs |
+| Heap | `ts_alloc`, a bump allocator (32 KiB by default, `HEAP_SIZE_KIB` up to 256), string building (`ts_str_join`, `ts_str_append`, number and base58 text) |
+| Oracles | Pyth price updates, Switchboard |
+| Associated token accounts, token metadata, transfer hooks | ATA derivation and creation, Token Metadata CPIs, transfer-hook extra accounts |
+
+## Changing it
+
+- Every runtime change can move compute units or binary size. Measure it before and after with
+  [typesol/benchmarks](https://github.com/typesol/benchmarks) pointed at your checkout, and put the difference in
+  the pull request (see CONTRIBUTING).
+- A change that alters behavior (a result, an error code, a log line, account bytes) is a language change and goes
+  in the CHANGELOG as one. One that only changes cost says so: "same results".
+- New error codes: add the `#define` here, the row in [errors.md](errors.md) and the name in the compiler's runtime
+  error list (`TYPESOL_ERRORS` in `src/clientgen.ts`), so clients name it (a test checks every code has a name).

package/lib/typesol.d.ts

@@ -162,7 +162,8 @@ export declare function remainingAccounts(): RemainingAccounts;
 
 /**
  * Read a struct of this program from a remaining account: owner, discriminator and size are checked.
- * `loadAccountMut` also requires it to be writable and not aliased by another writable account.
+ * `loadAccountMut` also requires it to be writable, not aliased by another writable account, and not already loaded
+ * with `loadAccountMut` in this instruction (2040).
  */
 export declare function loadAccount<T>(account: RemainingAccount): Readonly<T>;
 export declare function loadAccountMut<T>(account: RemainingAccount): T;
@@ -180,7 +181,8 @@ export declare function keccak256(...parts: (string | Pubkey | Hash | bigint | b
 
 /**
  * Verify a Merkle proof (keccak256, sorted pairs: the OpenZeppelin convention most airdrop tools use).
- * `proof` must be a `Vec<Hash>` instruction argument.
+ * `proof` must be a `Vec<Hash>` instruction argument. Leaves and inner nodes hash alike: build the leaf in the program
+ * as OpenZeppelin does, `keccak256(keccak256(data))`, never take it from the arguments (an inner node would pass).
  */
 export declare function merkleVerify(leaf: Hash, proof: Vec<Hash>, root: Hash): boolean;
 
@@ -211,7 +213,8 @@ export declare function ethMessageHash(message: string): Hash;
 
 /**
  * A Pyth `PriceUpdateV2` account (Pyth Solana Receiver, rec5EKMG…). Owner and discriminator are checked.
- * The fields are the raw update; use pythPrice() for a verified, fresh, feed-matched price.
+ * The fields are the raw update and are NOT checked: it may be only partially verified, for another feed, or stale.
+ * Use pythPrice() for a verified, fresh, feed-matched price (with `exponent` to pin the scale).
  */
 export interface PythPriceUpdate extends AccountMeta {
   readonly __pyth: void;
@@ -223,8 +226,12 @@ export interface PythPriceUpdate extends AccountMeta {
   readonly publishTime: i64;
   readonly fullyVerified: boolean;
 }
-/** Like Pyth's get_price_no_older_than: fully verified, `feedId` matches, published within `maxAgeSeconds`. */
-export declare function pythPrice(update: PythPriceUpdate, feedId: Hash, maxAgeSeconds: u64): i64;
+/**
+ * Like Pyth's get_price_no_older_than: fully verified, `feedId` matches, published within `maxAgeSeconds` (5111
+ * otherwise). The price is in units of 10^exponent: pass the `exponent` your arithmetic assumes and a feed whose
+ * exponent differs is refused, instead of read at the wrong scale.
+ */
+export declare function pythPrice(update: PythPriceUpdate, feedId: Hash, maxAgeSeconds: u64, exponent?: i32): i64;
 
 /**
  * A Switchboard On-Demand pull feed (PullFeedAccountData). Mainnet program unless `SwitchboardFeed<"devnet">`
@@ -237,7 +244,14 @@ export interface SwitchboardFeed<Cluster extends "mainnet" | "devnet" = "mainnet
  * The feed's current result scaled to `decimals` (from 18), if `feed` is `expectedFeed` (anyone can create feeds),
  * it has samples and it is at most `maxStaleSlots` old.
  */
-export declare function switchboardValue(feed: SwitchboardFeed<"mainnet" | "devnet">, expectedFeed: Pubkey, maxStaleSlots: u64, decimals: u8): i64;
+export declare function switchboardValue(
+  feed: SwitchboardFeed<"mainnet" | "devnet">,
+  expectedFeed: Pubkey,
+  maxStaleSlots: u64,
+  decimals: u8,
+  /** The fewest oracle samples the result may rest on (default 1). */
+  minSamples?: u8,
+): i64;
 
 /** The Associated Token Account program (ATokenGP…). Its address is checked. */
 export interface AssociatedTokenProgram extends AccountMeta {
@@ -570,13 +584,18 @@ export type InitIfNeeded<T> = T extends TokenAccount
  */
 export type HasOne<A, Field extends string> = A & { readonly __hasOne?: Field };
 /**
- * Anchor's `token::mint = mintParam, token::authority = authorityParam` on an existing token account, naming the
- * parameters (2014 / 2015); `never` leaves one out.
+ * Anchor's `token::mint = mintParam, token::authority = authorityParam, token::token_program = tokenProgramParam` on an
+ * existing token account, naming the parameters (2014 / 2015 / 2021: owned by that token program); `never` leaves one out.
  */
-export type TokenOf<A, MintParam extends string, AuthorityParam extends string = never> = A & { readonly __tokenOf?: [MintParam, AuthorityParam] };
-/** Anchor's `mint::authority = a, mint::freeze_authority = f` on an existing mint, naming the parameters (2016 / 2017). */
-export type MintOf<A, AuthorityParam extends string, FreezeAuthorityParam extends string = never> = A & {
-  readonly __mintOf?: [AuthorityParam, FreezeAuthorityParam];
+export type TokenOf<A, MintParam extends string, AuthorityParam extends string = never, TokenProgramParam extends string = never> = A & {
+  readonly __tokenOf?: [MintParam, AuthorityParam, TokenProgramParam];
+};
+/**
+ * Anchor's `mint::authority = a, mint::freeze_authority = f, mint::token_program = tp` on an existing mint, naming the
+ * parameters (2016 / 2017 / 2022: owned by that token program); `never` leaves one out.
+ */
+export type MintOf<A, AuthorityParam extends string, FreezeAuthorityParam extends string = never, TokenProgramParam extends string = never> = A & {
+  readonly __mintOf?: [AuthorityParam, FreezeAuthorityParam, TokenProgramParam];
 };
 export type Seeds<A, Names extends readonly string[], Bump extends string = never, ProgramId extends string = never> = A & {
   readonly __seeds?: [Names, Bump, ProgramId];
@@ -1642,7 +1661,10 @@ export declare function emit<T>(event: T): void;
  */
 export declare function returnData<T extends bigint | boolean | Pubkey | Hash>(program: AccountMeta): T;
 
-/** Verify `account.key` is the PDA for `seeds` + `bump` under this program. */
+/**
+ * Verify `account.key` is the PDA for `seeds` + `bump` under this program. Any bump that gives a PDA passes (Anchor's
+ * `bump = expr`): use a stored bump, not one from the arguments, or the caller picks among up to 256 addresses.
+ */
 export declare function requirePda(account: AccountMeta, seeds: Seed[], bump: u8): void;
 
 /** Close a program-owned account: move all lamports to `destination` and wipe it. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@typesol/cli",
-  "version": "0.24.0",
+  "version": "0.25.0",
   "description": "Compile a TypeScript-syntax language directly to Solana SBF programs.",
   "type": "module",
   "license": "MIT",