@typesol/cli 0.14.0 → 0.16.0

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.d.ts

@@ -1,4 +1,5 @@
 import { type BuildResult, type Sbpf } from "./compiler/index.js";
+import { type TemplateName } from "./templates.js";
 export declare const CONFIG = "typesol.json";
 /** A program entry in typesol.json: its entry file and (recorded on first build) its address. */
 export interface ProgramEntry {
@@ -47,5 +48,5 @@ export declare function deployArgs(soPath: string, keypair: string, opts: {
     payer?: string;
     config?: string;
 }): string[];
-/** Create a project: typesol.json, one program, a LiteSVM test, configs. Refuses to overwrite files. */
-export declare function scaffold(dir: string, name: string): string[];
+/** Create a project: typesol.json, one program from a template, its LiteSVM test, configs. Refuses to overwrite files. */
+export declare function scaffold(dir: string, name: string, template?: TemplateName): string[];

package/dist/workspace.js

@@ -16,6 +16,7 @@ import path from "node:path";
 import { writeClient } from "./clientgen.js";
 import { build, COMPILER_VERSION, SBPF_VERSIONS } from "./compiler/index.js";
 import { loadOrCreateKeypair } from "./keys.js";
+import { TEMPLATES } from "./templates.js";
 export const CONFIG = "typesol.json";
 export function findWorkspace(dir) {
     for (let d = path.resolve(dir);; d = path.dirname(d)) {
@@ -104,119 +105,29 @@ export function deployArgs(soPath, keypair, opts) {
         args.push("--keypair", opts.payer);
     return args;
 }
-const PROGRAM = `import { type Account, type Init, type Mut, type Pubkey, type Signer, type SystemProgram, type u8, type u64, require } from "typesol";
-
-export interface Counter {
-  authority: Pubkey;
-  count: u64;
-  bump: u8;
-}
-
-export enum CounterError {
-  Unauthorized = "Only the counter's authority can change it",
-}
-
-/** Create the caller's counter at PDA ["counter", authority]. */
-export function initialize(authority: Mut<Signer>, counter: Init<Counter>, systemProgram: SystemProgram): void {
-  counter.bump = counter.create(authority, ["counter", authority.key]);
-  counter.authority = authority.key;
-  counter.count = 0n;
-}
-
-export function increment(authority: Signer, counter: Mut<Counter>, by: u64): void {
-  require(counter.authority === authority.key, CounterError.Unauthorized);
-  counter.count += by;
-}
-
-export function assertAtLeast(counter: Account<Counter>, min: u64): void {
-  require(counter.count >= min, "counter is below the expected minimum");
-}
-`;
-const TEST = (name) => `// Runs the program in LiteSVM (an in-process Solana runtime): \`npm test\`.
-import { BN, BorshCoder, type Idl } from "@anchor-lang/core";
-import {
-  AccountRole,
-  appendTransactionMessageInstructions,
-  createTransactionMessage,
-  generateKeyPairSigner,
-  getAddressEncoder,
-  getProgramDerivedAddress,
-  lamports,
-  pipe,
-  setTransactionMessageFeePayerSigner,
-  signTransactionMessageWithSigners,
-  type Address,
-  type Instruction,
-  type KeyPairSigner,
-} from "@solana/kit";
-import { FailedTransactionMetadata, LiteSVM } from "litesvm";
-import path from "node:path";
-import { fileURLToPath } from "node:url";
-import { buildWorkspace, findWorkspace } from "typesol/workspace";
-import { beforeAll, describe, expect, it } from "vitest";
-
-const SYSTEM = "11111111111111111111111111111111" as Address;
-const ws = findWorkspace(path.dirname(fileURLToPath(import.meta.url)))!;
-
-describe("${name}", () => {
-  const svm = new LiteSVM();
-  let programId: Address;
-  let coder: BorshCoder;
-  beforeAll(() => {
-    const [built] = buildWorkspace(ws, ["${name}"]);
-    programId = built.address as Address;
-    svm.addProgramFromFile(programId, built.result.soPath);
-    coder = new BorshCoder(built.result.idl as unknown as Idl);
-  });
-
-  const ix = (name: string, args: object, accounts: { address: Address; signer?: KeyPairSigner; writable?: boolean }[]): Instruction => ({
-    programAddress: programId,
-    accounts: accounts.map((a) => ({
-      address: a.address,
-      role: a.signer ? (a.writable ? AccountRole.WRITABLE_SIGNER : AccountRole.READONLY_SIGNER) : a.writable ? AccountRole.WRITABLE : AccountRole.READONLY,
-      ...(a.signer ? { signer: a.signer } : {}),
-    })) as Instruction["accounts"],
-    data: new Uint8Array(coder.instruction.encode(name, args)),
-  });
-  const send = async (payer: KeyPairSigner, ixs: Instruction[]) => {
-    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;
-  };
-
-  it("initializes and increments the caller's counter", async () => {
-    const alice = await generateKeyPairSigner();
-    svm.airdrop(alice.address, lamports(1_000_000_000n));
-    const [counter] = await getProgramDerivedAddress({ programAddress: programId, seeds: ["counter", getAddressEncoder().encode(alice.address)] });
-    const me = { address: alice.address, signer: alice, writable: true };
-    expect(await send(alice, [ix("initialize", {}, [me, { address: counter, writable: true }, { address: SYSTEM }])])).not.toBeInstanceOf(FailedTransactionMetadata);
-    expect(await send(alice, [ix("increment", { by: new BN(5) }, [{ address: alice.address, signer: alice }, { address: counter, writable: true }])])).not.toBeInstanceOf(FailedTransactionMetadata);
-    const account = svm.getAccount(counter);
-    if (!account.exists) throw new Error("counter was not created");
-    const state = coder.accounts.decode("Counter", Buffer.from(account.data));
-    expect(state.count.toString()).toBe("5");
-  });
-});
-`;
-/** Create a project: typesol.json, one program, a LiteSVM test, configs. Refuses to overwrite files. */
-export function scaffold(dir, name) {
+/** Create a project: typesol.json, one program from a template, its LiteSVM test, configs. Refuses to overwrite files. */
+export function scaffold(dir, name, template = "counter") {
+    const t = TEMPLATES[template];
     if (!/^[a-z][a-z0-9_]*$/.test(name))
         throw new Error(`program name "${name}" must be snake_case`);
     const files = {
         [CONFIG]: JSON.stringify({ programs: { [name]: { path: `programs/${name}.ts` } }, out: "target", sbpf: "v0" }, null, 2) + "\n",
-        [`programs/${name}.ts`]: PROGRAM,
+        [`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`]: TEST(name),
+        [`tests/${name}.test.ts`]: t.test(name),
         "package.json": JSON.stringify({
             name,
             private: true,
@@ -232,6 +143,7 @@ export function scaffold(dir, name) {
                 "@solana/kit": "^8.5.0",
                 litesvm: "^1.6.1",
                 vitest: "^5.0.5",
+                ...t.devDependencies,
             },
         }, null, 2) + "\n",
         // target/deploy/*-keypair.json are the programs' addresses: never commit them, but keep a backup.

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

@@ -6,16 +6,17 @@ error. Exit codes: **0** success, **1** failure (compile errors, failed deploy,
 
 | Command | What it does |
 | --- | --- |
-| `typesol init [<dir>] [--name <program>]` | Create a project: `typesol.json`, `programs/<name>.ts`, `tests/<name>.test.ts` (LiteSVM), `package.json`, `tsconfig.json`. Refuses to overwrite files. |
+| `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/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,11 +18,12 @@ 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 |
 | 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) |
@@ -31,15 +32,15 @@ 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) |
 | 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) |
@@ -75,7 +76,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); `metadataAddress(mint)` |
 | `InstructionsSysvar`, `PythPriceUpdate`, `SwitchboardFeed` | exact address / owner program + discriminator |
 | `Program<"Address…">` | exact program address + executable |
 | `UncheckedProgram` | executable only — check `.key` yourself |
@@ -94,7 +95,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)`
 
@@ -145,8 +146,8 @@ 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 /
+inside a helper, data-enum arguments carrying structs, Pubkeys in templates, `?.`, `**=`, `!` on anything but an Option, `switch` on
+128-bit integers, `mulDiv` beyond u64, Token Metadata collection verification, Core plugins, Bubblegum v2 / collections /
 transfers, floating point (by design), `do … while`.
 They are rejected at compile time rather than half-supported.