@typesol/cli 0.24.1 → 0.26.0

package/docs/cli.md

@@ -6,12 +6,13 @@ error. Exit codes: **0** success, **1** failure (compile errors, failed deploy,
 
 | Command | What it does |
 | --- | --- |
-| `typesol init [<dir>] [--name <program>] [--template counter\|vault\|escrow]` | Create a project: `typesol.json`, `programs/<name>.ts`, `tests/<name>.test.ts` (LiteSVM), `package.json`, `tsconfig.json`, `programs/tsconfig.json` (with the editor plugin) and `.gitignore`. `<name>` must be snake_case; by default it is derived from `<dir>` (`my-app` → `my_app`). The template picks the program and its test: `counter` (default, a PDA counter per user), `vault` (SOL at a PDA: deposit, withdraw above rent, close) or `escrow` (SPL tokens: make, take, refund, the offer PDA signing for its vault). Refuses to overwrite files. |
+| `typesol init [<dir>] [--name <program>] [--template counter\|vault\|escrow]` | Create a project: `typesol.json`, `programs/<name>.ts`, `tests/<name>.test.ts` (LiteSVM), `package.json`, `tsconfig.json`, `programs/tsconfig.json` (with the editor plugin) and `.gitignore`. `<name>` must be snake_case; by default it is derived from `<dir>` (`my-app` → `my_app`). The template picks the program and its test: `counter` (default, a PDA counter per user), `vault` (SOL at a PDA: deposit, withdraw above rent, close) or `escrow` (SPL tokens: make, take, refund, the offer PDA signing for its vault). Refuses to overwrite files. It warns, with the install commands, when the platform-tools that building needs are missing. |
+| `typesol doctor [--url <rpc>] [--config <cli config>]` | Check what building, testing and deploying need: Node.js, the platform-tools, the Solana CLI, its keypair, the RPC (`--url`, a cluster moniker, or the CLI config) and the keypair's balance there, and the project. Each problem is printed with the command that fixes it. Exit code 1 when building is impossible (Node.js or the platform-tools missing); deploy pieces are warnings. |
 | `typesol build [<program>…] [--sbpf v0\|v1\|v2] [--profile] [--quiet]` | In a project: build every program (or those named) into `<out>/<name>/`: `<name>.so`, `<name>.json` (Anchor IDL), `<name>.client.ts` (TypeScript client, see [client.md](client.md)), `<name>.c`, `<name>.build.json`. The first build creates `<out>/deploy/<name>-keypair.json` and records the address in `typesol.json`; later builds refuse a missing or different keypair. |
 | `typesol build <file.ts> [--out <dir>] [--program-id <keypair.json>] [--sbpf …] [--profile]` | Outside a project (or a file that is not one of its programs): build that file. A project program's `.ts` builds as that program. |
 | `typesol check <file.ts> [--json] [--stdin]` | Type-check and validate without building. `--json` prints `{ ok, diagnostics: [{ file, line, column, message }] }`; `--stdin` checks the text given on stdin as that file (its imports come from disk). |
 | `typesol emit-c <file.ts> [--out <file.c>] [--profile]` | Print or write the generated C. |
-| `typesol deploy [<program>…] [--url <rpc>] [--keypair <payer.json>] [--config <cli config>] [--dry-run] [--sbpf …]` | Build, then `solana program deploy --use-rpc` at the program keypair's address. Deploying again upgrades (the payer must be the upgrade authority). `--dry-run` builds and prints the commands. Needs `solana` on PATH. |
+| `typesol deploy [<program>…] [--url <rpc>] [--keypair <payer.json>] [--config <cli config>] [--dry-run] [--sbpf …]` | Build, then `solana program deploy --use-rpc` at the program keypair's address. Deploying again upgrades (the payer must be the upgrade authority). `--dry-run` builds and prints the commands. Before sending anything it checks that the RPC answers and that the payer holds enough for the rent (about twice the binary's on a first deploy, while the buffer exists), and says what to do if not (start `solana-test-validator`, `solana airdrop` on devnet or a local validator). Needs `solana` on PATH. |
 | `typesol idl publish [<program>…] [--url <rpc>] [--keypair <authority.json>] [--config <cli config>] [--non-canonical]` | Compile (the binary is not rebuilt), then write each IDL to the Program Metadata program (seed `idl`). Canonical IDLs must be signed by the upgrade authority. Defaults come from the Solana CLI config (`~/.config/solana/cli/config.yml`). |
 | `typesol cpi <idl.json> [--out <file.ts>] [--prefix <name>] [--address <base58>]` | Generate TypeSOL helpers that call another program from its IDL. Unsupported instructions are listed on stderr. |
 | `typesol port <idl.json> [--out <file.ts>]` | A TypeSOL program skeleton from an Anchor IDL (0.30+/1.x), to port an Anchor program: account structs, enums, errors, events and one function per instruction with its accounts and arguments, each body `require(false, …NotPorted)` until written. Instruction discriminators (an explicit `@discriminator` when the name derives another), account names and error codes are kept, so existing clients keep working where the layouts match; notes on stderr list where they do not (Borsh `String`/`Option` in account data, a `Vec` that is not the last field, custom discriminators or error codes). |

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

