@typesol/cli 0.15.0 → 0.17.0

package/CHANGELOG.md

@@ -5,6 +5,113 @@ until 1.0, a minor version may change the language, the IDL layout or error code
 
 ## Unreleased
 
+## 0.17.0 — 2026-10-28
+
+Anchor's account bytes on request (`@layout borsh`, so a TypeSOL program can take over an Anchor program's accounts
+without a migration), lists with a fixed capacity anywhere in account data (`FixedVec`), arrow functions and generic
+helpers, Metaplex collection verification, Core plugins and Bubblegum V2, and a faster UTF-8 check. Existing programs
+keep their layouts and error codes (3004 is new, raised only by `@layout borsh` accounts). Not externally audited (see
+SECURITY.md).
+
+### Added
+- `/** @layout borsh */` on an account struct stores it with Anchor's bytes (Borsh String / Vec / Option for
+  `FixedString` / `FixedVec` / `Option`), so a TypeSOL program can take over an Anchor program's accounts without a
+  migration; its IDL lists Anchor's own types. An instruction unpacks the account into the fixed layout when it starts
+  and packs it back when it returns (3003 for bytes that are not a valid value, 3004 when the account is too small).
+  Checked byte for byte against an Anchor twin, including switching programs in the middle of a sequence.
+  `typesol port` marks Anchor account structs that need it.
+- `FixedVec<T, N>`: a list with room for N elements (u32 length + N slots, like `FixedString<N>`) as any account field,
+  several per struct and in nested structs, with `get` / `set` / `push` / `pop` / `clear` / `.length` / `for … of`;
+  `push` on a full one fails with 5104, `fixedVec([…])` writes a whole one. The IDL describes each as a
+  `FixedVec<N>_<T>` struct `{ len, items }`; the generated client reads and writes them as arrays. The
+  basics/favorites port uses one.
+- Bubblegum V2: `createTreeV2`, `mintV2` (optionally into a Metaplex Core collection), `transferV2` and `burnV2`, which
+  take the leaf (root, data and creator hashes, nonce, index) and pass its Merkle proof on from the remaining accounts;
+  the Core `BubblegumV2` collection plugin. Checked against Bubblegum, mpl-account-compression, mpl-noop and Core
+  (`pnpm fetch:programs` now fetches the mpl-account-compression pair too).
+- Metaplex Core plugins: a literal plugin list in `createAsset` / `createCollection` (Royalties, freeze / burn / transfer /
+  update delegates and their permanent forms, Attributes, Edition, AddBlocker, ImmutableMetadata, each with an optional
+  authority), and `addPlugin`, `updatePlugin`, `removePlugin` with their collection forms, checked against the real Core
+  program (a frozen asset cannot move until it is thawed).
+- Arrow functions: `const f = (x: u64): u64 => …` (and `const f = function (…) {…}`) at the top level or inside a
+  function is a helper. Local ones capture nothing (a closure over the enclosing function's variables is refused with
+  the name it reads); functions are called, not passed around.
+- Generic helpers: `function max<T extends bigint>(a: T, b: T): T` compiles once per set of types it is called with,
+  inferred from the arguments or written out (`max<u128>(x, 1n)`); type parameters stand for integers, booleans,
+  Pubkeys or enums.
+- `x as T` (and `satisfies`): names a type the value already has, never a conversion; mainly `return (a + b) as T`
+  in a generic helper.
+- Metaplex collections: `createV3`'s `isCollection: true` (CollectionDetails::V1), `createMasterEditionV3(…, maxSupply | null)`,
+  `verifyCollection(…)` (Verify with CollectionV1) and `masterEditionAddress(mint)`. The tokens/nft-operations port now
+  uses them instead of hand-encoded `invoke`s, checked against the real Token Metadata program.
+
+### Changed
+- IDLs no longer list `FixedString*` / `FixedOption_*` / `FixedVec*` helper types that nothing in them refers to
+  (for example an `Option` used only as an instruction argument, which is Borsh there).
+- UTF-8 checks of strings run eight ASCII bytes at a time: every official-example instruction with a string argument
+  gets cheaper (create_token_mint 40,919 → 39,828 CU, set_favorites 4,282 → 4,195).
+
+## 0.16.0 — 2026-10-28
+
+Everyday TypeScript that Anchor developers reach for (`for … of`, `??`, destructuring, `**`, structs returned from
+helpers and instructions, strings in enum variants), tools to move an Anchor program over (`typesol port`, a migration
+guide) and to work on it (`typesol/testing`, an editor plugin, `verify` against the cluster), Token-2022 extension
+setup and Metaplex creators. No IDL or error-code changes for existing programs. Not externally audited (see
+SECURITY.md).
+
+### Added
+- Metaplex `createV3(…, isMutable, { creators, collection }, signerSeeds?)`: 1–5 creators (shares checked to add up to 100
+  when literal) and an unverified collection mint, checked against the real Token Metadata program.
+- Data-enum variants can hold a `string` (`type Cmd = { kind: "Say"; text: string } | …`), as Anchor enums with `String`
+  payloads: Borsh in instruction arguments and events, a value in code (a copy when built from account text), refused
+  in account data. The IDL describes them as Borsh enums only.
+- `typesol port <idl.json>`: a TypeSOL program skeleton from an Anchor IDL (structs, enums, errors, one function per
+  instruction with its accounts and arguments). Discriminators, account names and error codes are kept, so existing
+  clients keep working where layouts match; notes list where Anchor's Borsh layout differs. Round-trips every example
+  (example → IDL → port → IDL) with the same instructions, accounts, layouts and error codes.
+- Token-2022 extension initializers on `Token2022Program` / `TokenInterface` (refused on `TokenProgram`): transfer fee,
+  mint close authority, non-transferable, permanent delegate, default account state, metadata / group / group-member
+  pointers, transfer hook, interest-bearing, immutable owner. Byte layouts checked against the official
+  @solana-program/token-2022 decoder on real mints.
+- `typesol/ts-plugin`: a TypeScript language-service plugin that shows the compiler's own errors in the editor, for
+  the unsaved text, once TypeScript has none. `typesol init` projects enable it in `programs/tsconfig.json` (the
+  editor must use the workspace's TypeScript). `typesol check` gains `--json` and `--stdin`.
+- `typesol/testing`: `testProgram(name, import.meta.url)` builds a project program into LiteSVM, with `wallet()`, `pda(…)`,
+  `ix(name, args, accounts)` (accounts by name, flags, fixed addresses and PDAs from the IDL, plain argument values),
+  `send`, `ok`, `errorCode`, `account` (decoded to bigints and address strings), `returned` and `balance`. The
+  `typesol init` templates' tests use it (the counter test went from 70 lines to 20). See docs/test-your-program.md.
+- `a ** b` on integers, every multiplication checked (5100 on overflow or a negative exponent, where JS throws). A
+  literal exponent unrolls at compile time; otherwise a square-and-multiply loop runs.
+- Object destructuring: `const { owner, pos: p } = acct` (`let` for scalars) from a name or a field path, read like
+  `acct.owner` (scalars copied, nested structs referenced). Rest elements, defaults and nested patterns are refused.
+- Instructions can return a fixed-size struct as return data (a literal, a stored struct or a helper's result), at
+  most 1024 bytes. It goes out in its fixed layout, which the IDL describes under `returns`, so Anchor clients and the
+  generated TypeScript client decode it.
+- Helpers can return a fixed-size struct: `return { x, y }`, a stored struct or another helper's result. The caller
+  gets its own copy to bind (`const p: Point = at(1n, 2n)`), store (`acct.home = at(…)`, `arr.set(i, at(…))`) or read
+  (`at(…).x`). Structs with a Vec or variable-length strings cannot be returned.
+- `a ?? b` on Options of integers, booleans and Pubkeys (b is evaluated only when a is empty; the result is an
+  Option when b can be null), and `x!` on an Option (its value; an empty one aborts with 5108).
+- `for (const x of list)` over a `Vec` (account field or argument) or a `FixedArray`: each `x` is what `list.get(i)`
+  gives (a value, or a reference into account data for structs, with the same aliasing checks), the length is read
+  again before every step as in JS, and `break` / `continue` work. Remaining accounts are still iterated by index.
+- `typesol verify <program>` without a `.so` reads the deployed program from the cluster (`--address`, or the address
+  in `typesol.json`; `--url`, cluster monikers or the Solana CLI config) under loader v2, v3 or v4, prints its upgrade
+  authority or that it is immutable and its last deploy slot, and compares the IDL published on chain with the built
+  one. A published IDL that differs is a mismatch (exit 3). No `solana program dump` step needed.
+- `typesol idl publish --url` accepts the Solana CLI's cluster monikers (`mainnet-beta`, `devnet`, …).
+
+### Fixed
+- `createV3` evaluates its arguments in source order (a creator share computed by a helper that changes account text
+  no longer changes the name or fee read before it).
+- A function whose stack frame exceeds SBPF v0's 4 KiB used to build and then corrupt memory at runtime (the toolchain
+  only printed a note). The build now fails, naming the instruction or helper and its frame size (v1/v2 frames grow
+  dynamically and are not limited).
+
+### Docs
+- docs/migrate-from-anchor.md: Anchor constructs, account data, code and tooling mapped to TypeSOL, with the `typesol port`
+  workflow and which account layouts differ.
+
 ## 0.15.0 — 2026-10-27
 
 Project templates for `typesol init`, a mainnet deployment guide, and clearer `typesol idl publish` failures. No

package/README.md

@@ -34,8 +34,8 @@ clients read TypeSOL programs unchanged.
 - **Small and fast.** On the same programs, TypeSOL uses 5–46% of Anchor's compute units, with binaries about 10×
   smaller. It also uses fewer compute units than native Rust and than hand-tuned Pinocchio on every benchmarked
   instruction.
-- **Reproducible.** The same sources and toolchain produce the same bytes. `typesol verify` checks a deployed program
-  against its source.
+- **Reproducible.** The same sources and toolchain produce the same bytes. `typesol verify` reads a deployed program
+  from the cluster and checks it, and the IDL published on chain, against its source.
 
 <p align="center">
   <a href="#numbers">
@@ -162,7 +162,9 @@ existing project: `npm install -D typesol@npm:@typesol/cli`.
 Deploying again upgrades the program in place. Keep `target/deploy/<name>-keypair.json`: that keypair is your
 program's address.
 
-To go to mainnet (wallet, cost, deploy, IDL, verification), follow [docs/mainnet.md](docs/mainnet.md).
+Coming from Anchor: [docs/migrate-from-anchor.md](docs/migrate-from-anchor.md) maps every construct, and `typesol port`
+starts from your program's IDL. Tests use `typesol/testing` (accounts by name, plain values; [docs/test-your-program.md](docs/test-your-program.md)). To go to
+mainnet (wallet, cost, deploy, IDL, verification), follow [docs/mainnet.md](docs/mainnet.md).
 
 ## How it works
 
@@ -189,8 +191,8 @@ Runtime failures point back to your source: `Error 6000 Unauthorized (counter.ts
 | --- | --- |
 | **Accounts** | `Signer`, `Account<T>`, `Mut<T>`, `Init<T>`, `InitIfNeeded<T>` (PDAs and associated token accounts), `Zeroed<T>` (up to 10 MiB), optional accounts (`A \| null`), token accounts and mints, programs, sysvars |
 | **Constraints** | `HasOne`, `Seeds` (also from account fields and under another program; `pdaBump` like `ctx.bumps`), `CloseTo`, `Ata`, `Address`, `Owner`, `Executable`. They are checked before the body runs and recorded in the IDL |
-| **Data** | `u8`…`u128`, `i8`…`i128`, `boolean`, `Pubkey`, `Hash`, nested structs, `FixedArray`, `FixedString`, `Option`, unit enums, data enums (discriminated unions), `Vec` that resizes its account |
-| **Control flow** | `if`, `for`, `while`, `switch` (with narrowing on data enums), ternaries, helper functions across multiple files |
+| **Data** | `u8`…`u128`, `i8`…`i128`, `boolean`, `Pubkey`, `Hash`, nested structs, `FixedArray`, `FixedString`, `Option`, unit enums, data enums (discriminated unions), `Vec` that resizes its account, `FixedVec` lists anywhere, and Anchor's own byte layout (`@layout borsh`) to take over existing Anchor accounts |
+| **Control flow** | `if`, `for`, `for … of`, `while`, `switch` (with narrowing on data enums), ternaries, `??`, destructuring, helper functions (returning structs too, arrow functions, generics) across multiple files |
 | **CPIs** | System, SPL Token, Token-2022 (including extension reads and metadata), ATA, Metaplex Token Metadata, Core, Bubblegum. Generic `invoke` with PDA signing, return data, and typed bindings generated from any Anchor IDL (`typesol cpi`) |
 | **Events** | `emit` (log-based) and `emitCpi` (Anchor `emit_cpi!`, through a self-CPI) |
 | **Crypto & oracles** | `sha256`, `keccak256`, Merkle proofs, Ed25519 and secp256k1 signature checks, Pyth pull oracle, Switchboard |
@@ -209,7 +211,9 @@ The full reference, with every type, check and built-in, is in [docs/language.md
 | `typesol idl publish` | upload the IDL to the Program Metadata program (canonical when the upgrade authority signs) |
 | `typesol cpi <idl.json>` | generate typed CPI helpers for another program |
 | `typesol client <idl.json>` | generate a typed TypeScript client from an Anchor IDL (`typesol build` writes one per program) |
-| `typesol verify` | rebuild from source and compare with a deployed binary |
+| `typesol port` | a TypeSOL skeleton of an Anchor program from its IDL, keeping discriminators and error codes |
+| `typesol/ts-plugin` | the compiler's errors in the editor as you type ([docs/cli.md](docs/cli.md#editor)) |
+| `typesol verify` | rebuild from source and compare with the program and IDL on chain (or a dumped `.so`) |
 | `typesol profile` | compute units per TypeScript line, from a `--profile` build's logs |
 | `typesol emit-c` | print the generated C |
 
@@ -302,7 +306,7 @@ Details are in [docs/testing.md](docs/testing.md).
 
 ## Status
 
-**TypeSOL is pre-1.0 (0.15).** Releases follow the organization's
+**TypeSOL is pre-1.0 (0.17).** Releases follow the organization's
 [versioning policy](https://github.com/typesol/.github/blob/main/VERSIONING.md); [CHANGELOG.md](CHANGELOG.md) lists every
 change.
 - The compiler, runtime and tooling have been through internal security reviews and are covered by the tests above.

package/dist/cli.js

@@ -5,8 +5,10 @@ import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { parseArgs } from "node:util";
+import ts from "typescript";
 import { build, CompileError, COMPILER_VERSION, generate, SBPF_VERSIONS, verifyBinary } from "./compiler/index.js";
 import { generateCpi } from "./cpigen.js";
+import { generatePort } from "./portgen.js";
 import { generateClient, writeClient } from "./clientgen.js";
 import { buildIdl } from "./compiler/idl.js";
 import { decodeAddress, loadOrCreateKeypair, readKeypair } from "./keys.js";
@@ -120,13 +122,35 @@ const COMMANDS = {
         },
     },
     check: {
-        usage: "typesol check <program.ts>",
-        help: "Typecheck and validate the TypeSOL subset without building.",
-        options: {},
-        run(_, args) {
-            const { model } = generate(mustExist(one(args, "<program.ts>")));
-            log(`ok  ${model.name}: ${model.instructions.length} instruction(s), ${model.accountStructs.size} account type(s), ${model.events.size} event(s)`);
-            return 0;
+        usage: "typesol check <program.ts> [--json] [--stdin]",
+        help: [
+            "Typecheck and validate the TypeSOL subset without building.",
+            "--json    print { ok, diagnostics: [{ file, line, column, message }] } (exit 1 when there are diagnostics)",
+            "--stdin   read <program.ts>'s text from stdin instead of the file (an editor's unsaved buffer); its imports are read from disk",
+        ].join("\n  "),
+        options: { json: { type: "boolean" }, stdin: { type: "boolean" } },
+        run(v, args) {
+            const file = path.resolve(one(args, "<program.ts>"));
+            const restore = v.stdin ? overrideFile(file, readFileSync(0, "utf8")) : undefined;
+            try {
+                if (!v.stdin)
+                    mustExist(file);
+                const { model } = generate(file);
+                if (v.json)
+                    log(JSON.stringify({ ok: true, diagnostics: [] }));
+                else
+                    log(`ok  ${model.name}: ${model.instructions.length} instruction(s), ${model.accountStructs.size} account type(s), ${model.events.size} event(s)`);
+                return 0;
+            }
+            catch (e) {
+                if (!v.json || !(e instanceof CompileError))
+                    throw e;
+                log(JSON.stringify({ ok: false, diagnostics: e.diagnostics }));
+                return 1;
+            }
+            finally {
+                restore?.();
+            }
         },
     },
     "emit-c": {
@@ -195,7 +219,7 @@ const COMMANDS = {
             const kit = await import("@solana/kit");
             const { publishIdl, rpcChain } = await import("./idlpublish.js");
             const signer = await kit.createKeyPairSignerFromBytes(readKeypair(keyFile));
-            const chain = rpcChain(kit.createSolanaRpc(rpcUrl));
+            const chain = rpcChain(kit.createSolanaRpc(clusterUrl(rpcUrl)));
             for (const name of names(ws, args)) {
                 // The IDL only needs the compiled model and the program address: the deployed binary is left alone.
                 const { address } = programAddress(ws, name);
@@ -228,6 +252,30 @@ const COMMANDS = {
             return 0;
         },
     },
+    port: {
+        usage: "typesol port <idl.json> [--out <file.ts>]",
+        help: [
+            "A TypeSOL program skeleton from an Anchor IDL (0.30+/1.x): account structs, enums, errors, events and one function per",
+            "instruction with its accounts and arguments (bodies to fill in). Discriminators, account names and error order are kept,",
+            "so existing clients keep working where the layouts match; the notes (stderr) list where they do not.",
+        ].join("\n  "),
+        options: { out: { type: "string" } },
+        run(v, args) {
+            const file = one(args, "<idl.json>");
+            const res = generatePort(readJson(file));
+            if (v.out) {
+                if (existsSync(v.out))
+                    throw new UsageError(`${v.out} exists; refusing to overwrite it`);
+                writeFileSync(v.out, res.source);
+                log(`  wrote ${v.out}`);
+            }
+            else
+                process.stdout.write(res.source);
+            for (const n of res.notes)
+                console.error(`  note: ${n}`);
+            return 0;
+        },
+    },
     client: {
         usage: "typesol client <idl.json> [--out <file.ts>] [--address <base58>]",
         help: "Generate a typed TypeScript client (on @solana/kit) from an Anchor IDL (0.30+/1.x or TypeSOL). The IDL is validated first;\n  what the client leaves out is printed as notes. `typesol build` already writes <name>.client.ts for TypeSOL programs.",
@@ -249,41 +297,95 @@ const COMMANDS = {
         },
     },
     verify: {
-        usage: "typesol verify <program.ts | program> <deployed.so> [--sbpf v0|v1|v2]",
+        usage: "typesol verify <program.ts | program> [<deployed.so>] [--address <program id>] [--url <rpc>] [--config <solana cli config>] [--sbpf v0|v1|v2]",
         help: [
-            "Rebuild and compare with a deployed binary (e.g. from `solana program dump`). Exit 0 on a match, 3 on a mismatch.",
+            "Rebuild and compare with what is deployed. Exit 0 on a match, 3 on a mismatch.",
+            "With a .so (e.g. from `solana program dump`): compare with that file.",
+            "Without one: read the program from the cluster (--url, else the Solana CLI config) at --address, or at the address",
+            "typesol.json records for a project program. Also prints the upgrade authority and compares the IDL published",
+            "on chain (`typesol idl publish`) with the one the source builds; a published IDL that differs is a mismatch.",
             "The SBPF version is read from the deployed binary unless --sbpf is given. Reproducible builds need the same",
             "TypeSOL version and platform-tools as the original (see its <name>.build.json).",
         ].join("\n  "),
-        options: { sbpf: { type: "string" } },
-        run(v, args) {
-            if (args.length !== 2)
-                throw new UsageError("verify takes the program and the deployed .so");
+        options: { sbpf: { type: "string" }, address: { type: "string" }, url: { type: "string" }, config: { type: "string" } },
+        async run(v, args) {
+            if (args.length < 1 || args.length > 2)
+                throw new UsageError("verify takes the program and, optionally, the deployed .so");
             const [target, deployedPath] = args;
+            if (deployedPath && (v.address || v.url))
+                throw new UsageError("give either a deployed .so or --address/--url, not both");
+            if (v.address && !decodeAddress(v.address))
+                throw new UsageError(`--address "${v.address}" is not a base58 Solana address`);
             const ws = findWorkspace(process.cwd());
             const name = ws && (ws.programs[target] ? target : programForEntry(ws, target));
             const entry = ws && name ? programPaths(ws, name).entry : target;
             if (!existsSync(entry))
                 throw new UsageError(`${entry} does not exist`);
-            if (!existsSync(deployedPath))
-                throw new UsageError(`${deployedPath} does not exist`);
-            const deployed = readFileSync(deployedPath);
+            let deployed;
+            let onChain;
+            if (deployedPath) {
+                if (!existsSync(deployedPath))
+                    throw new UsageError(`${deployedPath} does not exist`);
+                deployed = readFileSync(deployedPath);
+            }
+            else {
+                const address = v.address ?? (ws && name ? ws.programs[name].address : undefined);
+                if (!address)
+                    throw new UsageError("no program address: pass --address, a deployed .so, or name a project program that has been built");
+                const rpcUrl = v.url ?? solanaConfig(v.config).url;
+                if (!rpcUrl)
+                    throw new Error("no RPC: pass --url, or set json_rpc_url in the Solana CLI config");
+                // Loaded only here: the other commands do not need an RPC client.
+                const kit = await import("@solana/kit");
+                const { fetchDeployed } = await import("./onchain.js");
+                const rpc = kit.createSolanaRpc(clusterUrl(rpcUrl));
+                const info = await fetchDeployed(rpc, address);
+                onChain = { address, info, rpc };
+                deployed = info.elf;
+            }
             // ELF e_flags (offset 0x30) hold the SBPF version: 0 for v0, 1 for v1, 2 for v2.
             const flags = deployed.length > 0x34 && deployed.readUInt32BE(0) === 0x7f454c46 ? deployed.readUInt32LE(0x30) : 0;
             const sbpf = sbpfOf(v) ?? SBPF_VERSIONS[flags] ?? "v0";
             const dir = mkdtempSync(path.join(os.tmpdir(), "typesol-verify-"));
             let res, same;
             try {
-                res = build(entry, dir, "11111111111111111111111111111111", { sbpf });
+                res = build(entry, dir, onChain?.address ?? "11111111111111111111111111111111", { sbpf });
                 same = verifyBinary(deployed, readFileSync(res.soPath));
             }
             finally {
                 rmSync(dir, { recursive: true, force: true });
             }
+            const what = deployedPath ??
+                `${onChain.address} (${onChain.info.dataAccount === onChain.address ? "" : `data ${onChain.info.dataAccount}, `}loader ${onChain.info.loader})`;
             log(same
                 ? `  match     ${res.manifest.binary} (sbpf ${sbpf})`
-                : `  MISMATCH  ${deployedPath} is not what ${entry} builds to (${res.manifest.binary}, sbpf ${sbpf})`);
-            return same ? 0 : 3;
+                : `  MISMATCH  ${what} is not what ${entry} builds to (${res.manifest.binary}, sbpf ${sbpf})`);
+            if (!onChain)
+                return same ? 0 : 3;
+            const { info } = onChain;
+            log(`  authority ${info.authority ?? "none: the program is immutable"}${info.slot !== undefined ? `; last deployed in slot ${info.slot}` : ""}`);
+            const { fetchIdl, metadataAddress } = await import("./idlpublish.js");
+            const { canonicalJson } = await import("./onchain.js");
+            // No canonical metadata account means nothing was published; one that cannot be read is an error, not "none".
+            const at = await metadataAddress(onChain.address, null);
+            const exists = (await onChain.rpc.getAccountInfo(at, { encoding: "base64" }).send()).value !== null;
+            if (!exists) {
+                log("  idl       none published on chain (typesol idl publish)");
+                return same ? 0 : 3;
+            }
+            let published;
+            try {
+                published = await fetchIdl(onChain.rpc, onChain.address);
+            }
+            catch (e) {
+                log(`  IDL ERROR  the IDL at ${at} could not be read: ${e.message}`);
+                return 3;
+            }
+            const idlSame = canonicalJson(published) === canonicalJson(res.idl);
+            log(idlSame
+                ? "  idl       match: the published IDL is the one the source builds"
+                : "  IDL MISMATCH  the published IDL differs from the one the source builds");
+            return same && idlSame ? 0 : 3;
         },
     },
     profile: {
@@ -356,6 +458,31 @@ function readJson(file) {
         throw new Error(`${file}: not valid JSON (${e.message})`);
     }
 }
+/** Make the compiler read `text` for `file` (instead of the disk) until the returned function is called. */
+function overrideFile(file, text) {
+    const sys = ts.sys;
+    const { readFile, fileExists } = sys;
+    sys.readFile = (p, enc) => (path.resolve(p) === file ? text : readFile.call(sys, p, enc));
+    sys.fileExists = (p) => path.resolve(p) === file || fileExists.call(sys, p);
+    return () => {
+        sys.readFile = readFile;
+        sys.fileExists = fileExists;
+    };
+}
+/** The Solana CLI's cluster monikers, as `solana --url` accepts them; anything else is used as given. */
+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;
+}
 /** json_rpc_url / keypair_path from a Solana CLI config (the given file, or the CLI's default one). */
 function solanaConfig(file) {
     const configPath = file ?? path.join(os.homedir(), ".config/solana/cli/config.yml");

package/dist/clientgen.js

@@ -43,6 +43,7 @@ export const TYPESOL_ERRORS = {
     3000: "AccountDiscriminatorAlreadySet",
     3002: "AccountDiscriminatorMismatch",
     3003: "AccountDidNotDeserialize",
+    3004: "AccountDidNotSerialize",
     3005: "AccountNotEnoughKeys",
     3006: "AccountNotMutable",
     3007: "AccountOwnedByWrongProgram",
@@ -383,6 +384,8 @@ export function generateClient(idl, opts = {}) {
         const arrayLen = (t) => (typeof t === "object" && t.array ? Number(t.array[1]) : NaN);
         if (/^FixedString\d+$/.test(n) && f[0].name === "len" && Number.isInteger(arrayLen(f[1].type)))
             return { kind: "fstring", cap: arrayLen(f[1].type) };
+        if (/^FixedVec\d+_/.test(n) && f[0].name === "len" && f[1].name === "items" && Number.isInteger(arrayLen(f[1].type)))
+            return { kind: "fvec", elem: f[1].type.array[0], cap: arrayLen(f[1].type) };
         if (n.startsWith("FixedOption_") && f[0].name === "is_some")
             return { kind: "foption", inner: f[1].type };
         if (n.startsWith("FixedEnum_") && f[0].name === "tag" && defs.has(n.slice("FixedEnum_".length)) && Number.isInteger(arrayLen(f[1].type)))
@@ -476,6 +479,8 @@ export function generateClient(idl, opts = {}) {
         const s = special(n);
         if (s?.kind === "fstring")
             return "string";
+        if (s?.kind === "fvec")
+            return `Array<${tsType(s.elem, dir)}>`;
         if (s?.kind === "foption")
             return `${tsType(s.inner, dir)} | null`;
         if (s?.kind === "fenum")
@@ -484,6 +489,7 @@ export function generateClient(idl, opts = {}) {
     }
     let needsFixedString = false;
     let needsFixedOption = false;
+    let needsFixedVec = false;
     let needsUnitEnum = false;
     function codec(t) {
         if (typeof t === "string") {
@@ -525,6 +531,11 @@ export function generateClient(idl, opts = {}) {
         const s = special(n);
         if (s?.kind === "fstring")
             return ((needsFixedString = true), `fixedString(${s.cap})`);
+        if (s?.kind === "fvec") {
+            if (idlSize(s.elem) === undefined)
+                throw new ClientIdlError(`${n}: the elements have no fixed size`);
+            return ((needsFixedVec = true), `fixedVec(${codec(s.elem)}, ${idlSize(s.elem)}, ${s.cap})`);
+        }
         if (s?.kind === "foption") {
             const size = idlSize(s.inner);
             if (size === undefined)
@@ -560,6 +571,10 @@ export function generateClient(idl, opts = {}) {
         const sp = special(n);
         if (sp?.kind === "fstring")
             return 4 + sp.cap;
+        if (sp?.kind === "fvec") {
+            const e = idlSize(sp.elem);
+            return e === undefined ? undefined : 4 + e * sp.cap;
+        }
         if (sp?.kind === "fenum")
             return sp.size;
         if (sp?.kind === "foption") {
@@ -982,6 +997,28 @@ export function generateClient(idl, opts = {}) {
                 `  });`,
             ],
         });
+    if (needsFixedVec)
+        helperDefs.push({
+            name: "fixedVec",
+            lines: [
+                `/** TypeSOL FixedVec<T, N> in account data: u32 length, then room for N elements (unused ones zero). */`,
+                `const fixedVec = <From, To extends From>(item: Codec<From, To>, size: number, cap: number): Codec<From[], To[]> =>`,
+                `  createCodec<From[], To[]>({`,
+                `    fixedSize: 4 + size * cap,`,
+                `    write: (value, bytes, offset) => {`,
+                `      if (value.length > cap) throw new Error(value.length + " elements; the field holds " + cap);`,
+                `      bytes.fill(0, offset, offset + 4 + size * cap);`,
+                `      getU32Codec().write(value.length, bytes, offset);`,
+                `      value.forEach((v, i) => item.write(v, bytes, offset + 4 + i * size));`,
+                `      return offset + 4 + size * cap;`,
+                `    },`,
+                `    read: (bytes, offset) => {`,
+                `      const n = Math.min(getU32Codec().read(bytes, offset)[0], cap);`,
+                `      return [Array.from({ length: n }, (_, i) => item.read(bytes, offset + 4 + i * size)[0]), offset + 4 + size * cap];`,
+                `    },`,
+                `  });`,
+            ],
+        });
     if (needsUnitEnum)
         helperDefs.push({
             name: "unitEnum",

package/dist/compiler/analyze.d.ts

@@ -1,12 +1,18 @@
 import ts from "typescript";
 import { Reporter } from "./diagnostics.js";
-import { type DataEnumDef, type EnumDef, type ProgramModel, type ScalarType, type StructDef, type ValueType, isScalar } from "./model.js";
+import { type DataEnumDef, type EnumDef, type GenericHelper, type Helper, type ProgramModel, type ScalarType, type StructDef, type ValueType, isScalar } from "./model.js";
 export declare const LIB_PATH: string;
+/** Why a name cannot be used as a C member, or undefined when it can. */
+export declare function cNameProblem(name: string): string | undefined;
 /** Solana's account size limit, and what a program can allocate itself through a CPI (Init<T>). */
 export declare const MAX_ACCOUNT_SIZE: number;
+/** sol_set_return_data's limit. */
+export declare const MAX_RETURN_DATA = 1024;
 export declare const MAX_CPI_ALLOCATION: number;
 export interface Analysis {
     model: ProgramModel;
+    /** A generic helper's instance for these type arguments (analyzed once, then kept in `model.helpers`). */
+    instantiate(g: GenericHelper, typeArgs: ScalarType[]): Helper;
     /** TypeScript's checker: used for narrowing (which variant a data-enum value is in a branch). */
     checker: ts.TypeChecker;
     sourceFile: ts.SourceFile;
@@ -19,6 +25,8 @@ export interface Analysis {
 /** What type resolution needs: imports, unit enums, and where to record Option<T> uses. */
 export interface TypeScope {
     imports: Map<string, string>;
+    /** Inside a generic helper's instance: type parameter -> the type it stands for. */
+    typeArgs?: Map<string, ScalarType>;
     enums: Map<string, EnumDef>;
     dataEnums?: Map<string, DataEnumDef>;
     options: Map<string, ScalarType | {
@@ -45,4 +53,6 @@ export declare function resolveOptionType(node: ts.TypeNode, scope: TypeScope):
 }) | undefined;
 /** Values a local, argument or helper parameter can hold. */
 export declare function resolveValueType(node: ts.TypeNode, scope: TypeScope, allowVec?: boolean): ValueType | undefined;
+/** The helper (or generic) a call's callee names: a local function by its declaration, others by name. */
+export declare function calleeName(callee: ts.Identifier, decls: Map<ts.Node, string>, checker: ts.TypeChecker): string | undefined;
 export { isScalar };