@typesol/cli 0.24.1 → 0.26.0

package/dist/tools/doctor.js

@@ -0,0 +1,229 @@
+// `typesol doctor` and the checks `init` and `deploy` run before they need something: Node, the platform-tools the
+// compiler builds with, the Solana CLI, its keypair and RPC, the project, and (with an RPC) whether it answers and the
+// payer can afford a deploy. Each problem comes with the command that fixes it.
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync, statSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { findToolchain } from "../compiler/toolchain.js";
+import { base58, readKeypair } from "../keys.js";
+import { findWorkspace } from "../workspace.js";
+export const INSTALL_AGAVE = 'sh -c "$(curl -sSfL https://release.anza.xyz/stable/install)"';
+const MIN_NODE = [22, 12];
+/** The platform-tools the compiler needs: found, or what to run. */
+export function toolchainCheck() {
+    try {
+        const tc = findToolchain();
+        let version = "";
+        try {
+            version = execFileSync(tc.clang, ["--version"], { encoding: "utf8" })
+                .split("\n")[0]
+                .replace(/\s*\(.*$/, "");
+        }
+        catch {
+            /* the path is enough */
+        }
+        return { ok: true, what: "platform-tools", detail: version || tc.sdk };
+    }
+    catch (e) {
+        return {
+            ok: false,
+            what: "platform-tools",
+            detail: e.message.split(". ")[0],
+            fix: [INSTALL_AGAVE, "cargo-build-sbf --version   # once: downloads the platform-tools TypeSOL compiles with"],
+        };
+    }
+}
+/** json_rpc_url / keypair_path from a Solana CLI config (the given file, or the CLI's default one). */
+export function solanaConfig(file) {
+    const configPath = file ?? path.join(os.homedir(), ".config/solana/cli/config.yml");
+    if (!existsSync(configPath))
+        return { file: configPath, exists: false };
+    const text = readFileSync(configPath, "utf8");
+    const get = (k) => new RegExp(`^${k}:\\s*["']?([^"'\\n]+?)["']?\\s*$`, "m").exec(text)?.[1];
+    const expand = (p) => (p?.startsWith("~/") ? path.join(os.homedir(), p.slice(2)) : p);
+    return { url: get("json_rpc_url"), keypair: expand(get("keypair_path")), file: configPath, exists: true };
+}
+/** The Solana CLI's cluster monikers, as `solana --url` accepts them; anything else is used as given. */
+export function clusterUrl(url) {
+    const monikers = {
+        "mainnet-beta": "https://api.mainnet-beta.solana.com",
+        m: "https://api.mainnet-beta.solana.com",
+        devnet: "https://api.devnet.solana.com",
+        d: "https://api.devnet.solana.com",
+        testnet: "https://api.testnet.solana.com",
+        t: "https://api.testnet.solana.com",
+        localhost: "http://127.0.0.1:8899",
+        l: "http://127.0.0.1:8899",
+    };
+    return monikers[url] ?? url;
+}
+/** Only the host: an RPC URL can carry an API key in its path or query, and these messages may be shared. */
+export function rpcHost(url) {
+    try {
+        return new URL(url).host;
+    }
+    catch {
+        return "the RPC";
+    }
+}
+/** The cluster an RPC belongs to, for the airdrop hint (mainnet has none). */
+function clusterOf(url) {
+    const host = rpcHost(url);
+    if (/devnet/.test(host))
+        return "devnet";
+    if (/testnet/.test(host))
+        return "testnet";
+    if (/^(127\.0\.0\.1|localhost|0\.0\.0\.0)(:|$)/.test(host))
+        return "localhost";
+    return undefined;
+}
+export async function rpc(url, method, params = []) {
+    const res = await fetch(url, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ jsonrpc: "2.0", id: 1, method, params }),
+        signal: AbortSignal.timeout(10_000),
+    });
+    const body = (await res.json());
+    if (body.error)
+        throw new Error(body.error.message);
+    return body.result;
+}
+/** fetch's "fetch failed" says little: the cause's code (ECONNREFUSED, ENOTFOUND, a timeout) says more. */
+export const errText = (e) => {
+    const err = e;
+    return err.cause?.code ?? err.cause?.message ?? (err.name === "TimeoutError" ? "no answer in 10 s" : err.message);
+};
+const sol = (lamports) => lamports === 0 ? "0 SOL" : lamports < 100_000 ? `${lamports} lamports` : `${(lamports / 1e9).toFixed(lamports < 1e7 ? 4 : 2)} SOL`;
+/** A cost, rounded up so the advice is enough. */
+const solUp = (lamports) => `${(Math.ceil(lamports / 1e7) / 100).toFixed(2)} SOL`;
+/**
+ * Before `solana program deploy`: the RPC answers, and the payer holds enough for the program's rent (a first deploy
+ * holds about twice the binary's rent while the buffer exists; an upgrade, the buffer's). Throws with what to do.
+ */
+export async function deployPreflight(opts) {
+    const host = rpcHost(opts.url);
+    try {
+        await rpc(opts.url, "getVersion");
+    }
+    catch (e) {
+        const local = clusterOf(opts.url) === "localhost";
+        throw new Error(`cannot reach ${host} (${errText(e)}). ` +
+            (local
+                ? "Start a local validator in another terminal: `solana-test-validator`, or deploy to devnet with --url devnet."
+                : "Check --url (or json_rpc_url in the Solana CLI config); for a test deploy use --url devnet or a local `solana-test-validator`."));
+    }
+    if (!opts.payer || !existsSync(opts.payer))
+        return; // the Solana CLI reports a missing keypair itself
+    const payer = base58(readKeypair(opts.payer).subarray(32));
+    let need = 0;
+    for (const p of opts.programs) {
+        const size = statSync(p.soPath).size;
+        const exists = (await rpc(opts.url, "getAccountInfo", [p.address, { encoding: "base64", dataSlice: { offset: 0, length: 0 } }])).value;
+        const rent = await rpc(opts.url, "getMinimumBalanceForRentExemption", [size + 45]);
+        need += exists ? rent : 2 * rent;
+    }
+    need += 5_000_000; // fees for the buffer writes
+    const balance = (await rpc(opts.url, "getBalance", [payer])).value;
+    if (balance >= need)
+        return;
+    const cluster = clusterOf(opts.url);
+    const airdrop = cluster ? ` Get test SOL: \`solana airdrop ${Math.max(2, Math.ceil((need - balance) / 1e9))} ${payer} --url ${cluster}\`.` : "";
+    throw new Error(`the payer ${payer} has ${sol(balance)} on ${host}; deploying needs about ${solUp(need)} (rent, mostly returned when a buffer closes).${airdrop}`);
+}
+/** Everything `typesol doctor` checks, in order. */
+export async function doctorChecks(opts) {
+    const checks = [];
+    const [major, minor] = process.versions.node.split(".").map(Number);
+    const nodeOk = major > MIN_NODE[0] || (major === MIN_NODE[0] && minor >= MIN_NODE[1]);
+    checks.push({
+        ok: nodeOk,
+        what: "Node.js",
+        detail: process.versions.node,
+        fix: nodeOk ? undefined : [`install Node.js ${MIN_NODE.join(".")} or later (https://nodejs.org)`],
+    });
+    checks.push(toolchainCheck());
+    let solanaVersion;
+    try {
+        solanaVersion = execFileSync("solana", ["--version"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] })
+            .split(" (")[0]
+            .trim();
+    }
+    catch {
+        /* not installed */
+    }
+    checks.push(solanaVersion
+        ? { ok: true, what: "Solana CLI", detail: solanaVersion }
+        : { ok: false, optional: true, what: "Solana CLI", detail: "not on PATH (needed to deploy, not to build or test)", fix: [INSTALL_AGAVE] });
+    const cfg = solanaConfig(opts.config);
+    const keypair = cfg.keypair ?? path.join(os.homedir(), ".config/solana/id.json");
+    if (existsSync(keypair)) {
+        let address = "";
+        try {
+            address = base58(readKeypair(keypair).subarray(32));
+        }
+        catch (e) {
+            checks.push({ ok: false, optional: true, what: "keypair", detail: e.message });
+        }
+        if (address)
+            checks.push({ ok: true, what: "keypair", detail: `${address} (${keypair.replace(os.homedir(), "~")})` });
+    }
+    else
+        checks.push({
+            ok: false,
+            optional: true,
+            what: "keypair",
+            detail: `none at ${keypair.replace(os.homedir(), "~")} (the deploy payer)`,
+            fix: ["solana-keygen new"],
+        });
+    const url = opts.url ? clusterUrl(opts.url) : cfg.url;
+    if (!url)
+        checks.push({ ok: false, optional: true, what: "RPC", detail: "none set (deploy takes --url)", fix: ["solana config set --url devnet"] });
+    else {
+        const cluster = clusterOf(url);
+        try {
+            const v = await rpc(url, "getVersion");
+            checks.push({ ok: true, what: "RPC", detail: `${rpcHost(url)} (solana-core ${v["solana-core"]})` });
+            if (existsSync(keypair)) {
+                const balance = (await rpc(url, "getBalance", [base58(readKeypair(keypair).subarray(32))])).value;
+                checks.push(balance > 0
+                    ? { ok: true, what: "balance", detail: sol(balance) }
+                    : {
+                        ok: false,
+                        optional: true,
+                        what: "balance",
+                        detail: `0 SOL on ${rpcHost(url)}`,
+                        fix: [
+                            cluster && cluster !== "localhost"
+                                ? `solana airdrop 2 --url ${cluster}`
+                                : cluster
+                                    ? "solana airdrop 2 --url localhost"
+                                    : "fund the keypair above",
+                        ],
+                    });
+            }
+        }
+        catch (e) {
+            checks.push({
+                ok: false,
+                optional: true,
+                what: "RPC",
+                detail: `${rpcHost(url)} does not answer (${errText(e)})`,
+                fix: cluster === "localhost" ? ["solana-test-validator   # in another terminal"] : ["pass --url devnet, or fix json_rpc_url in the Solana CLI config"],
+            });
+        }
+    }
+    const ws = findWorkspace(opts.cwd);
+    checks.push(ws
+        ? { ok: true, what: "project", detail: `${path.relative(opts.cwd, ws.file) || ws.file}: ${Object.keys(ws.programs).join(", ")}` }
+        : { ok: true, optional: true, what: "project", detail: "none here (typesol init <dir> creates one)" });
+    return checks;
+}
+export function formatChecks(checks) {
+    const mark = (c) => (c.ok ? "ok " : c.optional ? " ! " : "ERR");
+    const width = Math.max(...checks.map((c) => c.what.length));
+    return checks
+        .map((c) => `  ${mark(c)}  ${c.what.padEnd(width)}  ${c.detail}${(c.fix ?? []).map((f) => `\n${" ".repeat(width + 9)}${f}`).join("")}`)
+        .join("\n");
+}

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

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