@typesol/cli 0.25.0 → 0.27.0

package/dist/{portgen.js → tools/portgen.js}

@@ -9,7 +9,7 @@
  * data enum, a COption) it says so in a note and a comment.
  */
 import { createHash } from "node:crypto";
-import { cNameProblem } from "./compiler/analyze.js";
+import { cNameProblem } from "../compiler/analyze.js";
 const RESERVED = new Set("break case catch class const continue debugger default delete do else enum export extends false finally for function if import in instanceof new null return super switch this throw true try typeof var void while with yield let static implements interface package private protected public await".split(" "));
 const camel = (s) => s.replace(/[_-]+([a-zA-Z0-9])/g, (_, c) => c.toUpperCase()).replace(/^[A-Z]/, (c) => c.toLowerCase());
 const pascal = (s) => camel(s).replace(/^[a-z]/, (c) => c.toUpperCase());

package/dist/workspace.js

@@ -13,7 +13,7 @@
  */
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import path from "node:path";
-import { writeClient } from "./clientgen.js";
+import { writeClient } from "./tools/clientgen.js";
 import { build, COMPILER_VERSION, SBPF_VERSIONS } from "./compiler/index.js";
 import { loadOrCreateKeypair } from "./keys.js";
 import { TEMPLATES } from "./templates.js";

package/docs/architecture.md

