@typesol/cli 0.15.0 → 0.17.0

package/dist/testing.d.ts

@@ -0,0 +1,66 @@
+/**
+ * `typesol/testing`: test a project's program in LiteSVM (an in-process Solana runtime) without the boilerplate.
+ *
+ *   const t = await testProgram("counter", import.meta.url);
+ *   const alice = await t.wallet();
+ *   const counter = await t.pda("counter", alice);
+ *   t.ok(await t.send(alice, t.ix("initialize", {}, { authority: alice, counter })));
+ *   t.ok(await t.send(alice, t.ix("increment", { by: 5n }, { authority: alice, counter })));
+ *   expect((await t.account("Counter", counter))?.count).toBe(5n);
+ *
+ * Accounts are passed by name; their signer / writable flags and fixed addresses (system program, token programs…)
+ * come from the IDL, as Anchor's `.accounts({...})` does, and PDAs seeded by constants, arguments or other accounts'
+ * keys are derived when left out. Arguments take plain values: bigints or numbers for
+ * integers, address strings for Pubkeys, null for an empty Option. Decoded accounts and return data come back the
+ * same way (bigints, address strings).
+ *
+ * Needs `litesvm` and `@anchor-lang/core`, which `typesol init` projects have.
+ */
+import anchor, { type Idl } from "@anchor-lang/core";
+import { type Address, type Instruction, type KeyPairSigner } from "@solana/kit";
+import { FailedTransactionMetadata, LiteSVM, TransactionMetadata } from "litesvm";
+declare const BorshCoder: typeof anchor.BorshCoder;
+type BorshCoder = InstanceType<typeof BorshCoder>;
+export type Result = TransactionMetadata | FailedTransactionMetadata;
+/** An account for an instruction: an address, a keypair (which then signs), or null to leave an optional one out. */
+export type AccountInput = Address | KeyPairSigner | null;
+/**
+ * A PDA seed: text, an address (or keypair), raw bytes, or a bigint as a little-endian u64. A string that is a valid
+ * address is taken as one; pass `new TextEncoder().encode(s)` for text that happens to look like an address.
+ */
+export type SeedInput = string | Address | KeyPairSigner | Uint8Array | bigint;
+export interface TestProgram {
+    svm: LiteSVM;
+    programId: Address;
+    idl: Idl;
+    coder: BorshCoder;
+    /** A new keypair funded with `sol` SOL (default 10). */
+    wallet(sol?: number): Promise<KeyPairSigner>;
+    /** The program's PDA for these seeds. */
+    pda(...seeds: SeedInput[]): Promise<Address>;
+    /** The PDA and its bump. */
+    pdaWithBump(...seeds: SeedInput[]): Promise<[Address, number]>;
+    /** An instruction of this program, accounts by name (`authority` or `authority`'s snake_case), args as plain values. */
+    ix(name: string, args?: Record<string, unknown>, accounts?: Record<string, AccountInput>, remaining?: {
+        address: Address;
+        writable?: boolean;
+        signer?: KeyPairSigner;
+    }[]): Instruction;
+    /** Send instructions in one transaction paid by `payer` (keypairs passed as accounts sign too). */
+    send(payer: KeyPairSigner, ...ixs: Instruction[]): Promise<Result>;
+    /** The successful result, or a thrown error with the program's logs. */
+    ok(res: Result): TransactionMetadata;
+    /** The custom error code of a failed transaction (6000+ for the program's error enums); throws if it succeeded. */
+    errorCode(res: Result): number;
+    /** An account of this program decoded by its IDL type, or null when it does not exist. */
+    account<T = Record<string, unknown>>(type: string, address: Address): Promise<T | null>;
+    /** A successful instruction's return data, decoded by its IDL `returns` type. */
+    returned<T = unknown>(instruction: string, res: Result): T;
+    /** Lamports of any account (0 when it does not exist). */
+    balance(address: Address): bigint;
+}
+/** Build `program` of the project around `from` (a file URL such as import.meta.url, or a directory) and load it. */
+export declare function testProgram(program: string, from: string | URL): Promise<TestProgram>;
+/** The same helpers for a program already loaded into `svm` at `programId` with this IDL. */
+export declare function programHarness(svm: LiteSVM, programId: Address, idl: Idl): TestProgram;
+export {};

package/dist/testing.js