@@ -56,4 +56,4 @@ In file order:
 - 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).
+  error list (`TYPESOL_ERRORS` in `src/tools/clientgen.ts`), so clients name it (a test checks every code has a name).

package/docs/security-model.md

@@ -0,0 +1,97 @@
+# Security model
+
+What a program compiled by TypeSOL can rely on, who is trusted, and what is left to the program's author. This is the
+specification the tests check and an audit measures the compiler against; [audit.md](audit.md) is the package for
+auditors, [SECURITY.md](../SECURITY.md) how to report a problem.
+
+## Trust
+
+| Party | Trusted for |
+| --- | --- |
+| The program's author | the program's logic: what it allows, to whom, for how much |
+| TypeSOL (this repository) | that the binary does what the source and these guarantees say, and nothing an attacker can steer beyond it |
+| The toolchain | the TypeScript compiler API (parsing, types), Agave platform-tools (clang, lld), Node.js |
+| The Solana runtime | account ownership and signer flags as passed, the loader's account serialization, CPI privilege rules, sysvars |
+
+Everything a transaction carries is attacker-controlled: the instruction data, which accounts are passed in which
+slots (any account, repeated or not), the flags the runtime then enforces, the data of accounts the program does not
+own, remaining accounts, and what another program returns or writes.
+
+## Guarantees
+
+Each holds for every instruction of every program the compiler accepts. A break of any of them is a security bug
+(SECURITY.md).
+
+### Before the body runs
+
+1. **Account count.** Fewer accounts than parameters fail (3005); more than 32 in total fail before parsing (5113).
+2. **Account types.** Each parameter is checked for what its type says: `Signer` signed (3010); `Mut<…>` writable
+   (2000); a program account (`Account<T>`, `Mut<T>`) owned by this program (3007), initialized (3012), with `T`'s
+   discriminator (3002) and at least its size (3003); `TokenAccount` / `Mint` owned by SPL Token or Token-2022 and an
+   initialized account of that kind (3007 / 3003); program parameters at their fixed address and executable
+   (3008 / 3009); `SystemAccount` owned by the System Program (3011); `Zeroed<T>` owned, all-zero discriminator and
+   rent-exempt.
+3. **No aliasing.** Two writable parameters are never the same account (2040), whatever slots the transaction uses.
+4. **Arguments.** Every argument is length-checked before it is read; strings are valid UTF-8; booleans, enums and
+   options have valid tags (102).
+5. **Constraints.** `Seeds` (2006, with the stored or the canonical bump), `Ata` (2015 / 2009 / 2014), `HasOne`
+   (2001), `Owner` (2004), `Executable` (2007), `Address` (2012), `TokenOf` / `MintOf` (2014–2017, 2021, 2022) hold
+   before the body, per account in Anchor's order ([errors.md](errors.md#which-error-a-transaction-gets)). A
+   constraint naming an optional account is refused at compile time, so leaving the account out cannot skip it.
+
+### While it runs
+
+6. **Arithmetic.** Every `+ - * / % **`, compound assignment, `++` / `--`, unary minus, shift and cast is checked:
+   overflow and lost bits fail (5100), division by zero fails (5101), a cast out of range fails (4102). There is no
+   unchecked integer operation in the language.
+7. **Bounds.** Every index into an array, Vec, FixedVec or remaining-account list is checked (5104); a
+   growable Vec's stored length is checked against the account's size before it is used (3003).
+8. **Account creation.** `create` / `createIfNeeded` is a top-level statement, and the account cannot be read or
+   written before it (compile error). Creation refuses an account that already exists (3000), and an address someone
+   pre-funded still gets created. `createIfNeeded` on an existing account re-derives the canonical PDA and checks
+   owner, discriminator and size (token accounts: mint and owner; mints: decimals, authorities and the extensions it
+   names).
+9. **Writes through references.** A place is never written after the code that computes its value may have moved it:
+   replacing or resizing what a live reference points into is a compile error, as is writing a Vec element with a
+   right side that may resize the Vec.
+10. **Remaining accounts.** Writing one (`.lamports`, `loadAccountMut`) checks it is writable (3006) and not another
+    account of the instruction (2040); `loadAccountMut` loads a given account once per instruction (2040);
+    `loadAccount<T>` checks owner, discriminator and size, and validates the data as instruction arguments are.
+11. **Growth.** An account grows by at most 10 KiB per instruction (3016), the payer is a `Mut<Signer>`, new bytes are
+    zero and the new rent is paid; shrinking keeps the lamports in the account.
+12. **CPIs.** A program signs only for its own PDAs (the runtime enforces it; the seeds are those written in the
+    source). `invoke` marks an account writable or signer only when the parameter is `Mut` / `Signer` or the program
+    signs for it; remaining accounts keep the flags they were passed with, or are checked for the role requested.
+    Return data is read only from the program named, at the expected size (5106).
+13. **Events.** `emitCpi` is accepted only from this program's event-authority PDA, signed (2002).
+
+### When it ends
+
+14. **Closing.** A `CloseTo<…>` or `close(…)` account has its lamports moved to the destination, its data zeroed and
+    its owner reset to the System Program on every successful return, so it cannot be revived as the same account.
+15. **No silent success.** Every failed check returns its error code and the transaction fails: no code path continues
+    or returns success after a failed check or CPI.
+
+## Left to the author
+
+- **Logic.** Who may call what, limits, prices, fees. TypeSOL checks what the types and constraints say, nothing more.
+- **`AccountInfo` / `UncheckedProgram`.** Unchecked by design, as in Anchor: check what you rely on.
+- **`requirePda(account, seeds, bump)`.** Any valid bump passes (Anchor's `bump = expr`). Use a stored bump, never one
+  from the arguments.
+- **Oracles.** `pythPrice` checks verification, feed and age (pass the exponent you scale by); the raw `update.*`
+  fields are unchecked. `switchboardValue` needs the expected feed; set `minSamples`.
+- **`merkleVerify`.** Leaves and inner nodes hash alike: build leaves as `keccak256(keccak256(data))` in the program.
+- **Existing accounts in `createIfNeeded`.** An existing token account's delegate and close authority, and a mint's
+  extensions the call does not name, are not checked (as in Anchor).
+- **Seeds of variable length.** Two adjacent string seeds can collide (`"ab" + "c"` and `"a" + "bc"`), as in Anchor.
+
+## Where TypeSOL is stricter than Anchor
+
+- Any two writable parameters naming one account are refused (Anchor compares only program and token accounts).
+- Arithmetic overflow returns an error code (5100) in every build; Anchor aborts the program, and only when
+  overflow checks are enabled.
+
+## Status
+
+The compiler and runtime have had internal security reviews; the findings of the latest are fixed in 0.25.0
+(CHANGELOG). There has been no external audit yet: see [audit.md](audit.md).

package/docs/testing.md

@@ -5,10 +5,11 @@ run prints its seed; reproduce with `FUZZ_SEED=<n>`, widen with `FUZZ_RUNS` / `F
 
 | Check | Oracle | What must hold |
 | --- | --- | --- |
-| `test/fuzz-arith.test.ts` | BigInt | `+ - * / % **`, `& \| ^ << >> ~`, unary minus, comparisons and casts at every width u8…u128 / i8…i128, plus `mulDiv`, `mulDivCeil`, `isqrt`, `min`, `max`, return the same value or abort with the same code (5100/5101/4102), for edge and random inputs |
-| `test/fuzz-state.test.ts` | TypeScript state model | random honest + hostile actions on vault and escrow: every outcome as predicted, balances equal the model, SOL conserved up to fees, token supply exactly conserved; random filings/decisions/resets on ledgerbook: Vec contents, account size and rent exemption equal the model |
-| `test/differential.test.ts` | Anchor twins in `bench/anchor` | identical transactions to TypeSOL and Anchor programs: same outcomes, same account contents, same wallet and token balances after every step |
-| `test/ports-*.test.ts` | the Anchor programs of solana-developers/program-examples and their tests | TypeSOL rewrites under `test/ports/` run the originals' flows and failure paths with the same outcomes, error codes and balances ([test/ports/README.md](../test/ports/README.md)) |
+| `test/verification/fuzz-arith.test.ts` | BigInt | `+ - * / % **`, `& \| ^ << >> ~`, unary minus, comparisons and casts at every width u8…u128 / i8…i128, plus `mulDiv`, `mulDivCeil`, `isqrt`, `min`, `max`, return the same value or abort with the same code (5100/5101/4102), for edge and random inputs |
+| `test/verification/fuzz-state.test.ts` | TypeScript state model | random honest + hostile actions on vault and escrow: every outcome as predicted, balances equal the model, SOL conserved up to fees, token supply exactly conserved; random filings/decisions/resets on ledgerbook: Vec contents, account size and rent exemption equal the model |
+| `test/verification/fuzz-layout.test.ts` | TypeScript model | random pushes, pops, sets, in-place additions, moves and clears on an account with two growable Vecs (honest, out of range and by a stranger): the decoded account equals the model after every step; random `loadAccountMut` index pairs over remaining-account lists that repeat accounts: every alias refused (2040), balances conserved |
+| `test/verification/differential.test.ts` | Anchor twins in `test/anchor-twins` | identical transactions to TypeSOL and Anchor programs: same outcomes, same account contents, same wallet and token balances after every step |
+| `test/porting/ports-*.test.ts` | the Anchor programs of solana-developers/program-examples and their tests | TypeSOL rewrites under `test/ports/` run the originals' flows and failure paths with the same outcomes, error codes and balances ([test/ports/README.md](../test/ports/README.md)) |
 
 Compute-unit and binary-size comparisons with Anchor, native Rust and Pinocchio are in the README
 ([Numbers](../README.md#numbers)).

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.1",
+  "version": "0.26.0",
   "description": "Compile a TypeScript-syntax language directly to Solana SBF programs.",
   "type": "module",
   "license": "MIT",
@@ -22,16 +22,16 @@
       "default": "./dist/workspace.js"
     },
     "./cpi": {
-      "types": "./dist/cpigen.d.ts",
-      "default": "./dist/cpigen.js"
+      "types": "./dist/tools/cpigen.d.ts",
+      "default": "./dist/tools/cpigen.js"
     },
     "./client": {
-      "types": "./dist/clientgen.d.ts",
-      "default": "./dist/clientgen.js"
+      "types": "./dist/tools/clientgen.d.ts",
+      "default": "./dist/tools/clientgen.js"
     },
     "./profile": {
-      "types": "./dist/profile.d.ts",
-      "default": "./dist/profile.js"
+      "types": "./dist/tools/profile.d.ts",
+      "default": "./dist/tools/profile.js"
     },
     "./testing": {
       "types": "./dist/testing.d.ts",
@@ -39,8 +39,8 @@
     },
     "./ts-plugin": "./ts-plugin/index.js",
     "./idl": {
-      "types": "./dist/idlpublish.d.ts",
-      "default": "./dist/idlpublish.js"
+      "types": "./dist/tools/idlpublish.d.ts",
+      "default": "./dist/tools/idlpublish.js"
     },
     "./package.json": "./package.json"
   },
@@ -63,12 +63,12 @@
     "test": "vitest run",
     "typesol": "node dist/cli.js",
     "smoke": "node scripts/smoke.ts",
-    "fuzz": "FUZZ_RUNS=2000 FUZZ_STEPS=600 FUZZ_VERBOSE=1 vitest run test/fuzz-arith.test.ts test/fuzz-state.test.ts test/differential.test.ts --silent=false",
-    "bench:anchor": "cd bench/anchor && cargo-build-sbf",
+    "fuzz": "FUZZ_RUNS=2000 FUZZ_STEPS=600 FUZZ_VERBOSE=1 vitest run test/verification/fuzz-arith.test.ts test/verification/fuzz-state.test.ts test/verification/fuzz-layout.test.ts test/verification/differential.test.ts --silent=false",
+    "build:twins": "cd test/anchor-twins && cargo-build-sbf",
     "prepack": "npm run build",
     "fetch:programs": "bash scripts/fetch-programs.sh",
-    "format": "prettier --write \"src/**/*.ts\" \"test/*.ts\" \"scripts/**/*.ts\" \"lib/**/*.ts\"",
-    "lint": "prettier --check \"src/**/*.ts\" \"test/*.ts\" \"scripts/**/*.ts\" \"lib/**/*.ts\" && pnpm typecheck",
+    "format": "prettier --write \"src/**/*.ts\" \"test/*.ts\" \"test/*/*.test.ts\" \"scripts/**/*.ts\" \"lib/**/*.ts\"",
+    "lint": "prettier --check \"src/**/*.ts\" \"test/*.ts\" \"test/*/*.test.ts\" \"scripts/**/*.ts\" \"lib/**/*.ts\" && pnpm typecheck",
     "prepublishOnly": "pnpm lint && pnpm test"
   },
   "engines": {

package/runtime/typesol_rt.h

@@ -18,6 +18,7 @@
 #define TS_ERR_INSTRUCTION_NOT_FOUND 101   /* InstructionFallbackNotFound */
 #define TS_ERR_INSTRUCTION_DATA 102        /* InstructionDidNotDeserialize */
 #define TS_ERR_NOT_WRITABLE 3006           /* AccountNotMutable */
+#define TS_ERR_CONSTRAINT_MUT 2000         /* ConstraintMut */
 #define TS_ERR_CONSTRAINT 2001             /* ConstraintHasOne */
 #define TS_ERR_NOT_RENT_EXEMPT 2005        /* ConstraintRentExempt */
 #define TS_ERR_CONSTRAINT_SIGNER 2002      /* ConstraintSigner */
@@ -31,6 +32,8 @@
 #define TS_ERR_MINT_AUTHORITY 2016         /* ConstraintMintMintAuthority */
 #define TS_ERR_FREEZE_AUTHORITY 2017       /* ConstraintMintFreezeAuthority */
 #define TS_ERR_MINT_DECIMALS 2018          /* ConstraintMintDecimals */
+#define TS_ERR_TOKEN_TOKEN_PROGRAM 2021    /* ConstraintTokenTokenProgram */
+#define TS_ERR_MINT_TOKEN_PROGRAM 2022     /* ConstraintMintTokenProgram */
 #define TS_ERR_DUPLICATE_MUT 2040          /* ConstraintDuplicateMutableAccount */
 #define TS_ERR_ALREADY_INITIALIZED 3000    /* AccountDiscriminatorAlreadySet */
 #define TS_ERR_DISCRIMINATOR 3002          /* AccountDiscriminatorMismatch */
@@ -275,6 +278,7 @@ typedef struct {
   const SolPubkey *program_id;
   TsAccount *ka[TS_MAX_ACCOUNTS];             /* ka_num entries */
   SolAccountInfo infos[TS_MAX_ACCOUNTS];      /* scratch for CPI account lists (ts_invoke) */
+  uint64_t loaded_mut;                        /* bit i: ka[i] loaded with loadAccountMut (zeroed by the entrypoint of a program that uses it) */
 } TsParams;
 
 /*
@@ -410,6 +414,12 @@ static inline uint64_t ts_check_writable(const TsAccount *a) {
   if (!a->is_writable) TS_FAIL(TS_ERR_NOT_WRITABLE, "TypeSOL: account must be writable");
   return SUCCESS;
 }
+/* A Mut<…> parameter passed read-only: Anchor's `#[account(mut)]` (ConstraintMut). ts_check_writable is for accounts
+   the program makes writable at runtime (remaining accounts, CPI metas). */
+static inline uint64_t ts_check_mut(const TsAccount *a) {
+  if (!a->is_writable) TS_FAIL(TS_ERR_CONSTRAINT_MUT, "TypeSOL: account must be writable (mut)");
+  return SUCCESS;
+}
 
 static inline uint64_t ts_check_program_account(const TsAccount *a, const SolPubkey *program_id,
                                                 const uint8_t disc[8], uint64_t size) {
@@ -428,7 +438,7 @@ static inline uint64_t ts_check_vec_len(const TsAccount *a, uint64_t fixed, uint
   return SUCCESS;
 }
 
-/* No other account in the instruction may be the same account (for loadAccountMut). */
+/* No other account in the instruction may be the same account (remaining accounts written in place). */
 static inline uint64_t ts_check_unaliased(const TsParams *params, const TsAccount *a) {
   /* The loader passes each account once and marks repeats as duplicates, which share its record. */
   uint64_t seen = 0;
@@ -437,6 +447,18 @@ static inline uint64_t ts_check_unaliased(const TsParams *params, const TsAccoun
   return SUCCESS;
 }
 
+/* loadAccountMut: unaliased, and not already loaded mutably in this instruction. Two loads of the same slot would be
+   two writable views of one account, as two slots naming it would (read both, write both: the classic drain). */
+static inline uint64_t ts_claim_mut(TsParams *params, const TsAccount *a) {
+  uint64_t seen = 0, at = 0;
+  for (uint64_t i = 0; i < params->ka_num; i++)
+    if (params->ka[i] == a) seen++, at = i;
+  if (seen > 1) TS_FAIL(TS_ERR_DUPLICATE_MUT, "TypeSOL: account passed more than once");
+  if (params->loaded_mut >> at & 1) TS_FAIL(TS_ERR_DUPLICATE_MUT, "TypeSOL: account already loaded with loadAccountMut");
+  params->loaded_mut |= (uint64_t)1 << at;
+  return SUCCESS;
+}
+
 static inline uint64_t ts_check_address(const TsAccount *a, const SolPubkey *expected) {
   if (!ts_key_eq(&a->key, expected)) TS_FAIL(TS_ERR_WRONG_PROGRAM, "TypeSOL: unexpected program address");
   return SUCCESS;
@@ -1466,7 +1488,8 @@ static inline int64_t ts_le_i64(const uint8_t *p) {
 }
 
 /* Like get_price_no_older_than: fully verified, matching feed id, publish_time + max_age >= now. */
-static inline uint64_t ts_pyth_price(const TsAccount *a, const SolPubkey *feed, uint64_t max_age, int64_t *out) {
+/* expo: the exponent the caller scales by; checked when check_expo (a feed's exponent can change). */
+static inline uint64_t ts_pyth_price(const TsAccount *a, const SolPubkey *feed, uint64_t max_age, bool check_expo, int32_t expo, int64_t *out) {
   uint64_t m;
   bool full;
   TS_TRY(ts_pyth_message(a, &m, &full));
@@ -1478,6 +1501,11 @@ static inline uint64_t ts_pyth_price(const TsAccount *a, const SolPubkey *feed,
   int64_t deadline;
   if (__builtin_add_overflow(published, (int64_t)(max_age > INT64_MAX ? INT64_MAX : max_age), &deadline)) deadline = INT64_MAX;
   if (deadline < now) TS_FAIL(TS_ERR_ORACLE, "TypeSOL: Pyth price is too old");
+  if (check_expo) {
+    int32_t e;
+    ts_memcpy(&e, a->data + m + 48, 4);
+    if (e != expo) TS_FAIL(TS_ERR_ORACLE, "TypeSOL: Pyth exponent is not the expected one");
+  }
   *out = ts_le_i64(a->data + m + 32);
   return SUCCESS;
 }
@@ -1503,9 +1531,10 @@ static inline uint64_t ts_check_switchboard(const TsAccount *a, bool devnet) {
  * The feed's current result (an 18-decimal fixed-point i128) scaled to `decimals`, if it has samples
  * and was produced within `max_stale_slots` slots of now.
  */
-static inline uint64_t ts_switchboard_value(const TsAccount *a, uint64_t max_stale_slots, uint8_t decimals, int64_t *out) {
+static inline uint64_t ts_switchboard_value(const TsAccount *a, uint64_t max_stale_slots, uint8_t decimals, uint8_t min_samples, int64_t *out) {
   if (decimals > 18) TS_FAIL(TS_ERR_ORACLE, "TypeSOL: at most 18 decimals");
-  if (a->data[TS_SB_RESULT_SAMPLES] == 0) TS_FAIL(TS_ERR_ORACLE, "TypeSOL: Switchboard feed has no samples");
+  if (a->data[TS_SB_RESULT_SAMPLES] == 0 || a->data[TS_SB_RESULT_SAMPLES] < min_samples)
+    TS_FAIL(TS_ERR_ORACLE, "TypeSOL: Switchboard feed has too few samples");
   uint64_t clock[5] = {0};
   if (sol_get_clock_sysvar(clock) != SUCCESS) TS_FAIL(TS_ERR_SYSVAR, "TypeSOL: clock sysvar unavailable");
   uint64_t slot = (uint64_t)ts_le_i64(a->data + TS_SB_RESULT_SLOT);