@@ -26,13 +26,13 @@ program.so + program.build.json (manifest: versions, sha256 of sources and binar
 
 | Path | Contents |
 | --- | --- |
-| `src/` | The compiler (`src/compiler/`) and the tools around it: CLI, workspace, client, CPI and port generators, testing, IDL publishing (source map below) |
+| `src/` | The compiler (`src/compiler/`); the CLI, projects, init templates and `typesol/testing` at the top; generators and chain tooling in `src/tools/` (client, CPI and port generators, IDL publishing, on-chain reads, profiling, the LiteSVM RPC). Source map below |
 | `runtime/` | `typesol_rt.h`, the C runtime every program includes ([runtime.md](runtime.md)) |
 | `lib/` | `typesol.d.ts`, the language surface programs typecheck against |
 | `ts-plugin/` | The editor plugin (`typesol/ts-plugin`) |
 | `examples/` | Example programs; the `typesol init` templates are copies of three of them |
-| `test/` | The test suite: `fixtures/` (programs the tests compile), `ports/` (TypeSOL rewrites of solana-developers/program-examples), `golden/` (pinned generated clients), `programs/` (third-party program binaries, see its SOURCES.md) |
-| `bench/anchor/` | Anchor twins of the counter, vault and escrow examples, for the differential tests (`pnpm bench:anchor`) and the zero-copy client test; the benchmarks themselves are in [typesol/benchmarks](https://github.com/typesol/benchmarks) |
+| `test/` | The test suite, by subject: `language/`, `security/`, `examples/`, `integrations/` (token, Metaplex, oracle and other CPIs), `client/`, `cli/`, `porting/`, `verification/` (differential and fuzz tests). Shared: `harness.ts` and the `*-helpers.ts`, `fixtures/` (programs the tests compile), `ports/` (TypeSOL rewrites of solana-developers/program-examples), `golden/` (pinned generated C and clients), `programs/` (third-party program binaries, see its SOURCES.md), `anchor-twins/` (below) |
+| `test/anchor-twins/` | Anchor twins of the counter, vault and escrow examples, for the differential tests (`pnpm build:twins`) and the zero-copy client test; the benchmarks themselves are in [typesol/benchmarks](https://github.com/typesol/benchmarks) |
 | `scripts/` | `smoke.ts` and `localnet.sh` (a local validator run), `fetch-programs.sh` (third-party binaries), `readme-bench.ts` (the README numbers) |
 | `docs/` | User and contributor documentation (also published on typesol.com) |
 | `assets/` | The CLI's logo and the README images (`readme/`, generated) |
@@ -53,17 +53,17 @@ program.so + program.build.json (manifest: versions, sha256 of sources and binar
 | `src/compiler/index.ts` | The compiler's API (`generate`, `build`, `verifyBinary`, the build manifest). |
 | `runtime/typesol_rt.h` | The C runtime: error codes, word-wise memory helpers, the entry point's input parser (`ts_deserialize`), account checks, checked math, Borsh helpers, CPIs (System, Token, Token-2022, ATA, Metaplex), oracles and the heap allocator. Header-only and `static inline`, so unused code is dropped. |
 | `src/workspace.ts` | `typesol.json` projects, program keypairs, `typesol init` templates and deploy arguments. |
-| `src/cpigen.ts` | `typesol cpi`: reads an Anchor IDL and writes typed TypeSOL CPI helpers. |
-| `src/clientgen.ts` | The TypeScript client (`<name>.client.ts`, [client.md](client.md)): reads an IDL, validates it (it may come from anywhere), and writes one `@solana/kit` file. Not part of the compiler core: `workspace.ts` and the CLI write it after `build()`, and `typesol client` writes it for any IDL. |
-| `src/idlpublish.ts` | `typesol idl publish` through the Program Metadata program, and reading a program's IDL back from the chain (Program Metadata or Anchor's IDL account) for `typesol client --address`. |
-| `src/portgen.ts` | `typesol port`: a TypeSOL program skeleton from an Anchor IDL (structs, enums, errors, events, one function per instruction). |
+| `src/tools/cpigen.ts` | `typesol cpi`: reads an Anchor IDL and writes typed TypeSOL CPI helpers. |
+| `src/tools/clientgen.ts` | The TypeScript client (`<name>.client.ts`, [client.md](client.md)): reads an IDL, validates it (it may come from anywhere), and writes one `@solana/kit` file. Not part of the compiler core: `workspace.ts` and the CLI write it after `build()`, and `typesol client` writes it for any IDL. |
+| `src/tools/idlpublish.ts` | `typesol idl publish` through the Program Metadata program, and reading a program's IDL back from the chain (Program Metadata or Anchor's IDL account) for `typesol client --address`. |
+| `src/tools/portgen.ts` | `typesol port`: a TypeSOL program skeleton from an Anchor IDL (structs, enums, errors, events, one function per instruction). |
 | `src/templates.ts` | The programs and tests `typesol init --template` writes (copies of `examples/`; a test checks they match). |
-| `src/svmrpc.ts` | `svmConnection`: a kit RPC and subscriptions pair answered by LiteSVM, so generated clients run in tests (exported by `typesol/testing`). |
+| `src/tools/svmrpc.ts` | `svmConnection`: a kit RPC and subscriptions pair answered by LiteSVM, so generated clients run in tests (exported by `typesol/testing`). |
 | `src/keys.ts` | Base58 and program keypair helpers. |
 | `ts-plugin/index.js` | `typesol/ts-plugin` (CommonJS, loaded by tsserver): runs `typesol check --json --stdin` on program entries and adds the diagnostics. |
 | `src/testing.ts` | `typesol/testing`: LiteSVM test helpers for projects (accounts by name from the IDL, plain values). |
-| `src/onchain.ts` | `typesol verify --address`: a deployed program's ELF, authority and deploy slot under loader v2, v3 or v4. |
-| `src/profile.ts` | Turns `--profile` logs into compute units per source line. |
+| `src/tools/onchain.ts` | `typesol verify --address`: a deployed program's ELF, authority and deploy slot under loader v2, v3 or v4. |
+| `src/tools/profile.ts` | Turns `--profile` logs into compute units per source line. |
 | `src/cli.ts` | Command parsing. Every command has strict options, `--help`, and exit codes 0 (success), 1 (failure), 2 (usage error) and 3 (verify mismatch). |
 
 ## The emitter
@@ -123,7 +123,7 @@ These invariants are easy to break. Each one has tests.
 3. Put any C helper in `runtime/typesol_rt.h` as `static inline`, returning `uint64_t` (`SUCCESS` or an error code)
    so that callers can wrap it in `TS_TRY`.
 4. Add an execution test that compiles a fixture under `test/fixtures/` and runs it in LiteSVM. Add a diagnostics
-   case in `test/diagnostics.test.ts` for each misuse you reject.
+   case in `test/language/diagnostics.test.ts` for each misuse you reject.
 5. Document it in `docs/language.md` and add a line to `CHANGELOG.md`.
 
 ### Add an account constraint
@@ -145,7 +145,7 @@ These invariants are easy to break. Each one has tests.
 ### Change generated C
 
 `test/golden/counter.c` pins the output for the counter example. Run
-`UPDATE_GOLDEN=1 pnpm test test/diagnostics.test.ts`, review the diff, and commit it with the change.
+`UPDATE_GOLDEN=1 pnpm test test/language/diagnostics.test.ts`, review the diff, and commit it with the change.
 
 For refactors that should not change behaviour, compare binaries: build every example and fixture before and after
 the change. The sha256 values in the `*.build.json` manifests must not change.
@@ -154,12 +154,12 @@ the change. The sha256 values in the `*.build.json` manifests must not change.
 
 | Files | What they cover |
 | --- | --- |
-| `test/<feature>.test.ts` | Execution tests. Each compiles fixtures and runs them in LiteSVM through `test/harness.ts`. |
-| `test/diagnostics.test.ts` | Every rejected construct, plus the golden C. |
-| `test/hardening.test.ts`, `test/regressions.test.ts` | Attacks and edge cases that once failed. Keep each as a negative test. |
-| `test/fuzz-*.test.ts`, `test/differential.test.ts` | Randomized checks against BigInt, a TypeScript state model, and the Anchor twins in `bench/anchor`. See [testing.md](testing.md). |
+| `test/<subject>/<feature>.test.ts` | Execution tests. Each compiles fixtures and runs them in LiteSVM through `test/harness.ts`. |
+| `test/language/diagnostics.test.ts` | Every rejected construct, plus the golden C. |
+| `test/security/hardening.test.ts`, `test/security/regressions.test.ts` | Attacks and edge cases that once failed. Keep each as a negative test. |
+| `test/verification/fuzz-*.test.ts`, `test/verification/differential.test.ts` | Randomized checks against BigInt, a TypeScript state model, and the Anchor twins in `test/anchor-twins`. See [testing.md](testing.md). |
 | `scripts/smoke.ts` | End to end against a real `solana-test-validator` (`scripts/localnet.sh`). |
 
 Some tests need optional inputs and are skipped without them:
 - `pnpm fetch:programs` downloads the Metaplex programs, which cannot be redistributed.
-- `pnpm bench:anchor` builds the Anchor twins and needs Rust and Anchor.
+- `pnpm build:twins` builds the Anchor twins and needs Rust and Anchor.

package/docs/audit.md

@@ -0,0 +1,90 @@
+# Audit package
+
+For a security firm reviewing TypeSOL. TypeSOL compiles a subset of TypeScript to C and then to Solana SBF; every
+program it builds includes one C runtime header. The question for an audit is whether a program compiled by TypeSOL
+can be made to do something its source and [the security model](security-model.md) say it cannot. Programs written
+with TypeSOL are out of scope; their authors audit them.
+
+## Scope
+
+In order of priority. Line counts at 0.25.0.
+
+| Priority | Component | Files | Lines | Why |
+| --- | --- | --- | ---: | --- |
+| 1 | C runtime | `runtime/typesol_rt.h` | 1,740 | In every program: input parsing, account checks, checked arithmetic, PDAs, system and token CPIs, account creation, resizing and closing, oracles, signature checks, the heap |
+| 1 | Instruction prologue and constraints | `src/compiler/emit/function.ts` | 584 | Which checks each account parameter gets, and their order |
+| 1 | Account data, Vecs and assignment | `src/compiler/emit/storage.ts`, `statements.ts`, `base.ts` | 2,296 | Reads and writes of account data, growable Vec layout and resizing, references and aliasing, closure and helper expansion |
+| 1 | Calls and CPIs | `src/compiler/emit/calls.ts`, `cpi.ts` | 4,276 | Built-ins, remaining accounts, `invoke` and its account flags, signer seeds, token and Metaplex CPIs, account creation |
+| 1 | Expressions | `src/compiler/emit/expressions.ts`, `shared.ts`, `borsh.ts` | 1,512 | Checked arithmetic and casts, Borsh encoding of arguments and `@layout borsh` accounts |
+| 2 | Front end | `src/compiler/analyze.ts`, `model.ts` | 2,202 | What the language accepts; constraints and account types as parsed from the source |
+| 2 | Interface | `src/compiler/idl.ts`, `src/tools/clientgen.ts` | 2,211 | The IDL and the generated client must describe the program exactly (a mismatch can make clients sign the wrong thing) |
+| 3 | Build and tooling | `src/compiler/toolchain.ts`, `src/cli.ts`, `src/workspace.ts`, `src/tools/` | | Build flags, deploy and verification commands |
+
+The language surface is `lib/typesol.d.ts` (1,711 lines): every type and built-in a program can use, with its
+documented behavior. [docs/language.md](language.md) is the reference; [docs/architecture.md](architecture.md) maps
+the code, [docs/runtime.md](runtime.md) the runtime's conventions.
+
+Out of scope: the Solana runtime, platform-tools (clang, lld), the TypeScript compiler, and programs written with
+TypeSOL.
+
+## What to check
+
+The guarantees in [security-model.md](security-model.md), each of which should hold for every program the compiler
+accepts. Areas where a bug would be most damaging, and where earlier internal reviews found the issues listed below:
+
+- **Account checks**: every parameter type and constraint, also when an account only reaches a helper, a closure or a
+  CPI; optional accounts; the duplicate-writable check.
+- **Aliasing**: two views of one account (parameters, remaining accounts, references held across a call), writes
+  through a place the right side moved.
+- **Account data layout**: growable Vecs after the fixed fields, their lengths against the account size, resizing and
+  the Vecs that follow, `@layout borsh` accounts.
+- **Arithmetic**: every operator and cast at every width, compound assignment, `mulDiv`, rent.
+- **CPIs and signing**: signer-seed arrays (including their reuse across statements), account flags in `invoke`,
+  account creation on pre-funded addresses, closing.
+- **The runtime's parsing**: instruction data, the serialized accounts, Token-2022 extension data, oracle accounts and
+  the instructions sysvar.
+
+## Earlier reviews
+
+Internal reviews, by the maintainers, in October 2026. Their findings and fixes are in the CHANGELOG:
+
+- **0.25.0** (runtime and emitted checks): two Medium issues fixed, a remaining account loaded mutably twice through
+  the same slot, and a Vec element written after its right side resized the Vec; plus a token program ambiguity,
+  `mint::token_program`, oracle options and documentation of `requirePda`, Merkle leaves and `createIfNeeded`.
+- **0.24.0** (compiler review): helper and closure expansion scoped to their own module, stale struct references
+  across Vec moves refused, account-shadowing parameters refused; client SDK hardening.
+- Earlier releases: see `test/security/regressions.test.ts` and `test/security/hardening.test.ts`, which keep every
+  attack that once worked as a failing transaction.
+
+## Evidence
+
+- **Tests**: 570, by subject under `test/` (`docs/architecture.md`). `test/security/` holds the attacks.
+- **Differential tests**: the same transactions to TypeSOL and to Anchor twins (`test/anchor-twins`), comparing
+  outcomes, account contents and balances after every step.
+- **Model-based fuzzing** (`test/verification/`): arithmetic against BigInt at every width; honest and hostile action
+  sequences against state models with value conservation; account layout with two growable Vecs and aliasing through
+  remaining accounts. Each run prints its seed (`FUZZ_SEED`), `pnpm fuzz` runs them wide.
+- **Ported programs**: all 46 programs of solana-developers/program-examples, run through their original tests' flows
+  and failure paths ([test/ports/README.md](../test/ports/README.md)).
+- **Four-way comparison**: [typesol/benchmarks](https://github.com/typesol/benchmarks) runs 17 of those programs in
+  TypeSOL, Anchor, native Rust and Pinocchio, requires the same outcome, and records how each refuses the hostile calls
+  and with which error.
+
+## Running it
+
+```sh
+git clone https://github.com/typesol/typesol && cd typesol
+pnpm install && pnpm build
+pnpm fetch:programs        # Metaplex binaries for the token-metadata, Core and Bubblegum tests
+pnpm build:twins           # the Anchor twins (Rust + Anchor 1.0.2)
+pnpm test                  # everything; CI runs it on Ubuntu (Node 22, 24) per change, macOS daily
+pnpm fuzz                  # the randomized checks, wide
+```
+
+`node dist/cli.js build <program.ts> --out <dir>` writes the generated C next to the binary, which is the most direct
+way to review what a construct compiles to; `test/golden/counter.c` is a pinned example.
+
+## Contact
+
+Coordinate through a private advisory on https://github.com/typesol/typesol/security, or report findings the same way
+(SECURITY.md).

package/docs/case-study-escrow.md

@@ -166,7 +166,7 @@ is marked PORTED in [the ports table](../test/ports/README.md).
 
 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
+- **The port's own test** ([`test/porting/ports-tokens.test.ts`](../test/porting/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.
@@ -184,9 +184,9 @@ Both implementations refuse the hostile calls the comparison makes:
 
 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.
+purpose: taker and maker are then the same writable account, which TypeSOL refuses for any two writable parameters
+unless one is marked `Dup<…>`, 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
 

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

@@ -70,5 +70,5 @@ Where TypeSOL's order differs, only a transaction that breaks two of these check
 - 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
+- TypeSOL refuses any two writable parameters naming one account (2040) unless one is `Dup<…>`, 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,7 +38,7 @@ 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; 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) |
+| 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; `stackHeight()` is 1 when the transaction calls the program directly, more under a CPI (`require(stackHeight() === 1n, …)` refuses CPI callers); `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 |
@@ -76,6 +76,7 @@ The full reference. For a tour, start with the [README](../README.md).
 | `A \| null` / `Optional<A>` | optional account (Anchor `Option<Account>`): the client passes this program's id to leave it out; its checks and constraints run only when present; `x !== null` before use, or `x!` / `x!.field` to assert it was passed (5115 otherwise); `optional` in the IDL |
 | `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` |
+| `Migrate<From, To>` | Anchor 1.0's `Migration`: an existing `From` account (owner, discriminator, size) rewritten as `To` by `acct.migrate(payer, value)`, a top-level statement the instruction must reach. `acct.from` (read-only) before it, `acct.to` after; the value is built in full before the rewrite, so it may read `acct.from`. Resized to `To` (the payer tops up rent when it grows, at most 10 KiB; shrinking keeps the lamports; growing needs `SystemProgram`). Fixed-layout structs without growable Vecs; no constraints yet; the account cannot be passed to a helper (use `acct.to` fields in the instruction). An account already migrated fails with 3002. Keep the old struct under a new name with its discriminator: `/** @discriminator account:Counter */ interface CounterV1 { … }` |
 | `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); 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) |