@@ -0,0 +1,337 @@
+/**
+ * `typesol/testing`: test a project's program in LiteSVM (an in-process Solana runtime) without the boilerplate.
+ *
+ *   const t = await testProgram("counter", import.meta.url);
+ *   const alice = await t.wallet();
+ *   const counter = await t.pda("counter", alice);
+ *   t.ok(await t.send(alice, t.ix("initialize", {}, { authority: alice, counter })));
+ *   t.ok(await t.send(alice, t.ix("increment", { by: 5n }, { authority: alice, counter })));
+ *   expect((await t.account("Counter", counter))?.count).toBe(5n);
+ *
+ * Accounts are passed by name; their signer / writable flags and fixed addresses (system program, token programs…)
+ * come from the IDL, as Anchor's `.accounts({...})` does, and PDAs seeded by constants, arguments or other accounts'
+ * keys are derived when left out. Arguments take plain values: bigints or numbers for
+ * integers, address strings for Pubkeys, null for an empty Option. Decoded accounts and return data come back the
+ * same way (bigints, address strings).
+ *
+ * Needs `litesvm` and `@anchor-lang/core`, which `typesol init` projects have.
+ */
+import anchor from "@anchor-lang/core";
+import { AccountRole, appendTransactionMessageInstructions, createTransactionMessage, generateKeyPairSigner, getAddressDecoder, getAddressEncoder, getProgramDerivedAddress, isAddress, isOffCurveAddress, lamports, pipe, setTransactionMessageFeePayerSigner, signTransactionMessageWithSigners, } from "@solana/kit";
+import { FailedTransactionMetadata, LiteSVM } from "litesvm";
+import { createHash } from "node:crypto";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { buildWorkspace, findWorkspace } from "./workspace.js";
+// @anchor-lang/core is CommonJS: Node 22 cannot import its classes by name from an installed ES module.
+const { BN, BorshCoder } = anchor;
+const BIG = new Set(["u64", "i64", "u128", "i128"]);
+const snake = (s) => s.replace(/([a-z0-9])([A-Z])/g, "$1_$2").toLowerCase();
+const camel = (s) => s.replace(/_([a-z0-9])/g, (_, c) => c.toUpperCase());
+const isSigner = (v) => typeof v === "object" && v !== null && "address" in v && "signTransactions" in v;
+/** Build `program` of the project around `from` (a file URL such as import.meta.url, or a directory) and load it. */
+export async function testProgram(program, from) {
+    const start = typeof from === "string" && !from.startsWith("file:") ? from : path.dirname(fileURLToPath(from));
+    const ws = findWorkspace(start);
+    if (!ws)
+        throw new Error(`no typesol.json at or above ${start}`);
+    if (!ws.programs[program])
+        throw new Error(`typesol.json has no program "${program}" (it has ${Object.keys(ws.programs).join(", ")})`);
+    const [built] = buildWorkspace(ws, [program]);
+    const svm = new LiteSVM();
+    const programId = built.address;
+    svm.addProgramFromFile(programId, built.result.soPath);
+    return programHarness(svm, programId, built.result.idl);
+}
+/** The same helpers for a program already loaded into `svm` at `programId` with this IDL. */
+export function programHarness(svm, programId, idl) {
+    const coder = new BorshCoder(idl);
+    const pidl = idl;
+    const types = new Map((pidl.types ?? []).map((t) => [t.name, t]));
+    const enc = getAddressEncoder();
+    /** A plain value → what the Anchor coder expects for `type`. */
+    const toCoder = (v, type, where) => {
+        if (typeof type === "string") {
+            if (BIG.has(type))
+                return new BN(String(v));
+            if (/^[ui](8|16|32)$/.test(type))
+                return Number(v);
+            if (type === "pubkey") {
+                const a = isSigner(v) ? v.address : v;
+                if (typeof a !== "string" || !isAddress(a))
+                    throw new Error(`${where}: expected an address`);
+                return { toBuffer: () => Buffer.from(enc.encode(a)) };
+            }
+            return v;
+        }
+        if ("option" in type)
+            return v === null || v === undefined ? null : toCoder(v, type.option, where);
+        if ("vec" in type)
+            return v.map((x, i) => toCoder(x, type.vec, `${where}[${i}]`));
+        if ("array" in type)
+            return v.map((x, i) => toCoder(x, type.array[0], `${where}[${i}]`));
+        const def = types.get(type.defined.name);
+        if (def?.type.kind === "struct" && def.type.fields && typeof v === "object" && v !== null) {
+            const o = v;
+            return Object.fromEntries(def.type.fields.map((f) => [f.name, toCoder(o[f.name] ?? o[camel(f.name)], f.type, `${where}.${f.name}`)]));
+        }
+        // A unit enum as its index or variant name, as well as Anchor's { Variant: {} }.
+        const variants = def?.type?.variants;
+        const unitObject = typeof v === "object" && v !== null && Object.keys(v).length === 1 && !Object.values(v)[0];
+        const emptyObject = typeof v === "object" && v !== null && Object.keys(v).length === 1 && Object.keys(Object.values(v)[0]).length === 0;
+        if (def?.type.kind === "enum" && variants && (typeof v === "number" || typeof v === "bigint" || typeof v === "string" || unitObject || emptyObject)) {
+            const key = typeof v === "object" ? Object.keys(v)[0] : v;
+            const same = (x) => x.name === key || camel(x.name) === key || x.name.toLowerCase() === String(key).toLowerCase();
+            const i = typeof key === "string" ? variants.findIndex(same) : Number(key);
+            if (!variants[i])
+                throw new Error(`${where}: ${String(v)} is not a variant of ${type.defined.name}`);
+            return { [variants[i].name]: {} };
+        }
+        // A variant with fields, { Variant: { field: value } }: its fields converted like a struct's.
+        if (def?.type.kind === "enum" && variants && typeof v === "object" && v !== null && Object.keys(v).length === 1) {
+            const [key, body] = Object.entries(v)[0];
+            const variant = variants.find((x) => x.name === key || camel(x.name) === key || x.name.toLowerCase() === key.toLowerCase());
+            if (!variant)
+                throw new Error(`${where}: ${key} is not a variant of ${type.defined.name}`);
+            const fields = (variant.fields ?? []);
+            if (fields.length && fields.every((f) => typeof f === "object" && f?.name && f.type) && typeof body === "object" && body !== null) {
+                const o = body;
+                return {
+                    [variant.name]: Object.fromEntries(fields.map((f) => [f.name, toCoder(o[f.name] ?? o[camel(f.name)], f.type, `${where}.${variant.name}.${f.name}`)])),
+                };
+            }
+            return { [variant.name]: body };
+        }
+        return v;
+    };
+    /** What the coder decodes → plain values (bigints, address strings), recursively. */
+    const plain = (v) => {
+        if (v === null || v === undefined)
+            return v;
+        if (BN.isBN(v))
+            return BigInt(v.toString());
+        if (typeof v === "object" && typeof v.toBase58 === "function")
+            return v.toBase58();
+        if (Array.isArray(v))
+            return v.map(plain);
+        if (v instanceof Uint8Array)
+            return v;
+        if (typeof v === "object") {
+            const o = v;
+            const keys = Object.keys(o).sort().join(",");
+            // Account data keeps Options and FixedStrings in a fixed layout; give them back as the plain value / string.
+            if (keys === "is_some,value")
+                return o.is_some ? plain(o.value) : null;
+            if (keys === "bytes,len" && Array.isArray(o.bytes))
+                return Buffer.from(o.bytes.slice(0, Number(o.len))).toString("utf8");
+            return Object.fromEntries(Object.entries(o).map(([k, x]) => [k, plain(x)]));
+        }
+        return v;
+    };
+    /** find_program_address, synchronously (sha256 + the curve check), so ix() can fill PDAs in. */
+    const findPda = (seeds, program) => {
+        for (let bump = 255; bump >= 0; bump--) {
+            const h = createHash("sha256");
+            for (const s of seeds)
+                h.update(s);
+            h.update(Uint8Array.of(bump));
+            h.update(new Uint8Array(enc.encode(program)));
+            h.update("ProgramDerivedAddress");
+            const a = getAddressDecoder().decode(h.digest());
+            if (isOffCurveAddress(a))
+                return a;
+        }
+        throw new Error("no off-curve bump for these seeds");
+    };
+    /** An argument's bytes as a seed: little-endian integers at their width, bool as one byte, Pubkey, UTF-8 text. */
+    const argSeed = (v, type) => {
+        if (typeof type !== "string" || v === undefined || v === null)
+            return undefined;
+        const int = /^([ui])(8|16|32|64|128)$/.exec(type);
+        if (int) {
+            const bytes = Number(int[2]) / 8;
+            let n = BigInt.asUintN(bytes * 8, BigInt(v));
+            const out = new Uint8Array(bytes);
+            for (let i = 0; i < bytes; i++, n >>= 8n)
+                out[i] = Number(n & 0xffn);
+            return out;
+        }
+        if (type === "bool")
+            return Uint8Array.of(v ? 1 : 0);
+        if (type === "pubkey")
+            return new Uint8Array(enc.encode((isSigner(v) ? v.address : v)));
+        if (type === "string")
+            return new TextEncoder().encode(v);
+        return undefined;
+    };
+    /** A unit-enum argument as a seed: one byte, its variant index (given as the index or as Anchor's { Variant: {} }). */
+    const enumSeed = (v, type) => {
+        if (typeof type !== "object" || !("defined" in type) || v === undefined || v === null)
+            return undefined;
+        const def = types.get(type.defined.name);
+        const variants = def?.type.kind === "enum" ? def.type.variants : undefined;
+        if (!variants || variants.some((x) => x.fields?.length))
+            return undefined;
+        if (typeof v === "number" || typeof v === "bigint")
+            return Uint8Array.of(Number(v));
+        const name = typeof v === "object" ? Object.keys(v)[0] : String(v);
+        const i = variants.findIndex((x) => x.name === name || camel(x.name) === name || x.name.toLowerCase() === String(name).toLowerCase());
+        return i < 0 ? undefined : Uint8Array.of(i);
+    };
+    const seedBytes = (s) => {
+        if (s instanceof Uint8Array)
+            return s;
+        if (typeof s === "bigint") {
+            const b = new Uint8Array(8);
+            new DataView(b.buffer).setBigUint64(0, s, true);
+            return b;
+        }
+        if (isSigner(s))
+            return new Uint8Array(enc.encode(s.address));
+        if (isAddress(s))
+            return new Uint8Array(enc.encode(s));
+        return new TextEncoder().encode(s);
+    };
+    const harness = {
+        svm,
+        programId,
+        idl,
+        coder,
+        async wallet(sol = 10) {
+            const k = await generateKeyPairSigner();
+            svm.airdrop(k.address, lamports(BigInt(Math.round(sol * 1e9))));
+            return k;
+        },
+        async pda(...seeds) {
+            return (await harness.pdaWithBump(...seeds))[0];
+        },
+        async pdaWithBump(...seeds) {
+            const [a, bump] = await getProgramDerivedAddress({ programAddress: programId, seeds: seeds.map(seedBytes) });
+            return [a, bump];
+        },
+        ix(name, args = {}, accounts = {}, remaining = []) {
+            const def = pidl.instructions.find((i) => i.name === name || i.name === snake(name));
+            if (!def)
+                throw new Error(`the program has no instruction "${name}" (it has ${pidl.instructions.map((i) => i.name).join(", ")})`);
+            const given = new Map(Object.entries(accounts).map(([k, v]) => [snake(k), v]));
+            for (const k of given.keys())
+                if (!def.accounts.some((a) => a.name === k))
+                    throw new Error(`${def.name} has no account "${k}"`);
+            const argsIn = args;
+            // PDAs whose seeds are constants, arguments or other accounts' keys are filled in, as the generated client does.
+            const addressOf = (name) => {
+                const v = given.get(name);
+                if (v === undefined || v === null)
+                    return def.accounts.find((x) => x.name === name)?.address; // fixed in the IDL
+                return isSigner(v) ? v.address : v;
+            };
+            for (let progress = true; progress;) {
+                progress = false;
+                for (const a of def.accounts) {
+                    if (given.has(a.name) || !a.pda || a.address)
+                        continue;
+                    const seed = (s) => {
+                        if (s.kind === "const")
+                            return Uint8Array.from(s.value);
+                        if (s.kind === "account") {
+                            const at = s.path.includes(".") ? undefined : addressOf(s.path);
+                            return at && new Uint8Array(enc.encode(at));
+                        }
+                        const arg = def.args.find((x) => x.name === s.path);
+                        const value = arg && (argsIn[arg.name] ?? argsIn[camel(arg.name)]);
+                        return arg && (argSeed(value, arg.type) ?? enumSeed(value, arg.type));
+                    };
+                    const seeds = a.pda.seeds.map(seed);
+                    const program = a.pda.program ? seed(a.pda.program) : new Uint8Array(enc.encode(programId));
+                    if (seeds.some((x) => x === undefined) || !program || program.length !== 32)
+                        continue;
+                    given.set(a.name, findPda(seeds, getAddressDecoder().decode(program)));
+                    progress = true;
+                }
+            }
+            const metas = def.accounts.map((a) => {
+                let v = given.has(a.name) ? given.get(a.name) : undefined;
+                if (v === undefined && a.address)
+                    v = a.address;
+                if (v === undefined || v === null) {
+                    if (!a.optional)
+                        throw new Error(`${def.name}: account "${camel(a.name)}" is required`);
+                    return { address: programId, role: AccountRole.READONLY }; // left out: the program's own id stands in
+                }
+                if (a.signer && !isSigner(v))
+                    throw new Error(`${def.name}: account "${camel(a.name)}" signs; pass its keypair, not its address`);
+                const address = isSigner(v) ? v.address : v;
+                const role = a.signer
+                    ? a.writable
+                        ? AccountRole.WRITABLE_SIGNER
+                        : AccountRole.READONLY_SIGNER
+                    : a.writable
+                        ? AccountRole.WRITABLE
+                        : AccountRole.READONLY;
+                return { address, role, ...(isSigner(v) && a.signer ? { signer: v } : {}) };
+            });
+            for (const r of remaining)
+                metas.push({
+                    address: r.address,
+                    role: r.signer ? (r.writable ? AccountRole.WRITABLE_SIGNER : AccountRole.READONLY_SIGNER) : r.writable ? AccountRole.WRITABLE : AccountRole.READONLY,
+                    ...(r.signer ? { signer: r.signer } : {}),
+                });
+            const a = args;
+            const encoded = Object.fromEntries(def.args.map((x) => [x.name, toCoder(a[x.name] ?? a[camel(x.name)], x.type, `${def.name}(${camel(x.name)})`)]));
+            return { programAddress: programId, accounts: metas, data: new Uint8Array(coder.instruction.encode(def.name, encoded)) };
+        },
+        async send(payer, ...ixs) {
+            const tx = await pipe(createTransactionMessage({ version: 0 }), (t) => setTransactionMessageFeePayerSigner(payer, t), (t) => svm.setTransactionMessageLifetimeUsingLatestBlockhash(t), (t) => appendTransactionMessageInstructions(ixs, t), (t) => signTransactionMessageWithSigners(t));
+            const res = svm.sendTransaction(tx);
+            svm.expireBlockhash();
+            return res;
+        },
+        ok(res) {
+            if (res instanceof FailedTransactionMetadata)
+                throw new Error(`transaction failed: ${String(res.err())}\n${res.meta().logs().join("\n")}`);
+            return res;
+        },
+        errorCode(res) {
+            if (!(res instanceof FailedTransactionMetadata))
+                throw new Error("expected the transaction to fail, but it succeeded");
+            const m = /Custom\D*(\d+)/.exec(String(res.err()));
+            if (!m)
+                throw new Error(`not a custom program error: ${String(res.err())}\n${res.meta().logs().join("\n")}`);
+            return Number(m[1]);
+        },
+        async account(type, address) {
+            const a = svm.getAccount(address);
+            if (!a.exists)
+                return null;
+            return plain(coder.accounts.decode(type, Buffer.from(a.data)));
+        },
+        returned(instruction, res) {
+            const def = pidl.instructions.find((i) => i.name === instruction || i.name === snake(instruction));
+            if (!def?.returns)
+                throw new Error(`${instruction} returns nothing`);
+            const data = Buffer.from(harness.ok(res).returnData().data());
+            const t = def.returns;
+            if (typeof t === "string") {
+                if (t === "pubkey")
+                    return getAddressDecoder().decode(data);
+                if (t === "bool")
+                    return (data[0] !== 0);
+                const signed = t.startsWith("i");
+                const bytes = Number(t.slice(1)) / 8;
+                let n = 0n;
+                for (let i = bytes - 1; i >= 0; i--)
+                    n = (n << 8n) | BigInt(data[i]);
+                if (signed && n >= 1n << BigInt(bytes * 8 - 1))
+                    n -= 1n << BigInt(bytes * 8);
+                return (bytes <= 4 ? Number(n) : n);
+            }
+            if ("defined" in t)
+                return plain(coder.types.decode(t.defined.name, data));
+            throw new Error(`decode ${instruction}'s return data yourself (${JSON.stringify(t)})`);
+        },
+        balance(address) {
+            return svm.getBalance(address) ?? 0n;
+        },
+    };
+    return harness;
+}

