@typesol/cli 0.14.0 → 0.16.0

package/CHANGELOG.md

@@ -5,6 +5,87 @@ until 1.0, a minor version may change the language, the IDL layout or error code
 
 ## Unreleased
 
+## 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
+language, IDL or error-code changes. Not externally audited (see SECURITY.md).
+
+### Added
+- `typesol init --template counter|vault|escrow`: start from a PDA counter (the default, as before), a SOL vault or an
+  SPL token escrow. Each template is the matching `examples/` program with a LiteSVM test of its main flow and of a
+  refused call; the escrow project also gets `@solana-program/token`.
+
+### Fixed
+- `typesol idl publish` names the reason a write failed (the transaction's error and its last log lines) instead of
+  "The provided transaction plan failed to execute".
+
+### Docs
+- docs/mainnet.md: from `typesol init` to a verified program on mainnet-beta (wallet, cost, deploy, IDL, `verify`,
+  freezing and closing).
+- README: the official escrow on mainnet-beta in all four versions, with each transaction's compute units linked to
+  Solscan; the TypeSOL program's IDL is published on chain.
+
 ## 0.14.0 — 2026-10-27
 
 PDAs are derived without the PDA syscalls, so instructions that create, check or search for PDAs use up to a few

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">
@@ -152,6 +152,9 @@ npx typesol build                             # target/counter/{counter.so, coun
 npx typesol deploy --url http://127.0.0.1:8899 --keypair ~/.config/solana/id.json
 ```
 
+`--template vault` or `--template escrow` starts from a SOL vault or an SPL token escrow instead of the counter, each
+with a passing LiteSVM test.
+
 The npm package is [`@typesol/cli`](https://www.npmjs.com/package/@typesol/cli). Projects install it under the name
 `typesol`, which is what programs import (`import { … } from "typesol"`); `typesol init` sets that up. To add it to an
 existing project: `npm install -D typesol@npm:@typesol/cli`.
@@ -159,6 +162,10 @@ 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.
 
+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
 
 ```
@@ -185,7 +192,7 @@ 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 |
+| **Control flow** | `if`, `for`, `for … of`, `while`, `switch` (with narrowing on data enums), ternaries, `??`, destructuring, helper functions (returning structs too) 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 |
@@ -204,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 |
 
@@ -246,6 +255,27 @@ CPI account records only for the accounts a call lists. It uses fewer compute un
 instruction here, while also refusing duplicate writable accounts as Anchor does. Fewer compute
 units are not a safety claim. The differential tests also run the escrow against its Anchor twin ([docs/testing.md](docs/testing.md)).
 
+### On mainnet
+
+The official escrow ([tokens/escrow](https://github.com/solana-developers/program-examples/tree/de090195e4de698e150572c4f886c333323a64a5/tokens/escrow)),
+deployed to Solana mainnet-beta in all four versions on 2026-10-27 and called with the same mints, amounts and accounts,
+one instruction per transaction. Each figure is the compute units of that transaction, linked to Solscan; the lowest per row is in bold. The deployed
+programs match these builds byte for byte (`typesol verify` for TypeSOL), and the TypeSOL program's IDL is published
+on chain with `typesol idl publish`.
+
+| Transaction | TypeSOL | Pinocchio | Native Rust | Anchor |
+| --- | ---: | ---: | ---: | ---: |
+| make_offer (offer 1) | [20,304](https://solscan.io/tx/32PVva77dT1rSWrMWX2sHTMPZiwztdEZYtpANaxrsuJxPcd3hnV6pDgJJaV4LkL3bX6ALDoHMNF8fjngtodYHBS1) | [**19,645**](https://solscan.io/tx/528BdMTrnLWauSXVh2vaFfy4XwKFpbyt95hQ6w3fwjtpkT85RPkRhGydunAizNDRqTTLPxcEVMrdcDvRer4H9LRE) | [30,698](https://solscan.io/tx/4MQgt75MvojaAkfxnvrE2yJWabGpE8bsZhNq2CeGJxHZg6uD6A64Kv71JmrsgiGnaEovvv8K34DYL49owLjhs4QJ) | [38,648](https://solscan.io/tx/9T1ZY9JaSMb1GMqv1i22AuZuJQN6B5XcgqeDv5tGqEm5Uox3MBTdXsECt59GwcXkFG9QKgXJyqndTEzpSXhbAVM) |
+| take_offer (offer 1) | [**7,998**](https://solscan.io/tx/49EQwgnKShFdsAs37AEzYmv6tLY8DipcCjmRgqwj4fVTFEgVVWdEXw5AvuEufL5ymJYs4T4hVFdkENW9XK9een5m) | [25,206](https://solscan.io/tx/21MGkXpKRe4c7EeA1hC6JHevsk78xUdbcWmyqG47EbLeCNKSMTzTjkJQqtydnQmV8uHPmr6bJHnvQmmQTSZB7Am2) | [28,612](https://solscan.io/tx/B1hu1EL4Y5vWhBVWdyZEpzRNJb8kd6G9CgN7KtyNNGpQ84o9dfn1sdy9Z1UCHECNtp24Mw8bEH2iYz2YADdEUjx) | [32,835](https://solscan.io/tx/3ZLuQQz7Bx5YdgmFXpVQWHn5kyc8v39jr2BnfofH6sqenzfJpAdVm4h38uYcHwYygnfso92kJe7HRHeASsABoKPQ) |
+| make_offer (offer 2) | [21,804](https://solscan.io/tx/xuu9KXbZvzGDpTEEcDE9LYvBqmPen81y6ty92e6crRxT8m4Mc4XyxhjWHbjVNsr9RE3QY4M1j1Sw9cH7PRMKKuc) | [**19,645**](https://solscan.io/tx/LLzS13AJrqACGoT1VHZN278ij39pNkttb1Z4Wh2AYXknWxwjaiaiMeD7WZomjP6TBv18RHfQHUfogQzApvXr2mC) | [35,198](https://solscan.io/tx/4xiKfzyccVatef1T52tZ3VAJwcx5R7iWgHWezBzZ3p2WpvoLzMp1PSUgr7x3sspE53mDE5JaghaNPKuUohVgPuwc) | [47,648](https://solscan.io/tx/4mxW8D5zpY8t4fL8JRbvhp6ejU6CUvB3iWmFjACipzexW6tZfFeatfnEnDTX3Y97BxsvAftoX9eQauiVu84xrLxh) |
+| refund_offer (offer 2) | [**5,961**](https://solscan.io/tx/4kY7s3y95Lrd2WGCWGPWW3zFBVtEKH6EskdscuYmRCRRgPt2rJTZ1CmZMGUUkHs7aai9AygEiTSUG23EMUrFr7rg) | [13,387](https://solscan.io/tx/QUXWwdbKRcT6WhZvSe4U8nxr4GAMaPNV6pZ1fwrC28kRxdJm7HKXVr2DFRuKD9bEzoS6hFdiA2rLr1mQWyrN3oz) | [17,731](https://solscan.io/tx/5zj7E4c61j1JzUsUPC1fNs9ECFLVmCug9rsdYsVLn7YD1RSxdbAJUQDam1BX3epTzW6ed2uFGwTiNhwaYo7vqdwm) | [23,576](https://solscan.io/tx/5Kjwnq5tN8mzj5s67VGxSry4kRzZk6HLdgXW65FyTvpUeC1D7aQoDGTwzrA7kqyYEvV9y9znnZmLaqU98zFrJJo4) |
+| program | [65ybkcg6…](https://solscan.io/account/65ybkcg6mQa9t5EuHtirRdvf2qAu12qRiK6wYBbGk16P) | [FrQwq3iU…](https://solscan.io/account/FrQwq3iUa8ZkWEne1y27webXTAyLgH4Hj6t986t6VS2G) | [5pnmi1Md…](https://solscan.io/account/5pnmi1MdxzXKmgX7ooRSE212rzZK8rb7nNpRTSMqP8V1) | [EG7M3sLL…](https://solscan.io/account/EG7M3sLLwB7MhmtzwYsaxbhZaFDbshL9hmVK79bQVyVq) |
+
+Most of make_offer is the Associated Token Account program creating the vault (about 13,500 CU in every version); it
+searches for the vault address's bump itself at 1,500 CU a try, which is why TypeSOL's offer 2 cost 1,500 more than
+offer 1 (its own part was 6,719 CU both times). The Pinocchio version takes the offer PDA's bump from the client instead
+of searching for it (its own part: 6,051 CU). Mainnet figures differ from the LiteSVM means above.
+
 ## How it is tested
 
 - **Execution tests.** Every feature is compiled and run in LiteSVM.
@@ -276,7 +306,7 @@ Details are in [docs/testing.md](docs/testing.md).
 
 ## Status
 
-**TypeSOL is pre-1.0 (0.14).** Releases follow the organization's
+**TypeSOL is pre-1.0 (0.16).** 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,12 +5,15 @@ 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";
 import { formatProfile, profileLogs } from "./profile.js";
+import { TEMPLATE_NAMES } from "./templates.js";
 import { buildWorkspace, CONFIG, deployArgs, findWorkspace, programAddress, programForEntry, programPaths, scaffold } from "./workspace.js";
 const ASSETS = fileURLToPath(new URL("../assets/", import.meta.url));
 /** A usage problem: printed with the command's help, exit code 2. */
@@ -38,14 +41,23 @@ function banner() {
 const SBPF = `--sbpf v0|v1|v2      SBPF version (default v0, or "sbpf" in ${CONFIG}); v1/v2 need clusters that enabled them`;
 const COMMANDS = {
     init: {
-        usage: "typesol init [<dir>] [--name <program>]",
-        help: "Create a project: typesol.json, programs/<name>.ts, tests/<name>.test.ts (LiteSVM), package.json, tsconfig.json, .gitignore.\n  Refuses to overwrite files. <name> must be snake_case (default: derived from <dir>).",
-        options: { name: { type: "string" } },
+        usage: "typesol init [<dir>] [--name <program>] [--template counter|vault|escrow]",
+        help: [
+            "Create a project: typesol.json, programs/<name>.ts, tests/<name>.test.ts (LiteSVM), package.json, tsconfig.json, .gitignore.",
+            "Refuses to overwrite files. <name> must be snake_case (default: derived from <dir>).",
+            "--template counter   a PDA counter per user (default)",
+            "--template vault     a SOL vault at a PDA: deposit, withdraw above rent, close",
+            "--template escrow    an SPL token escrow: make, take, refund, with the offer PDA signing for its vault",
+        ].join("\n  "),
+        options: { name: { type: "string" }, template: { type: "string" } },
         run(v, args) {
             if (args.length > 1)
                 throw new UsageError("init takes at most one directory");
             if (v.name !== undefined && !/^[a-z][a-z0-9_]*$/.test(v.name))
                 throw new UsageError(`--name "${v.name}" must be snake_case (a-z, 0-9, _; starting with a letter)`);
+            const template = v.template ?? "counter";
+            if (!TEMPLATE_NAMES.includes(template))
+                throw new UsageError(`--template "${template}" is not one of ${TEMPLATE_NAMES.join(", ")}`);
             const root = path.resolve(args[0] ?? ".");
             const derived = path
                 .basename(root)
@@ -53,7 +65,7 @@ const COMMANDS = {
                 .replace(/^_+|_+$/g, "")
                 .toLowerCase();
             const name = v.name ?? (/^[a-z]/.test(derived) ? derived : `p_${derived || "program"}`);
-            for (const f of scaffold(root, name))
+            for (const f of scaffold(root, name, template))
                 log(`  created ${path.join(root, f)}`);
             log(`\n  next: cd ${path.relative(process.cwd(), root) || "."} && npm install && npm test`);
             return 0;
@@ -110,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": {
@@ -185,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);
@@ -218,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.",
@@ -239,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: {
@@ -346,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/compiler/analyze.d.ts

@@ -2,8 +2,12 @@ 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";
 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;

package/dist/compiler/analyze.js

@@ -17,7 +17,7 @@ const C_RESERVED = new Set([
     ..."NULL SUCCESS HEAP_LENGTH HEAP_START_ADDRESS MAX_PERMITTED_DATA_INCREASE MAX_RETURN_DATA MAX_SEED_LENGTH_EXCEEDED INVALID_SEEDS SIZE_PUBKEY memcpy memset strlen static_assert offsetof sol_log_64".split(" "),
 ]);
 /** Why a name cannot be used as a C member, or undefined when it can. */
-function cNameProblem(name) {
+export function cNameProblem(name) {
     if (name.includes("__") || name.startsWith("_"))
         return `"${name}": names starting with "_" or containing "__" are reserved for generated code`;
     if (name.includes("$"))
@@ -94,6 +94,8 @@ const MAX_ARRAY_LEN = 1_000_000;
 const MAX_STRING_CAP = 10_240;
 /** Solana's account size limit, and what a program can allocate itself through a CPI (Init<T>). */
 export const MAX_ACCOUNT_SIZE = 10 * 1024 * 1024;
+/** sol_set_return_data's limit. */
+export const MAX_RETURN_DATA = 1024;
 export const MAX_CPI_ALLOCATION = 10 * 1024;
 export function snakeCase(name) {
     return name
@@ -388,6 +390,9 @@ export function analyze(entry) {
         instructions.push(ix);
         for (const a of ix.args)
             collectStructs(a.type, structs, dataEnums, argStructs);
+        // A returned struct goes out in its fixed layout, like an argument comes in: it cannot also be a Borsh event.
+        if (ix.returns?.kind === "struct")
+            collectStructs(ix.returns, structs, dataEnums, argStructs);
         for (const a of ix.accounts)
             if (a.kind.kind === "account" || a.kind.kind === "init" || a.kind.kind === "zeroed" || a.kind.kind === "initIfNeeded")
                 accountStructs.add(a.kind.struct.name);
@@ -696,8 +701,8 @@ function analyzeStructs(items, aliases, dataEnums, reporter, scopeFor, fstrings)
                     if (problem)
                         reporter.fail(p.name, problem);
                     const t = fieldType(p.type);
-                    if (t.kind === "string" || t.kind === "vec")
-                        reporter.fail(p.type, "variant fields must have a fixed size (use FixedString<N>)");
+                    if (t.kind === "vec")
+                        reporter.fail(p.type, "variant fields must have a fixed size (a Vec cannot be one; use FixedArray<T, N>)");
                     fields.push({ name: p.name.text, type: t });
                 }
                 if (!vname || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(vname))
@@ -734,11 +739,31 @@ function analyzeStructs(items, aliases, dataEnums, reporter, scopeFor, fstrings)
                     reporter.fail(at, `data enum ${e.name} contains itself`);
                 if (state.get(`enum:${e.name}`) !== "done") {
                     state.set(`enum:${e.name}`, "visiting");
+                    // A string field is a TS_Str view (16 bytes) in the C payload and makes the enum variable-size.
+                    const fieldSize = (f) => {
+                        if (f.kind === "string") {
+                            e.variable = true;
+                            return 16;
+                        }
+                        if (f.kind === "dataEnum") {
+                            const inner = dataEnums.get(f.name);
+                            const size = sizeOf(f, e.node);
+                            if (inner?.variable) {
+                                e.variable = true;
+                                return 1 + inner.payload;
+                            }
+                            return size;
+                        }
+                        return sizeOf(f, e.node);
+                    };
                     for (const v of e.variants)
-                        v.size = v.fields.reduce((sum, f) => sum + sizeOf(f.type, e.node), 0);
+                        v.size = v.fields.reduce((sum, f) => sum + fieldSize(f.type), 0);
                     e.payload = Math.max(0, ...e.variants.map((v) => v.size));
                     state.set(`enum:${e.name}`, "done");
                 }
+                // Variable enums have no fixed layout: a struct holding one is event-only, like one holding a string.
+                if (e.variable)
+                    return undefined;
                 return 1 + e.payload;
             }
             case "vec":
@@ -801,10 +826,16 @@ function analyzeHelper(fn, reporter, scope, structs) {
     if (fn.typeParameters?.length || fn.asteriskToken)
         reporter.fail(fn, "helper functions cannot be generic or generators");
     if (!fn.type)
-        reporter.fail(fn.name, "helper functions need an explicit return type (void, an integer, boolean or Pubkey)");
-    const returns = fn.type.kind === ts.SyntaxKind.VoidKeyword ? undefined : resolveScalarType(fn.type, scope);
-    if (fn.type.kind !== ts.SyntaxKind.VoidKeyword && !returns)
-        reporter.fail(fn.type, "helpers return void, an integer, boolean or Pubkey");
+        reporter.fail(fn.name, "helper functions need an explicit return type (void, an integer, boolean, Pubkey or a struct)");
+    let returns = fn.type.kind === ts.SyntaxKind.VoidKeyword ? undefined : resolveScalarType(fn.type, scope);
+    if (fn.type.kind !== ts.SyntaxKind.VoidKeyword && !returns) {
+        const s = ts.isTypeReferenceNode(fn.type) && ts.isIdentifier(fn.type.typeName) && !fn.type.typeArguments ? structs.get(fn.type.typeName.text) : undefined;
+        if (s && (s.size === undefined || s.vec))
+            reporter.fail(fn.type, `${s.name} has variable-size fields and cannot be returned; return a struct of fixed size`);
+        if (!s)
+            reporter.fail(fn.type, "helpers return void, an integer, boolean, Pubkey or a struct");
+        returns = { kind: "struct", name: s.name };
+    }
     const params = fn.parameters.map((p) => {
         if (!ts.isIdentifier(p.name) || !p.type || p.initializer || p.questionToken || p.dotDotDotToken)
             reporter.fail(p, "parameters need a plain name and an explicit type");
@@ -865,8 +896,19 @@ function analyzeInstruction(fn, reporter, scope, structs) {
     let returns;
     if (fn.type && fn.type.kind !== ts.SyntaxKind.VoidKeyword) {
         returns = resolveScalarType(fn.type, scope);
+        const s = !returns && ts.isTypeReferenceNode(fn.type) && ts.isIdentifier(fn.type.typeName) && !fn.type.typeArguments
+            ? structs.get(fn.type.typeName.text)
+            : undefined;
+        if (s) {
+            if (s.size === undefined || s.vec)
+                reporter.fail(fn.type, `${s.name} has variable-size fields and cannot be return data`);
+            // The runtime caps return data at 1024 bytes.
+            if (s.size > MAX_RETURN_DATA)
+                reporter.fail(fn.type, `${s.name} is ${s.size} bytes; return data holds at most ${MAX_RETURN_DATA}`);
+            returns = { kind: "struct", name: s.name };
+        }
         if (!returns)
-            reporter.fail(fn.type, "instructions return void or one integer, boolean or Pubkey (sent as return data)");
+            reporter.fail(fn.type, "instructions return void, one integer, boolean or Pubkey, or a fixed-size struct (sent as return data)");
     }
     const accounts = [];
     const args = [];

package/dist/compiler/emit/base.js

@@ -136,7 +136,7 @@ export class EmitterBase {
         if ((ts.isPropertyAccessExpression(node) || ts.isCallExpression(node) || ts.isElementAccessExpression(node)) && node.questionDotToken)
             this.fail(node, "optional chaining (?.) is not supported; check `x !== null` first");
         if (ts.isNonNullExpression(node))
-            this.fail(node, "the ! assertion is not supported; check `x !== null` so TypeScript narrows it");
+            this.fail(node, "the ! assertion works on Option values only; check `x !== null` so TypeScript narrows it");
     }
     lookup(name) {
         for (let i = this.scopes.length - 1; i >= 0; i--) {

package/dist/compiler/emit/calls.js

@@ -905,6 +905,13 @@ export class CallEmitter extends ExpressionEmitter {
             return undefined;
         }
         const t = this.tmp();
+        if (h.returns.kind === "struct") {
+            // The result lives in a local the caller owns: a reference to it reads and copies like any struct. Declared at
+            // the top of the function, so a reference taken inside a block (a ternary's branch) stays valid after it.
+            this.hoisted.push(`  TSS_${h.returns.name} ${t};`);
+            this.line(`TS_TRY(fn_${h.name}(${[...args, `&${t}`].join(", ")}));`);
+            return { c: `(&${t})`, type: { kind: "structRef", struct: h.returns.name, writable: true } };
+        }
         this.line(`${scalarC(h.returns)} ${t};`);
         this.line(`TS_TRY(fn_${h.name}(${[...args, `&${t}`].join(", ")}));`);
         return h.returns.kind === "pubkey" ? { c: `(&${t})`, type: h.returns } : { c: t, type: h.returns };