@@ -86,6 +87,7 @@ The full reference. For a tour, start with the [README](../README.md).
 | `AssociatedTokenProgram` | `create` / `createIdempotent` CPIs; `associatedTokenAddress(owner, mint, tokenProgram)` |
 | `TokenMetadataProgram` | Metaplex `createV3(...)` (CreateMetadataAccountV3), optionally with `{ creators: [{ address, verified, share }], collection: mint }` after `isMutable` (1–5 creators, shares adding up to 100; only the update authority, signing, can be `verified: true`; the collection is written unverified; `isCollection: true` makes the NFT a sized collection); `createMasterEditionV3(edition, mint, updateAuthority, mintAuthority, payer, metadata, tokenProgram, systemProgram, maxSupply \| null)`; `verifyCollection(authority, metadata, collectionMint, collectionMetadata, collectionMasterEdition, systemProgram, instructionsSysvar)` (Verify with CollectionV1); `metadataAddress(mint)`, `masterEditionAddress(mint)` |
 | `InstructionsSysvar`, `PythPriceUpdate`, `SwitchboardFeed` | exact address / owner program + discriminator |
+| `InstructionsSysvar` (introspection) | `ixs.length`, `ixs.currentIndex()` (the top-level instruction being executed), `ixs.get(i)` → a `TransactionInstruction`: `programId`, `accountsLength`, `dataLength`, `accountKey(j)` / `accountIsSigner(j)` / `accountIsWritable(j)`, `readU8/U16/U32/U64/readPubkey(offset)` (little-endian), `is(program, "name")` (that program's instruction by its default Anchor discriminator, sha256("global:<name>"); an instruction with its own `@discriminator` is matched with `programId` and `readU64(0)` instead). Every read is bounds-checked (5104). It is the transaction author's data: require things of the transaction with it (a repay instruction after a flash loan), never treat it as proof |
 | `Program<"Address…">` | exact program address + executable |
 | `UncheckedProgram` | executable only — check `.key` yourself |
 | `AccountInfo` / `Mut<AccountInfo>` | nothing (writable for `Mut`); `owner`, `executable` |
@@ -94,7 +96,10 @@ 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). A remaining account
+account written through `.lamports` or `loadAccountMut` is another account of the instruction). `Dup<Mut<T>>`
+(Anchor's `dup`) lifts that for one parameter when both accounts are read and written in place (not created, closed,
+a close destination or `@layout borsh`): a write through either is seen through the other, so read what you need
+before writing. 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.
 