package/dist/workspace.js

@@ -114,7 +114,17 @@ export function scaffold(dir, name, template = "counter") {
         [CONFIG]: JSON.stringify({ programs: { [name]: { path: `programs/${name}.ts` } }, out: "target", sbpf: "v0" }, null, 2) + "\n",
         [`programs/${name}.ts`]: t.program,
         "programs/tsconfig.json": JSON.stringify({
-            compilerOptions: { target: "ES2022", module: "ESNext", moduleResolution: "Bundler", strict: true, noEmit: true, types: [], lib: ["ES2022"] },
+            compilerOptions: {
+                target: "ES2022",
+                module: "ESNext",
+                moduleResolution: "Bundler",
+                strict: true,
+                noEmit: true,
+                types: [],
+                lib: ["ES2022"],
+                // TypeSOL's own errors in the editor (with the workspace's TypeScript; see docs/cli.md).
+                plugins: [{ name: "typesol/ts-plugin" }],
+            },
             include: ["**/*.ts"],
         }, null, 2) + "\n",
         [`tests/${name}.test.ts`]: t.test(name),

package/docs/architecture.md

@@ -39,6 +39,9 @@ program.so + program.build.json (manifest: versions, sha256 of sources and binar
 | `src/cpigen.ts` | `typesol cpi`: reads an Anchor IDL and writes typed TypeSOL CPI helpers. |
 | `src/clientgen.ts` | The TypeScript client (`<name>.client.ts`, [client.md](client.md)): reads an IDL, validates it (it may come from anywhere), and writes one `@solana/kit` file. Not part of the compiler core: `workspace.ts` and the CLI write it after `build()`, and `typesol client` writes it for any IDL. |
 | `src/idlpublish.ts` | `typesol idl publish` through the Program Metadata program. |
+| `ts-plugin/index.js` | `typesol/ts-plugin` (CommonJS, loaded by tsserver): runs `typesol check --json --stdin` on program entries and adds the diagnostics. |
+| `src/testing.ts` | `typesol/testing`: LiteSVM test helpers for projects (accounts by name from the IDL, plain values). |
+| `src/onchain.ts` | `typesol verify --address`: a deployed program's ELF, authority and deploy slot under loader v2, v3 or v4. |
 | `src/profile.ts` | Turns `--profile` logs into compute units per source line. |
 | `src/cli.ts` | Command parsing. Every command has strict options, `--help`, and exit codes 0 (success), 1 (failure), 2 (usage error) and 3 (verify mismatch). |
 

package/docs/cli.md

@@ -9,13 +9,14 @@ error. Exit codes: **0** success, **1** failure (compile errors, failed deploy,
 | `typesol init [<dir>] [--name <program>] [--template counter\|vault\|escrow]` | Create a project: `typesol.json`, `programs/<name>.ts`, `tests/<name>.test.ts` (LiteSVM), `package.json`, `tsconfig.json`. The template picks the program and its test: `counter` (default, a PDA counter per user), `vault` (SOL at a PDA: deposit, withdraw above rent, close) or `escrow` (SPL tokens: make, take, refund, the offer PDA signing for its vault). Refuses to overwrite files. |
 | `typesol build [<program>…] [--sbpf v0\|v1\|v2] [--profile] [--quiet]` | In a project: build every program (or those named) into `<out>/<name>/`: `<name>.so`, `<name>.json` (Anchor IDL), `<name>.client.ts` (TypeScript client, see [client.md](client.md)), `<name>.c`, `<name>.build.json`. The first build creates `<out>/deploy/<name>-keypair.json` and records the address in `typesol.json`; later builds refuse a missing or different keypair. |
 | `typesol build <file.ts> [--out <dir>] [--program-id <keypair.json>] [--sbpf …] [--profile]` | Outside a project (or a file that is not one of its programs): build that file. A project program's `.ts` builds as that program. |
-| `typesol check <file.ts>` | Type-check and validate without building. |
+| `typesol check <file.ts> [--json] [--stdin]` | Type-check and validate without building. `--json` prints `{ ok, diagnostics: [{ file, line, column, message }] }`; `--stdin` checks the text given on stdin as that file (its imports come from disk). |
 | `typesol emit-c <file.ts> [--out <file.c>] [--profile]` | Print or write the generated C. |
 | `typesol deploy [<program>…] [--url <rpc>] [--keypair <payer.json>] [--config <cli config>] [--dry-run] [--sbpf …]` | Build, then `solana program deploy --use-rpc` at the program keypair's address. Deploying again upgrades (the payer must be the upgrade authority). `--dry-run` builds and prints the commands. Needs `solana` on PATH. |
 | `typesol idl publish [<program>…] [--url <rpc>] [--keypair <authority.json>] [--config <cli config>] [--non-canonical]` | Compile (the binary is not rebuilt), then write each IDL to the Program Metadata program (seed `idl`). Canonical IDLs must be signed by the upgrade authority. Defaults come from the Solana CLI config (`~/.config/solana/cli/config.yml`). |
 | `typesol cpi <idl.json> [--out <file.ts>] [--prefix <name>] [--address <base58>]` | Generate TypeSOL helpers that call another program from its IDL. Unsupported instructions are listed on stderr. |
+| `typesol port <idl.json> [--out <file.ts>]` | A TypeSOL program skeleton from an Anchor IDL (0.30+/1.x), to port an Anchor program: account structs, enums, errors and one function per instruction with its accounts and arguments, each body `require(false, …NotPorted)` until written. Instruction discriminators (an explicit `@discriminator` when the name derives another), account names and error codes are kept, so existing clients keep working where the layouts match; notes on stderr list where they do not (Borsh `String`/`Option` in account data, a `Vec` that is not the last field, custom discriminators or error codes). |
 | `typesol client <idl.json> [--out <file.ts>] [--address <base58>]` | Generate a typed TypeScript client on `@solana/kit` from an Anchor IDL (0.30+/1.x or TypeSOL); the IDL is validated first, and what the client leaves out is printed as notes. See [client.md](client.md). |
-| `typesol verify <program\|file.ts> <deployed.so> [--sbpf …]` | Rebuild and compare with a deployed binary (`solana program dump`); trailing zero padding is ignored; the SBPF version is read from the deployed ELF unless `--sbpf` is given. |
+| `typesol verify <program\|file.ts> [<deployed.so>] [--address <program id>] [--url <rpc>] [--config <cli config>] [--sbpf …]` | Rebuild and compare with what is deployed. Without a `.so`, reads the program from the cluster (`--url`, cluster monikers such as `mainnet-beta` included, else the Solana CLI config) at `--address` or the address `typesol.json` records, under any loader (v2, upgradeable v3, v4); prints the upgrade authority (or that the program is immutable) and the last deploy slot, and compares the IDL published with `typesol idl publish` (a published IDL that differs is a mismatch). With a `.so` (e.g. `solana program dump`), compares with that file. Trailing zero padding is ignored; the SBPF version is read from the deployed ELF unless `--sbpf` is given. |
 | `typesol profile <logs.txt\|-> [--program <id>]` | Compute units per TypeScript line from the logs of a `--profile` build's transaction (exit 1 when the logs have no markers). |
 | `typesol help <command>` | Same as `typesol <command> --help`. |
 | `typesol --version` | Print the version. |
@@ -32,3 +33,16 @@ error. Exit codes: **0** success, **1** failure (compile errors, failed deploy,
 
 `"programs": { "vault": "programs/vault.ts" }` (a plain path) is accepted too. Keep `target/deploy/*-keypair.json`
 safe and out of git: it is each program's address and its first upgrade authority must not lose it.
+
+## Editor
+
+`typesol init` projects load `typesol/ts-plugin` from `programs/tsconfig.json`: besides TypeScript's errors, the editor
+shows what the TypeSOL compiler refuses (an unsupported construct, a constraint that cannot hold…) at its line, for the
+text being edited, once TypeScript itself has nothing to report. It checks the program entries listed in
+`typesol.json`. Editors load tsconfig plugins from the project's own TypeScript: in VS Code, run "TypeScript: Select
+TypeScript Version" → "Use Workspace Version". To add it to an existing project:
+
+```json
+{ "compilerOptions": { "plugins": [{ "name": "typesol/ts-plugin" }] } }
+```
+

package/docs/errors.md

@@ -15,7 +15,8 @@ Framework errors use Anchor's numbers where Anchor has the same check, so client
 | 2040 | the same account passed in two writable slots (ConstraintDuplicateMutableAccount) |
 | 3000 | account already exists / initialized (AccountDiscriminatorAlreadySet) |
 | 3002 | discriminator mismatch (AccountDiscriminatorMismatch) |
-| 3003 | data too small, not an initialized token account / mint, or a read past the end (AccountDidNotDeserialize) |
+| 3003 | data too small, not an initialized token account / mint, a read past the end, or a `@layout borsh` account whose bytes are not a valid Borsh value (AccountDidNotDeserialize) |
+| 3004 | a `@layout borsh` account too small for the value it would now hold (AccountDidNotSerialize) |
 | 3005 | not enough accounts (AccountNotEnoughKeys) |
 | 3006 | account must be writable (AccountNotMutable) |
 | 3007 | wrong owner program (AccountOwnedByWrongProgram) |
@@ -26,7 +27,7 @@ Framework errors use Anchor's numbers where Anchor has the same check, so client
 | 4102 | cast overflow (InvalidNumericConversion) |
 | 5100 / 5101 | arithmetic overflow (including shifts) / division by zero |
 | 5103 | sysvar unavailable |
-| 5104 | index out of bounds (arrays, Vecs, remaining accounts, `pop()` on an empty Vec) |
+| 5104 | index out of bounds (arrays, Vecs, remaining accounts, `pop()` on an empty Vec, `push` on a full FixedVec) |
 | 5105 | string longer than the FixedString capacity |
 | 5106 | missing or mismatched return data |
 | 5107 | event larger than 1024 bytes |

package/docs/language.md

@@ -6,9 +6,9 @@ The full reference. For a tour, start with the [README](../README.md).
 
 | Concept | TypeSOL |
 | --- | --- |
-| Instruction | an exported function returning `void`, or one integer / boolean / `Pubkey` (sent as return data, `returns` in the IDL) |
+| Instruction | an exported function returning `void`, one integer / boolean / `Pubkey`, or a fixed-size struct (sent as return data, at most 1024 bytes; `returns` in the IDL, and the generated client decodes it) |
 | Account data | an exported `interface` with fixed-size fields; interfaces nest (`home: Point`, `trail: FixedArray<Point, 4>`) |
-| Integers | `u8` `u16` `u32` `u64` `u128` `i8` `i16` `i32` `i64` `i128` — bigint literals (`1n`), every `+ - * / %` checked; `& \| ^` on equal types, `~` within the width, `<<` / `>>` checked (amount below the width, `<<` may not lose bits) |
+| Integers | `u8` `u16` `u32` `u64` `u128` `i8` `i16` `i32` `i64` `i128` — bigint literals (`1n`), every `+ - * / % **` checked (`**` aborts on a negative exponent, as JS throws); `& \| ^` on equal types, `~` within the width, `<<` / `>>` checked (amount below the width, `<<` may not lose bits) |
 | Integer helpers | `mulDiv(a, b, c)` / `mulDivCeil` (u64 through a 128-bit product), `isqrt(x)` (up to u128), `min(a, b)`, `max(a, b)` |
 | Other scalars | `boolean`, `Pubkey` (compare with `===` or `.equals`) |
 | Errors | `export enum MyError { Name = "message" }` + `require(cond, MyError.Name)` → codes 6000+ |
@@ -18,12 +18,15 @@ The full reference. For a tour, start with the [README](../README.md).
 | Local arrays | `const xs = fixedArray<i64, 5>(0n)` — up to 256 elements on the stack |
 | Strings | `string` arguments and literals; `name: FixedString<32>` in account data (u32 length + 32 bytes); `===`, `byteLength(s)`, `log(s)`, `+=`, as PDA seeds; too-long writes abort (5105). A local bound to account text keeps its own copy |
 | Copies | `a.home = b.home`, `a.trail.set(0n, a.home)` copy whole structs / arrays of the same type: assignment copies (like Rust/Anchor), binding with `const` references |
+| Destructuring | `const { owner, pos: p } = acct` (or `let` for scalars to change) from a name or a field path — one declaration per name, read like `acct.owner`: scalars are copies, nested structs are references. No rest, defaults or nesting |
 | Struct values | `const p: Point = { x, y }` (or a copy of another Point) — a local struct; fields can be updated, store it with `acct.home = p` |
 | Pubkey constants | `const ADMIN = pubkey("4Nd1…")` (checked at compile time) or inline `pubkey("…")`; usable as seeds |
 | Events | `emit<Deposited>({ owner: owner.key, amount })` — Anchor-format `Program data:` logs, listed under `events` in the IDL; event structs may hold `string` and `Option` |
 | Enums | `export enum Status { Pending, Approved }` — unit variants stored as the Borsh u8 index; `Status.Approved`, `===` |
-| Options | `best: Option<u64>` (or `u64 \| null`) — `null`, `=== null`, TypeScript narrowing; `===` between options or with a value follows JS (null equals null, empty never equals a value); empty use aborts (5108); `${opt}` prints the value or `null`. Borsh `option` in arguments/events, fixed `{ is_some, value }` in account data |
+| Options | `best: Option<u64>` (or `u64 \| null`) — `null`, `=== null`, TypeScript narrowing; `===` between options or with a value follows JS (null equals null, empty never equals a value); empty use aborts (5108); `a ?? b` takes b only when a is empty (b runs only then; the result is an Option when b can be null), `x!` is the value or aborts with 5108; `${opt}` prints the value or `null`. Borsh `option` in arguments/events, fixed `{ is_some, value }` in account data |
 | Vecs | `entries: Vec<Entry>` as the last account field — `get`, `set`, `push(v, payer)`, `pop()`, `clear()`, `.length`; the account is resized (realloc) and rent topped up by `payer`; `Vec<u64>` arguments are read-only views; `pop()` of a Vec of structs works as a statement |
+| Anchor's account bytes | `/** @layout borsh */` on an account struct stores it as Anchor does (Borsh: a `FixedString<N>` is a String, a `FixedVec<T, N>` a Vec, an `Option` one byte when empty, and the fields after them move), so a TypeSOL program can take over accounts an Anchor program wrote and the IDL lists Anchor's own types. The instruction unpacks it into the usual fixed layout when it starts (bad bytes fail with 3003) and packs it back when it returns (3004 when the account is too small for the new value), so everything else works on it unchanged. Programs invoked from the body (CPIs) see the account's bytes as they were when the instruction started. Costs more compute than the fixed layout (the whole account is read and written each time; see the benchmarks); nested structs and list elements must be fixed-size (FixedString elements allowed); not for arguments, events, `Zeroed<T>`, `loadAccount` or a growable `Vec<T>` |
+| Fixed-capacity lists | `owners: FixedVec<Pubkey, 8>` — any field, any number of them, in nested structs too: a u32 length and room for N elements (always 4 + N × size bytes), the same `get`, `set`, `push(v)`, `pop()`, `clear()`, `.length` and `for … of`; `push` on a full one fails (5104); `acct.owners = fixedVec([a, b])` writes a whole one (unused slots zeroed). Account data and returned structs only: arguments use `Vec<T>` |
 | Struct arguments | `order: Order`, `ids: FixedArray<u8, 4>`, `orders: Vec<Order>` — fixed layouts, Borsh-identical, validated on entry (bools, enums, option tags, string lengths, enum tags; 102) and read-only |
 | Remaining accounts | `remainingAccounts()` — `.length`, `.get(i)` → `key`, `owner`, `lamports` (writes check writability), `isSigner`, `isWritable`; `loadAccount<T>` / `loadAccountMut<T>` give checked struct views; pass them to `invoke`, one at a time or spread: `...remainingAccounts()` (each with the flags it was passed with), `...readonly(rest)` / `...writable(rest)` (all with that role), `rest.slice(a, b)` for part of them; a CPI lists at most 32 accounts (5113) |
 | Struct literals | `book.entries.push({ who: who.key, amount, status: Status.Pending, note }, who)` — every field required |
@@ -31,15 +34,17 @@ The full reference. For a tour, start with the [README](../README.md).
 | Other programs' accounts | `const pool = loadForeign<Pool>(account, AMM_PROGRAM)` — owner, `account:Pool` discriminator and size checked (3007 / 3002 / 3003); `readData<u64>(account, offset)` for raw little-endian reads (bounds-checked, 3003) |
 | Ternaries | `const fee = vip ? 0n : 30n` — only the chosen branch runs |
 | Constants | top-level `const SEED = "vault"`, `const FEE: u16 = 30n`, `const ON = true` — inlined, usable as seeds (and described in the IDL) |
-| Data enums | `export type Action = { kind: "Deposit"; amount: u64 } \| { kind: "Pause" }` — `a.kind === "Deposit"`, `switch (a.kind)`, TypeScript narrowing picks the variant (checked again at runtime, 5112); Borsh enums in arguments/events, fixed `{ tag, payload }` in account data |
+| Data enums | `export type Action = { kind: "Deposit"; amount: u64 } \| { kind: "Pause" }` — `a.kind === "Deposit"`, `switch (a.kind)`, TypeScript narrowing picks the variant (checked again at runtime, 5112); Borsh enums in arguments/events, fixed `{ tag, payload }` in account data. A variant may hold a `string` (`{ kind: "Say"; text: string }`): such an enum works in arguments, events and locals (Borsh, as Anchor encodes it) but not in account data |
 | Option of structs | `home: Option<Point>` in account data — `=== null`, `p.home.x` after narrowing, `p.home = null` / `{ x, y }` |
 | Strings at runtime | `"hello, " + name`, `` `#${n}` `` — built on the 32 KiB heap (5110 when full) |
 | `switch` | on integers (up to 64 bits), enums and data-enum `.kind`, with JS `break` / fallthrough; case labels are literals, constants or enum members |
 | Hashing & signatures | `sha256(...)`, `keccak256(...)` → `Hash`; `findProgramAddress(seeds, program)` → the canonical PDA of any program (Rust `Pubkey::find_program_address(..).0`, e.g. a Bubblegum asset id); `merkleVerify(leaf, proof: Vec<Hash>, root)` (sorted-pair keccak, OpenZeppelin convention); `verifyEd25519(instructionsSysvar, signer, message)` checks an Ed25519 precompile instruction in the same transaction; `verifySecp256k1(keccak256(...message) | ethMessageHash(message), recoveryId, r, s, ethAddress)` (the hash must be computed in the program; a passed-in hash could be forged) |
 | Oracles | `pythPrice(update: PythPriceUpdate, feedId, maxAgeSeconds)` (fully verified, feed-matched, fresh); raw `update.price / conf / exponent / publishTime`; `switchboardValue(feed: SwitchboardFeed, expectedFeed, maxStaleSlots, decimals)` (the feed must be the expected one: anyone can create feeds) (mainnet program unless `SwitchboardFeed<"devnet">`) |
 | Multiple files | `import { Side, min } from "./math"` — structs, enums, constants and helpers can live in other files; only the entry file's exported functions are instructions; names are program-wide, so imports from TypeSOL files cannot be renamed; error codes number imported files first |
-| Loops | `for (let i = 0n; i < n; i++)`, `while`, `break`, `continue` — bounded by the compute budget |
-| Helpers | non-exported functions (and every function of an imported file): take values, structs, Vec arguments, `SignerSeeds` and accounts the instruction already checked (`Signer`, `AccountInfo`/`AccountMeta`, `Mut<T>`, token accounts, programs); return a scalar or `void`; no recursion. Helpers cannot grow Vecs (only instructions know the entry size) |
+| Loops | `for (let i = 0n; i < n; i++)`, `while`, `for (const x of list)` over a `Vec` or `FixedArray` (each `x` is what `list.get(i)` gives: a value, or a reference into account data for structs; the length is read again every step, as in JS), `break`, `continue` — bounded by the compute budget. Remaining accounts are iterated by index |
+| Helpers | non-exported functions (and every function of an imported file): take values, structs, Vec arguments, `SignerSeeds` and accounts the instruction already checked (`Signer`, `AccountInfo`/`AccountMeta`, `Mut<T>`, token accounts, programs); return `void`, a scalar or a fixed-size struct (`function at(x: u64, y: u64): Point { return { x, y }; }`: the caller gets its own copy, to bind, store with `acct.home = at(…)` / `arr.set(i, at(…))` or read as `at(…).x`); no recursion. Helpers cannot grow Vecs (only instructions know the entry size) |
+| Arrow functions | `const fee = (x: u64): u64 => x / 100n` (or `const f = function (…) {…}`) at the top level or inside a function is a helper (parameter and return types written out). A local one capturing nothing: it reads its parameters, top-level names and other functions, not the enclosing function's variables (pass them in). Functions are called, not stored or passed |
+| Generic helpers | `function max<T extends bigint>(a: T, b: T): T` — compiled once per set of types it is called with (`max(a, b)` with u64 arguments, or `max<u128>(x, 1n)` when only literals tell); a type parameter stands for an integer, boolean, Pubkey or enum. Each instance is checked like any helper; one that is never called is not compiled (TypeScript still type-checks it). Arithmetic on `T` is a `bigint` to TypeScript: `return (a + b) as T` (`as` names a type the value already has; it never converts) |
 | Evaluation order | operands and arguments are read left to right, as in JS, even when a later one changes account data (`v.length + v.pop()`) |
 | `++` `--` `+=` `-=` `*=` `/=` `%=` `&=` `\|=` `^=` `<<=` `>>=` | all checked |
 | Sysvars | `now()`, `currentSlot()`, `currentEpoch()` (clock), `minimumBalance(account)`, `rentExempt(space)` (rent) |
@@ -48,8 +53,8 @@ The full reference. For a tour, start with the [README](../README.md).
 | Events through CPI | `emitCpi<Paid>({ … }, eventAuthority, self)` with `eventAuthority: EventAuthority, self: SelfProgram` parameters — Anchor `emit_cpi!`: the event rides in a self-CPI (inner instruction), not in logs; the program accepts Anchor's event instruction (2002 / 2006 otherwise) |
 | Heap | 32 KiB by default; `const HEAP_SIZE_KIB = 64n` (32–256) lets the program use more, when clients add ComputeBudget `requestHeapFrame` |
 | Docs | JSDoc on instructions, `@param`, structs, fields and data enums becomes `docs` in the IDL |
-| Metaplex Core | `core: MplCoreProgram` — `createCollection`, `createAsset` (in a collection, PDA authorities via signerSeeds), `transferAsset`, `burnAsset` (no plugins; `null` leaves an optional account out); `coreAssetOwner(asset)`, `coreAssetCollection(asset)` |
-| Compressed NFTs | `bubblegum: BubblegumProgram` — `createTree` (client-allocated tree on SPL Account Compression), `mint` (MintV1, no collection/creators) |
+| Metaplex Core | `core: MplCoreProgram` — `createCollection`, `createAsset` (in a collection, PDA authorities via signerSeeds), `transferAsset`, `burnAsset` (`null` leaves an optional account out); plugins as a literal list after the uri (`[{ kind: "Royalties", basisPoints: 500n, creators: [{ address, percentage: 100n }] }, { kind: "PermanentFreezeDelegate", frozen: false, authority: studio.key }]`), and `addPlugin` / `updatePlugin` / `removePlugin(…, "FreezeDelegate")` with their `…CollectionPlugin` forms. Plugins: Royalties (no rule set), FreezeDelegate, BurnDelegate, TransferDelegate, UpdateDelegate, PermanentFreezeDelegate, Attributes, PermanentTransferDelegate, PermanentBurnDelegate, Edition, AddBlocker, ImmutableMetadata; `authority` is `"owner"`, `"updateAuthority"`, `"none"` or a Pubkey; `coreAssetOwner(asset)`, `coreAssetCollection(asset)` |
+| Compressed NFTs | `bubblegum: BubblegumProgram` — V1: `createTree` (client-allocated tree on SPL Account Compression), `mint` (MintV1, no collection/creators). V2 (trees on mpl-account-compression with mpl-noop): `createTreeV2`, `mintV2(…, { name, symbol, uri, sellerFeeBasisPoints, creators?, isMutable? }, { collection, authority, cpiSigner }?)` (into a Core collection that has the `BubblegumV2` plugin), `transferV2` and `burnV2` with the leaf `{ root, dataHash, creatorHash, assetDataHash?, flags?, nonce, index }` and its proof as `remainingAccounts()` / `rest.slice(a)` |
 
 ## Account parameters and the checks they emit
 
@@ -75,7 +80,7 @@ The full reference. For a tour, start with the [README](../README.md).
 | `SystemProgram`, `TokenProgram`, `Token2022Program` | exact program address |
 | `TokenInterface` | either token program |
 | `AssociatedTokenProgram` | `create` / `createIdempotent` CPIs; `associatedTokenAddress(owner, mint, tokenProgram)` |
-| `TokenMetadataProgram` | Metaplex `createV3(...)` (CreateMetadataAccountV3); `metadataAddress(mint)` |
+| `TokenMetadataProgram` | Metaplex `createV3(...)` (CreateMetadataAccountV3), optionally with `{ creators: [{ address, verified, share }], collection: mint }` after `isMutable` (1–5 creators, shares adding up to 100; only the update authority, signing, can be `verified: true`; the collection is written unverified; `isCollection: true` makes the NFT a sized collection); `createMasterEditionV3(edition, mint, updateAuthority, mintAuthority, payer, metadata, tokenProgram, systemProgram, maxSupply \| null)`; `verifyCollection(authority, metadata, collectionMint, collectionMetadata, collectionMasterEdition, systemProgram, instructionsSysvar)` (Verify with CollectionV1); `metadataAddress(mint)`, `masterEditionAddress(mint)` |
 | `InstructionsSysvar`, `PythPriceUpdate`, `SwitchboardFeed` | exact address / owner program + discriminator |
 | `Program<"Address…">` | exact program address + executable |
 | `UncheckedProgram` | executable only — check `.key` yourself |
@@ -94,7 +99,7 @@ account written through `.lamports` or `loadAccountMut` is another account of th
   `transfer`, `transferChecked(from, mint, to, authority, amount)` (required by Token-2022 mints with fees/hooks), `mintTo`, `burn`, `closeAccount`,
   `approve(source, delegate, owner, amount)`, `revoke`, `setAuthority(target, current, AuthorityType.MintTokens, next | null)`,
   `freezeAccount` / `thawAccount(account, mint, freezeAuthority)`, `syncNative(account)`, `initializeMint2(mint, decimals, mintAuthority, freezeAuthority | null)`,
-  `initializeAccount3(account, mint, owner)`, and on Token-2022 `initializeMetadata(mint, updateAuthority, mintAuthority, name, symbol, uri)` (metadata extension)
+  `initializeAccount3(account, mint, owner)`, and on Token-2022 `initializeMetadata(mint, updateAuthority, mintAuthority, name, symbol, uri)` (metadata extension) and the extension initializers to call between `createAccount` and `initializeMint2` / `initializeAccount3`: `initializeTransferFeeConfig(mint, configAuthority | null, withdrawAuthority | null, basisPoints, maximumFee)`, `initializeMintCloseAuthority(mint, authority | null)`, `initializeNonTransferableMint(mint)`, `initializePermanentDelegate(mint, delegate)`, `initializeDefaultAccountState(mint, frozen)`, `initializeMetadataPointer` / `initializeGroupPointer` / `initializeGroupMemberPointer` / `initializeTransferHook(mint, authority | null, address | null)`, `initializeInterestBearingMint(mint, rateAuthority | null, rate)`, `initializeImmutableOwner(account)`
 - `account.lamports` read/write on `Mut` accounts, `close(account, destination)` for program accounts
 - `requirePda(account, seeds, bump)`
 
@@ -144,10 +149,10 @@ an integer literal, an argument, `acct.key` or a scalar field of an account, the
 
 ## Not supported yet
 
-Vecs anywhere but the last account field, growing an account by more than 10 KiB in one instruction, growing a Vec
-inside a helper, data-enum arguments carrying strings/structs, Pubkeys in templates, `?.` / `!` / `**`, `switch` on
-128-bit integers, `mulDiv` beyond u64, Token Metadata creators/collections, Core plugins, Bubblegum v2 / collections /
-transfers, floating point (by design), `do … while`.
+Growable `Vec`s anywhere but the last account field (use `FixedVec<T, N>`), FixedVec in arguments and events, growing an account by more than 10 KiB in one instruction, growing a Vec
+inside a helper, data-enum arguments carrying structs, Pubkeys in templates, `?.`, `**=`, `!` on anything but an Option, `switch` on
+128-bit integers, `mulDiv` beyond u64, Core's MasterEdition / VerifiedCreators / Autograph plugins, royalty rule sets and external plugin adapters, Bubblegum V2 delegates / freezes / metadata updates / V1 transfers, closures (local functions reading the enclosing function's variables), functions as values (callbacks,
+`.map`), type parameters standing for structs, floating point (by design), `do … while`.
 They are rejected at compile time rather than half-supported.
 
 `Init.create` handles a PDA address someone pre-funded: it tops up rent, then allocates and assigns instead of

package/docs/mainnet.md

@@ -77,12 +77,13 @@ explorers look for it. It costs a few thousandths of a SOL of rent.
 ## 6. Verify
 
 ```sh
-solana program dump <program id> deployed.so
-npx typesol verify my_app deployed.so
+npx typesol verify my_app
 ```
 
-`verify` rebuilds the program from `programs/my_app.ts` and compares it with the deployed bytes. `match` means anyone
-with your source and the same TypeSOL version gets exactly the program on chain.
+`verify` rebuilds the program from `programs/my_app.ts`, reads the deployed one at the address in `typesol.json` from
+the cluster in your Solana CLI config, and compares the bytes. `match` means anyone with your source and the same
+TypeSOL version gets exactly the program on chain. It also prints the upgrade authority and checks the IDL you
+published in step 5. Anyone can run it against your program with `--address <program id> --url mainnet-beta`.
 
 ## 7. Call it