@typesol/cli 0.15.0 → 0.16.0

package/CHANGELOG.md

@@ -5,6 +5,67 @@ 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

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
 
@@ -190,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 |
@@ -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.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,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/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 };