package/docs/migrate-from-anchor.md

@@ -46,6 +46,8 @@ and error codes. Its notes (on stderr) list what an existing Anchor client would
 | `Option<Account<'info, T>>` | `Mut<T> \| null` (the client passes the program id to leave it out) |
 | `UncheckedAccount` / `AccountInfo` | `AccountInfo` / `Mut<AccountInfo>`: check what you rely on yourself |
 | `SystemAccount<'info>` | `SystemAccount` / `Mut<SystemAccount>` |
+| `Migration<'info, From, To>` | `Migrate<From, To>`, then `acct.migrate(payer, value)`; the old struct keeps its on-chain discriminator with `/** @discriminator account:<OldName> */` |
+| `#[account(discriminator = …)]` | `/** @discriminator <preimage or 0x8 bytes> */` on the struct |
 | `AccountLoader<T>` with `#[account(zero)]` | `Zeroed<T>` (TypeSOL reads every account in place: no copy to avoid) |
 | `Program<'info, System>` | `SystemProgram` |
 | `Program<'info, Token>` / `Token2022` / `Interface<'info, TokenInterface>` | `TokenProgram` / `Token2022Program` / `TokenInterface` |
@@ -57,6 +59,8 @@ and error codes. Its notes (on stderr) list what an existing Anchor client would
 | `#[account(init, payer = p, seeds = […], bump, token::mint = m, token::authority = a)]` | `Init<TokenAccount>`, then `vault.create(p, […], m, a.key)` (`InitIfNeeded<TokenAccount>` + `createIfNeeded`) |
 | `associated_token::mint = m, associated_token::authority = a` | `Ata<TokenAccount, "a", "m">`; `Ata<Init<TokenAccount>, "a", "m">` creates it |
 | `ctx.remaining_accounts` | `remainingAccounts()` |
+| `#[account(mut, dup)]` | `Dup<Mut<T>>` (in-place accounts only) |
+| `sysvar::instructions` (`load_current_index_checked`, `load_instruction_at_checked`), `get_stack_height()` | `InstructionsSysvar`: `currentIndex()`, `get(i)`, `.length`; `stackHeight()` |
 | `ctx.bumps.vault` | the value `create` returns, or `acct.pdaBump` |
 
 ## Account data

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,105 @@
+# 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,
+   unless the program marks one `Dup<…>`, and then only for accounts read and written in place (see below).
+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). A `Migrate<From, To>` account is checked as an existing `From`; `migrate(…)` is a top-level statement every
+   path reaches, builds the new value before rewriting the bytes, and nothing reads the old data after it (compile
+   errors).
+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.
+- **`Dup<…>`.** A parameter marked `Dup` may be the same account as another writable one. Reads see every write
+  (both are the same bytes), so a value read before a write through the other slot is stale: read, then write.
+- **Instruction introspection.** The Instructions sysvar holds what the transaction's author put there. Require things
+  of the transaction with it (that a repay instruction follows), never treat it as proof of who did what.
+- **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 unless one is `Dup<…>` (Anchor compares only program
+  and token accounts, and `dup` lifts that).
+- 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

@@ -186,10 +186,43 @@ export declare function keccak256(...parts: (string | Pubkey | Hash | bigint | b
  */
 export declare function merkleVerify(leaf: Hash, proof: Vec<Hash>, root: Hash): boolean;
 
-/** The Instructions sysvar (Sysvar1nstructions…). Its address is checked. */
+/**
+ * The Instructions sysvar (Sysvar1nstructions…): every instruction of the transaction being executed. Its address is
+ * checked. What it holds is the transaction author's: use it to require something of the transaction (a repay
+ * instruction after a flash loan, a fee instruction before), never as proof of anything else.
+ */
 export interface InstructionsSysvar extends AccountMeta {
   readonly __instructions_sysvar: void;
+  /** How many instructions the transaction has. */
+  readonly length: u64;
+  /** The index of the top-level instruction being executed (this one, or the one that CPI'd into this program). */
+  currentIndex(): u64;
+  /** The transaction's instruction at `index` (5104 when there is none). */
+  get(index: u64): TransactionInstruction;
 }
+/** One instruction of the transaction, read from the Instructions sysvar. Reads past its end fail with 5104. */
+export interface TransactionInstruction {
+  readonly __transaction_instruction: void;
+  readonly programId: Pubkey;
+  readonly accountsLength: u64;
+  readonly dataLength: u64;
+  accountKey(i: u64): Pubkey;
+  accountIsSigner(i: u64): boolean;
+  accountIsWritable(i: u64): boolean;
+  /** Little-endian integers and keys from the instruction data. */
+  readU8(offset: u64): u8;
+  readU16(offset: u64): u16;
+  readU32(offset: u64): u32;
+  readU64(offset: u64): u64;
+  readPubkey(offset: u64): Pubkey;
+  /** `program`'s instruction `name` (snake_case or camelCase): its program id and 8-byte Anchor discriminator match. */
+  is(program: Pubkey, name: string): boolean;
+}
+/**
+ * How deep in cross-program calls this program runs: 1 when the transaction calls it directly, more when another
+ * program invoked it. `require(stackHeight() === 1n, …)` refuses CPI callers.
+ */
+export declare function stackHeight(): u64;
 
 /**
  * True when this transaction contains an Ed25519 precompile instruction that verified `message`
@@ -597,6 +630,27 @@ export type TokenOf<A, MintParam extends string, AuthorityParam extends string =
 export type MintOf<A, AuthorityParam extends string, FreezeAuthorityParam extends string = never, TokenProgramParam extends string = never> = A & {
   readonly __mintOf?: [AuthorityParam, FreezeAuthorityParam, TokenProgramParam];
 };
+/**
+ * Anchor's `dup`: this writable account may be the same account as another writable parameter (TypeSOL refuses that
+ * otherwise, 2040). Both are read and written in place, so a write through one is seen through the other: read
+ * what you need before writing. Not for accounts that are created, closed, a close destination or `@layout borsh`.
+ */
+export type Dup<A> = A & { readonly __dup?: true };
+/**
+ * Anchor 1.0's `Migration<From, To>`: an existing `From` account (owner, discriminator and size checked) that this
+ * instruction rewrites as `To` with `acct.migrate(payer, value)`, a top-level statement every path must reach. Read
+ * the old data through `acct.from` before migrating (the new value may use it: it is built in full before the account
+ * is rewritten), and the new data through `acct.to` after. The account is resized to `To`: the payer tops up the rent
+ * when it grows (at most 10 KiB), and shrinking keeps the lamports. `From` usually keeps the old type's discriminator
+ * under a new name: `/** @discriminator account:Counter *\/ interface CounterV1 { … }`. An account already migrated
+ * fails with 3002, as under Anchor.
+ */
+export interface Migrate<From, To> extends AccountMeta {
+  readonly __migrate: [From, To];
+  readonly from: Readonly<From>;
+  readonly to: To;
+  migrate(payer: Mut<Signer>, value: To): void;
+}
 export type Seeds<A, Names extends readonly string[], Bump extends string = never, ProgramId extends string = never> = A & {
   readonly __seeds?: [Names, Bump, ProgramId];
   /** The PDA's bump (Anchor `ctx.bumps.<account>`): the stored bump field when one is named, else the canonical bump found. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@typesol/cli",
-  "version": "0.25.0",
+  "version": "0.27.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": {