@typesol/cli 0.15.0 → 0.17.0

package/dist/portgen.js

@@ -0,0 +1,367 @@
+/**
+ * `typesol port <idl.json>`: a TypeSOL program skeleton from an Anchor IDL (0.30+/1.x), to port an Anchor program.
+ *
+ * It writes the account structs, enums, errors, events and one function per instruction with its accounts and
+ * arguments, bodies left to fill in. Instructions keep their discriminators (an explicit `@discriminator` when the
+ * name would derive another), account structs keep their names (so their discriminators), errors keep their order —
+ * so existing clients keep working. Account structs holding a String, Vec or Option get `@layout borsh`, so they keep
+ * Anchor's bytes (existing accounts stay readable); where a layout still differs (a String or Vec nested in a struct, a
+ * data enum, a COption) it says so in a note and a comment.
+ */
+import { createHash } from "node:crypto";
+import { cNameProblem } from "./compiler/analyze.js";
+const RESERVED = new Set("break case catch class const continue debugger default delete do else enum export extends false finally for function if import in instanceof new null return super switch this throw true try typeof var void while with yield let static implements interface package private protected public await".split(" "));
+const camel = (s) => s.replace(/[_-]+([a-zA-Z0-9])/g, (_, c) => c.toUpperCase()).replace(/^[A-Z]/, (c) => c.toLowerCase());
+const pascal = (s) => camel(s).replace(/^[a-z]/, (c) => c.toUpperCase());
+const snake = (s) => s.replace(/([a-z0-9])([A-Z])/g, "$1_$2").toLowerCase();
+/** Names TypeSOL source cannot use as written: TypeScript keywords, the generated C's reserved names, the builtins
+ *  a skeleton imports, names starting with "_". */
+const BUILTINS = new Set(["require"]); // what a skeleton imports as a value
+/** A function, parameter or local name; `member`: a struct field or variant, which also becomes a C member name. */
+const ident = (s, member = false) => {
+    let n = camel(s).replace(/^_+/, "") || "value";
+    if (/^\d/.test(n))
+        n = `v${n}`;
+    while (RESERVED.has(n) || BUILTINS.has(n) || (member && cNameProblem(n)))
+        n = `${n}Value`;
+    return n;
+};
+/** A type name: kept as written when it is a valid one (account names decide account discriminators). */
+const typeName = (s) => (/^[A-Za-z][A-Za-z0-9_]*$/.test(s) && !s.includes("__") && !RESERVED.has(s) ? s : pascal(s).replace(/^(\d)/, "T$1"));
+const sighash = (preimage) => [...createHash("sha256").update(preimage).digest().subarray(0, 8)];
+const sameBytes = (a, b) => a.length === b.length && a.every((x, i) => x === b[i]);
+const INTS = new Set(["u8", "u16", "u32", "u64", "u128", "i8", "i16", "i32", "i64", "i128"]);
+const PROGRAMS = {
+    "11111111111111111111111111111111": "SystemProgram",
+    TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA: "TokenProgram",
+    TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb: "Token2022Program",
+    ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL: "AssociatedTokenProgram",
+};
+export function generatePort(idl) {
+    const notes = [];
+    const imports = new Set();
+    const use = (n) => (imports.add(n), n);
+    const accountNames = new Set((idl.accounts ?? []).map((a) => a.name));
+    const eventNames = new Set((idl.events ?? []).map((e) => e.name));
+    const definedName = (d) => (typeof d === "string" ? d : d.name);
+    const defs = new Map((idl.types ?? []).map((t) => [t.name, t]));
+    // The fixed layouts a TypeSOL-built IDL spells out as helper types map back to TypeSOL's own types.
+    const helperDefs = new Map((idl.types ?? []).filter((t) => /^(FixedString\d+|FixedOption_|FixedEnum_)/.test(t.name)).map((t) => [t.name, t]));
+    const isTuple = (fields) => !!fields?.length && (typeof fields[0] !== "object" || fields[0] === null || !("name" in fields[0]));
+    // Types the skeleton cannot declare: references to them become a placeholder with a note.
+    const skipped = new Set((idl.types ?? [])
+        .filter((d) => !helperDefs.has(d.name) &&
+        (d.generics?.length || (d.type.kind === "struct" && isTuple(d.type.fields)) || (d.type.kind !== "struct" && d.type.kind !== "enum")))
+        .map((d) => d.name));
+    const dataEnum = (name) => defs.get(name)?.type.kind === "enum" && (defs.get(name)?.type.variants ?? []).some((v) => v.fields?.length);
+    // Where each struct is used decides what a field can be: account data and struct arguments keep fixed layouts.
+    const usage = new Map();
+    const mark = (t, as) => {
+        if (!t || typeof t === "string")
+            return;
+        const inner = t.vec ?? t.option ?? t.coption ?? t.array?.[0];
+        if (inner)
+            return mark(inner, as);
+        if (!t.defined)
+            return;
+        const name = definedName(t.defined);
+        const set = usage.get(name) ?? new Set();
+        if (set.has(as))
+            return;
+        usage.set(name, set.add(as));
+        const def = defs.get(name);
+        for (const f of (def?.type.fields ?? []))
+            if (typeof f === "object" && f && "type" in f)
+                mark(f.type, as);
+        for (const v of def?.type.variants ?? [])
+            for (const f of v.fields ?? [])
+                mark(typeof f === "object" && f && "type" in f ? f.type : f, as);
+    };
+    for (const a of accountNames)
+        mark({ defined: a }, "account");
+    for (const e of eventNames)
+        mark({ defined: e }, "event");
+    for (const ix of idl.instructions)
+        for (const g of ix.args)
+            mark(g.type, "arg");
+    const fixed = (w) => w === "account" || w === "struct" || w === "variant";
+    const describe = (w) => (w === "account" ? "account data" : w === "struct" ? "a struct argument" : "a data-enum variant");
+    const tsType = (t, where, at, last = false) => {
+        if (typeof t === "string") {
+            if (INTS.has(t))
+                return use(t);
+            if (t === "bool")
+                return "boolean";
+            if (t === "pubkey" || t === "publicKey")
+                return use("Pubkey");
+            if (t === "string") {
+                if (!fixed(where))
+                    return "string";
+                notes.push(`${at}: Anchor encodes this String with its length (Borsh); TypeSOL holds FixedString<N> (u32 length + N bytes) in ${describe(where)}, so this layout differs. Set N.`);
+                return `${use("FixedString")}<32> /* TODO: capacity; Anchor has a variable String */`;
+            }
+            if (t === "bytes")
+                return tsType({ vec: "u8" }, where, at, last);
+            notes.push(`${at}: IDL type "${t}" has no TypeSOL equivalent; left as u64`);
+            return `${use("u64")} /* TODO: ${t} */`;
+        }
+        if (t.array) {
+            const n = Number(t.array[1]);
+            if (!Number.isInteger(n) || n < 1) {
+                notes.push(`${at}: an array of length ${JSON.stringify(t.array[1])}; set it`);
+                return `${use("FixedArray")}<${tsType(t.array[0], where, at)}, 1> /* TODO: length */`;
+            }
+            return `${use("FixedArray")}<${tsType(t.array[0], where, at)}, ${n}>`;
+        }
+        if (t.coption)
+            notes.push(`${at}: a COption (4-byte tag in Anchor); TypeSOL's Option has a 1-byte tag, so this layout differs.`);
+        if (t.option || t.coption) {
+            const inner = tsType((t.option ?? t.coption), where === "variant" ? "variant" : where, at);
+            if (fixed(where))
+                notes.push(`${at}: an Option in ${describe(where)} is fixed-size in TypeSOL (1 + size of T), Borsh (1, or 1 + size) in Anchor: the layout differs.`);
+            return `${use("Option")}<${inner}>`;
+        }
+        if (t.vec) {
+            const inner = tsType(t.vec, where, at);
+            if (where === "variant" || where === "struct" || (where === "account" && !last)) {
+                notes.push(`${at}: a Vec here (TypeSOL keeps a Vec only as an account's last field or as an argument); replaced by FixedArray, so the layout differs.`);
+                return `${use("FixedArray")}<${inner}, 8> /* TODO: Anchor has a Vec here */`;
+            }
+            return `${use("Vec")}<${inner}>`;
+        }
+        if (t.defined) {
+            const name = definedName(t.defined);
+            const fs = /^FixedString(\d+)$/.exec(name);
+            if (fs)
+                return `${use("FixedString")}<${fs[1]}>`;
+            const helper = helperDefs.get(name);
+            if (helper && name.startsWith("FixedOption_")) {
+                const value = (helper.type.fields ?? []).find((f) => f.name === "value");
+                if (value)
+                    return `${use("Option")}<${tsType(value.type, "arg", at)}>`;
+            }
+            if (name.startsWith("FixedEnum_"))
+                return typeName(name.slice("FixedEnum_".length));
+            if (skipped.has(name)) {
+                notes.push(`${at}: ${name} could not be ported (generic, tuple or unsupported type); replaced by a placeholder`);
+                return `${use("u8")} /* TODO: ${name} */`;
+            }
+            if ((where === "account" || where === "struct") && dataEnum(name))
+                notes.push(`${at}: ${name} is a data enum: Anchor stores the variant's own size (Borsh), TypeSOL the largest variant's, so this layout differs.`);
+            return typeName(name);
+        }
+        notes.push(`${at}: unsupported IDL type ${JSON.stringify(t)}; left as u64`);
+        return `${use("u64")} /* TODO */`;
+    };
+    /** A String, Vec or Option at a struct's top level: Borsh-sized in Anchor. */
+    const borshOnly = (t) => t === "string" || t === "bytes" || (typeof t === "object" && (!!t.vec || !!t.option));
+    /** A field's type in a `@layout borsh` struct, or undefined when that layout cannot hold it. Notes the capacities. */
+    const borshField = (t, at) => {
+        const quiet = at === "";
+        const fixedOk = (u) => {
+            if (typeof u === "string")
+                return INTS.has(u) || u === "bool" || u === "pubkey" || u === "publicKey";
+            if (u.array)
+                return Number.isInteger(Number(u.array[1])) && fixedOk(u.array[0]);
+            if (u.defined) {
+                const name = definedName(u.defined);
+                const d = defs.get(name);
+                if (!d || skipped.has(name) || helperDefs.has(name))
+                    return false;
+                if (d.type.kind === "enum")
+                    return (d.type.variants ?? []).every((v) => !v.fields?.length);
+                return (d.type.fields ?? []).every((f) => fixedOk(f.type));
+            }
+            return false;
+        };
+        if (t === "string") {
+            if (!quiet)
+                notes.push(`${at}: set the String's capacity to Anchor's #[max_len] (Borsh bytes are kept: @layout borsh)`);
+            return `${use("FixedString")}<32> /* TODO: #[max_len] */`;
+        }
+        if (t === "bytes")
+            return borshField({ vec: "u8" }, at);
+        if (typeof t === "object" && t.vec) {
+            const elem = t.vec === "string"
+                ? `${use("FixedString")}<32> /* TODO: #[max_len] */`
+                : fixedOk(t.vec) && !quiet
+                    ? tsType(t.vec, "account", at)
+                    : fixedOk(t.vec)
+                        ? "x"
+                        : undefined;
+            if (elem === undefined)
+                return undefined;
+            if (!quiet)
+                notes.push(`${at}: set the Vec's capacity to Anchor's #[max_len] (Borsh bytes are kept: @layout borsh)`);
+            return `${use("FixedVec")}<${elem}, 8> /* TODO: #[max_len] */`;
+        }
+        if (typeof t === "object" && t.option) {
+            if (!fixedOk(t.option))
+                return undefined;
+            return quiet ? "x" : `${use("Option")}<${tsType(t.option, "account", at)}>`;
+        }
+        if (!fixedOk(t))
+            return undefined;
+        return quiet ? "x" : tsType(t, "account", at);
+    };
+    const esc = (s) => s.replace(/\*\//g, "* /");
+    const docs = (lines, pad = "") => (lines?.length ? `${pad}/** ${esc(lines.join(" "))} */\n` : "");
+    const out = [];
+    // Constants: integer literals and strings; expressions are left to port by hand.
+    for (const c of idl.constants ?? []) {
+        const ty = typeof c.type === "string" && INTS.has(c.type) ? c.type : undefined;
+        const name = /^[A-Za-z_][A-Za-z0-9_]*$/.test(c.name) ? c.name : ident(c.name);
+        if (ty && /^-?\d[\d_]*$/.test(c.value.trim()))
+            out.push(`export const ${name}: ${use(ty)} = ${c.value.trim().replace(/_/g, "")}n;`);
+        else if (c.type === "string" && /^".*"$/.test(c.value.trim()))
+            out.push(`export const ${name} = ${c.value.trim()};`);
+        else
+            notes.push(`constant ${c.name} = ${c.value}: not a literal; port it by hand`);
+    }
+    if (out.length)
+        out.push("");
+    // Types: structs (account data, events or arguments), enums.
+    for (const def of idl.types ?? []) {
+        if (helperDefs.has(def.name))
+            continue;
+        if (skipped.has(def.name)) {
+            notes.push(`type ${def.name}: ${def.generics?.length ? "generics are" : def.type.kind === "struct" ? "tuple structs are" : `kind "${def.type.kind}" is`} not supported; skipped`);
+            continue;
+        }
+        const used = usage.get(def.name) ?? new Set(["account"]);
+        const where = used.has("account") ? "account" : used.has("arg") ? "struct" : used.has("event") ? "event" : "account";
+        if (def.type.kind === "struct") {
+            const fields = (def.type.fields ?? []);
+            // An account struct with a String, Vec or Option of its own: `@layout borsh` keeps Anchor's bytes.
+            const borsh = accountNames.has(def.name) && !isTuple(fields) && fields.some((f) => borshOnly(f.type)) && fields.every((f) => borshField(f.type, "") !== undefined);
+            const tag = accountNames.has(def.name) ? " (account)" : eventNames.has(def.name) ? ` (event: emit<${typeName(def.name)}>({ … }))` : "";
+            const doc = def.docs?.length ? esc(def.docs.join(" ")) : `${def.name}${tag}`;
+            out.push(borsh ? `/**\n * ${doc}\n * @layout borsh\n */` : `/** ${doc} */`);
+            out.push(`export interface ${typeName(def.name)} {`);
+            const seen = new Set();
+            fields.forEach((f, i) => {
+                let n = ident(f.name, true);
+                while (seen.has(n))
+                    n = `${n}2`;
+                seen.add(n);
+                const ty = borsh ? borshField(f.type, `${def.name}.${f.name}`) : tsType(f.type, where, `${def.name}.${f.name}`, i === fields.length - 1);
+                out.push(`${docs(f.docs, "  ")}  ${n}: ${ty};`);
+            });
+            out.push("}", "");
+        }
+        else {
+            const variants = def.type.variants ?? [];
+            if (variants.every((v) => !v.fields?.length)) {
+                out.push(`${docs(def.docs)}export enum ${typeName(def.name)} {`, ...variants.map((v) => `  ${ident(v.name, true).replace(/^[a-z]/, (c) => c.toUpperCase())},`), "}", "");
+            }
+            else {
+                // Strings in variants are fine in arguments and events (Borsh); account data needs fixed-size variants.
+                const vw = used.has("account") || (!used.has("arg") && !used.has("event")) ? "variant" : "event";
+                const parts = variants.map((v) => {
+                    const fs = (v.fields ?? []).map((f, i) => typeof f === "object" && f !== null && "name" in f
+                        ? `${ident(f.name, true)}: ${tsType(f.type, vw, `${def.name}.${v.name}`)}`
+                        : `f${i}: ${tsType(f, vw, `${def.name}.${v.name}`)}`);
+                    return `{ kind: "${pascal(v.name)}"${fs.map((x) => `; ${x}`).join("")} }`;
+                });
+                out.push(`${docs(def.docs)}export type ${typeName(def.name)} =\n  | ${parts.join("\n  | ")};`, "");
+            }
+        }
+    }
+    // Errors: TypeSOL numbers them 6000 + their index. NotPorted, last, marks the instructions still to write, so the
+    // codes of the program's own errors do not move.
+    const errors = idl.errors ?? [];
+    const program = typeName(pascal(idl.metadata?.name ?? "program"));
+    const errorEnum = `${program}Error`;
+    if (!errors.every((e, i) => e.code === 6000 + i))
+        notes.push(`errors: TypeSOL numbers an error enum from 6000 in order; the IDL's codes (${errors.map((e) => e.code).join(", ")}) differ, so clients see other codes`);
+    const memberNames = new Set();
+    const member = (name) => {
+        // RequireFailedN is TypeSOL's own name for require("message") errors; it is reserved in source.
+        let n = /^RequireFailed\d+$/.test(name) ? name.replace("RequireFailed", "Check") : pascal(name);
+        while (memberNames.has(n))
+            n += "_";
+        memberNames.add(n);
+        return n;
+    };
+    const errorLines = errors.map((e) => `  ${member(e.name)} = ${JSON.stringify(e.msg ?? e.name)},`);
+    const notPorted = member("NotPorted");
+    out.push(`export enum ${errorEnum} {`, ...errorLines, `  ${notPorted} = "This instruction is not ported yet",`, "}", "");
+    // Accounts of an instruction, nested groups flattened.
+    const flatten = (items, prefix = "") => items.flatMap((a) => (a.accounts ? flatten(a.accounts, `${prefix}${a.name}_`) : [{ ...a, name: `${prefix}${a.name}` }]));
+    for (const ix of idl.instructions) {
+        const fn = ident(ix.name);
+        const params = [];
+        const comments = [];
+        const taken = new Set();
+        const unique = (n, kind) => {
+            let m = n;
+            while (taken.has(m))
+                m = `${m}${kind}`;
+            if (m !== n)
+                notes.push(`${ix.name}: ${kind.toLowerCase()} "${n}" renamed to "${m}" (an account and an argument share the name)`);
+            taken.add(m);
+            return m;
+        };
+        for (const a of flatten(ix.accounts)) {
+            let ty;
+            if (a.address && PROGRAMS[a.address])
+                ty = use(PROGRAMS[a.address]);
+            else if (a.signer)
+                ty = a.writable ? `${use("Mut")}<${use("Signer")}>` : use("Signer");
+            else {
+                // The IDL does not say which struct an account holds: AccountInfo until you pick Account<T> / Mut<T> / Init<T>.
+                const base = a.writable ? `${use("Mut")}<${use("AccountInfo")}>` : use("AccountInfo");
+                ty = a.address ? `${use("Address")}<${base}, "${a.address}">` : base;
+            }
+            if (a.optional)
+                ty = `${ty} | null`;
+            params.push(`${unique(ident(a.name), "Account")}: ${ty}`);
+            if (a.pda) {
+                const seeds = a.pda.seeds.map((s) => s.kind === "const"
+                    ? JSON.stringify(Buffer.from(s.value ?? []).toString("utf8"))
+                    : s.kind === "arg"
+                        ? `@${camel(s.path ?? "")} (argument)`
+                        : `@${camel(s.path ?? "")}`);
+                comments.push(`${ident(a.name)}: PDA [${seeds.join(", ")}]`);
+            }
+            if (a.relations?.length)
+                comments.push(`${ident(a.name)}: has_one ${a.relations.map(camel).join(", ")}`);
+        }
+        for (const g of ix.args)
+            params.push(`${unique(ident(g.name), "Arg")}: ${tsType(g.type, "arg", `${ix.name}(${g.name})`)}`);
+        let ret = "void";
+        let body = `  ${use("require")}(false, ${errorEnum}.${notPorted}); // TODO: port ${ix.name}`;
+        if (ix.returns) {
+            const r = typeof ix.returns === "string" ? ix.returns : undefined;
+            if (r && INTS.has(r))
+                ((ret = use(r)), (body += "\n  return 0n;"));
+            else if (r === "bool")
+                ((ret = "boolean"), (body += "\n  return false;"));
+            else
+                notes.push(`${ix.name}: returns ${JSON.stringify(ix.returns)}; set the return type and value`);
+        }
+        const derived = sighash(`global:${snake(fn)}`);
+        const tags = sameBytes(derived, ix.discriminator) ? [] : [`@discriminator 0x${Buffer.from(ix.discriminator).toString("hex")}`];
+        const doc = [...(ix.docs ?? []), ...comments.map((c) => `- ${c}`), ...tags];
+        if (doc.length)
+            out.push(`/**\n${doc.map((l) => ` * ${esc(l)}`).join("\n")}\n */`);
+        out.push(`export function ${fn}(${params.join(", ")}): ${ret} {`, body, "}", "");
+    }
+    for (const a of idl.accounts ?? []) {
+        if (!sameBytes(sighash(`account:${a.name}`), a.discriminator))
+            notes.push(`account ${a.name}: its discriminator is not sha256("account:${a.name}"); TypeSOL derives that one, so existing accounts would not load`);
+    }
+    const header = [
+        `// Ported from the ${idl.metadata?.name ?? "program"} IDL by \`typesol port\`. Fill in the instruction bodies;`,
+        "// pick Account<T> / Mut<T> / Init<T> for the AccountInfo parameters that hold one of the structs below.",
+        `import { ${[
+            ...[...imports]
+                .filter((n) => n !== "require")
+                .sort()
+                .map((n) => `type ${n}`),
+            ...(imports.has("require") ? ["require"] : []),
+        ].join(", ")} } from "typesol";`,
+        "",
+    ];
+    return { source: [...header, ...out].join("\n").replace(/\n{3,}/g, "\n\n"), notes };
+}

package/dist/templates.js

@@ -2,71 +2,16 @@
 // main flow and at least one refused call, so a new project starts from something that passes and shows how to test.
 // The programs are copies of examples/ (test/workspace.test.ts checks they still match).
 export const TEMPLATE_NAMES = ["counter", "vault", "escrow"];
-/** The part every test shares: build the project's program into a LiteSVM, encode instructions with its IDL, send. */
+/** Every test starts the same way: build the project's program into a LiteSVM with `typesol/testing`. */
 const testFile = (name, o) => `// Runs the program in LiteSVM (an in-process Solana runtime): \`npm test\`.
-import { BN, BorshCoder, type Idl } from "@anchor-lang/core";
-${o.imports}import {
-${[
-    "AccountRole",
-    "appendTransactionMessageInstructions",
-    "createTransactionMessage",
-    ...o.kit,
-    "pipe",
-    "setTransactionMessageFeePayerSigner",
-    "signTransactionMessageWithSigners",
-    "type Address",
-    "type Instruction",
-    "type KeyPairSigner",
-]
-    .map((x) => `  ${x},`)
-    .join("\n")}
-} from "@solana/kit";
-import { FailedTransactionMetadata, LiteSVM, TransactionMetadata } from "litesvm";
-import path from "node:path";
-import { fileURLToPath } from "node:url";
-import { buildWorkspace, findWorkspace } from "typesol/workspace";
+${o.imports ?? ""}import { testProgram, type TestProgram } from "typesol/testing";
 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)),
+  let t: TestProgram;
+  beforeAll(async () => {
+    t = await testProgram("${name}", import.meta.url);
   });
-  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;
-  };
-  /** The custom error code of a failed transaction: 6000 + the member's index in the program's error enum. */
-  const errorCode = (res: TransactionMetadata | FailedTransactionMetadata) => {
-    if (!(res instanceof FailedTransactionMetadata)) throw new Error("expected the transaction to fail");
-    return Number(/Custom\\D*(\\d+)/.exec(String(res.err()))?.[1]);
-  };
 ${o.body}});
 `;
 export const TEMPLATES = {
@@ -101,25 +46,17 @@ export function assertAtLeast(counter: Account<Counter>, min: u64): void {
 }
 `,
         test: (name) => testFile(name, {
-            imports: "",
-            kit: ["generateKeyPairSigner", "getAddressEncoder", "getProgramDerivedAddress", "lamports"],
             body: `
   it("initializes and increments the caller's counter; refuses anyone else", async () => {
-    const alice = await generateKeyPairSigner();
-    const mallory = await generateKeyPairSigner();
-    svm.airdrop(alice.address, lamports(1_000_000_000n));
-    svm.airdrop(mallory.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 }])])).toBeInstanceOf(TransactionMetadata);
-    expect(await send(alice, [ix("increment", { by: new BN(5) }, [{ address: alice.address, signer: alice }, { address: counter, writable: true }])])).toBeInstanceOf(TransactionMetadata);
-    const account = svm.getAccount(counter);
-    if (!account.exists) throw new Error("counter was not created");
-    expect(coder.accounts.decode("Counter", Buffer.from(account.data)).count.toString()).toBe("5");
+    const alice = await t.wallet();
+    const mallory = 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<{ count: bigint }>("Counter", counter))?.count).toBe(5n);
 
     // CounterError.Unauthorized is the enum's first member: 6000.
-    const stranger = ix("increment", { by: new BN(1) }, [{ address: mallory.address, signer: mallory }, { address: counter, writable: true }]);
-    expect(errorCode(await send(mallory, [stranger]))).toBe(6000);
+    expect(t.errorCode(await t.send(mallory, t.ix("increment", { by: 1n }, { authority: mallory, counter })))).toBe(6000);
   });
 `,
         }),
@@ -182,41 +119,30 @@ export function shut(owner: Mut<Signer>, vault: Mut<Vault>): void {
 }
 `,
         test: (name) => testFile(name, {
-            imports: "",
-            kit: ["generateKeyPairSigner", "getAddressEncoder", "getProgramDerivedAddress", "lamports"],
             body: `
   it("deposits and withdraws SOL, keeps the rent reserve, then closes", async () => {
-    const owner = await generateKeyPairSigner();
-    svm.airdrop(owner.address, lamports(10_000_000_000n));
-    const [vault] = await getProgramDerivedAddress({ programAddress: programId, seeds: ["vault", getAddressEncoder().encode(owner.address)] });
-    const me = { address: owner.address, signer: owner, writable: true };
-    const v = { address: vault, writable: true };
-
-    expect(await send(owner, [ix("open", {}, [me, v, { address: SYSTEM }])])).toBeInstanceOf(TransactionMetadata);
-    const rent = svm.getBalance(vault)!;
-    expect(await send(owner, [ix("deposit", { amount: new BN(3_000_000_000) }, [me, v, { address: SYSTEM }])])).toBeInstanceOf(TransactionMetadata);
-    expect(await send(owner, [ix("withdraw", { amount: new BN(1_000_000_000) }, [me, v])])).toBeInstanceOf(TransactionMetadata);
-    expect(svm.getBalance(vault)).toBe(rent + 2_000_000_000n);
+    const owner = await t.wallet();
+    const vault = await t.pda("vault", owner);
+    t.ok(await t.send(owner, t.ix("open", {}, { owner, vault })));
+    const rent = t.balance(vault);
+    t.ok(await t.send(owner, t.ix("deposit", { amount: 3_000_000_000n }, { owner, vault })));
+    t.ok(await t.send(owner, t.ix("withdraw", { amount: 1_000_000_000n }, { owner, vault })));
+    expect(t.balance(vault)).toBe(rent + 2_000_000_000n);
 
     // VaultError.InsufficientFunds (third member, 6002): the rent reserve stays.
-    expect(errorCode(await send(owner, [ix("withdraw", { amount: new BN(2_000_000_001) }, [me, v])]))).toBe(6002);
+    expect(t.errorCode(await t.send(owner, t.ix("withdraw", { amount: 2_000_000_001n }, { owner, vault })))).toBe(6002);
 
-    expect(await send(owner, [ix("shut", {}, [me, v])])).toBeInstanceOf(TransactionMetadata);
-    expect(svm.getAccount(vault).exists).toBe(false);
+    t.ok(await t.send(owner, t.ix("shut", {}, { owner, vault })));
+    expect(await t.account("Vault", vault)).toBeNull();
   });
 
   it("refuses a stranger", async () => {
-    const owner = await generateKeyPairSigner();
-    const thief = await generateKeyPairSigner();
-    svm.airdrop(owner.address, lamports(2_000_000_000n));
-    svm.airdrop(thief.address, lamports(1_000_000_000n));
-    const [vault] = await getProgramDerivedAddress({ programAddress: programId, seeds: ["vault", getAddressEncoder().encode(owner.address)] });
-    const v = { address: vault, writable: true };
-    expect(await send(owner, [ix("open", {}, [{ address: owner.address, signer: owner, writable: true }, v, { address: SYSTEM }])])).toBeInstanceOf(
-      TransactionMetadata,
-    );
+    const owner = await t.wallet();
+    const thief = await t.wallet();
+    const vault = await t.pda("vault", owner);
+    t.ok(await t.send(owner, t.ix("open", {}, { owner, vault })));
     // VaultError.NotOwner: 6000.
-    expect(errorCode(await send(thief, [ix("shut", {}, [{ address: thief.address, signer: thief, writable: true }, v])]))).toBe(6000);
+    expect(t.errorCode(await t.send(thief, t.ix("shut", {}, { owner: thief, vault })))).toBe(6000);
   });
 `,
         }),
@@ -330,18 +256,17 @@ export function refund(
 }
 `,
         test: (name) => testFile(name, {
-            imports: `import { AccountState, getMintEncoder, getMintSize, getTokenDecoder, getTokenEncoder, getTokenSize } from "@solana-program/token";\n`,
-            kit: ["generateKeyPairSigner", "getAddressEncoder", "getProgramDerivedAddress", "lamports"],
+            imports: `import { AccountState, getMintEncoder, getMintSize, getTokenDecoder, getTokenEncoder, getTokenSize } from "@solana-program/token";\nimport { type Address, type KeyPairSigner, generateKeyPairSigner, lamports } from "@solana/kit";\n`,
             body: `
   const TOKEN = "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA" as Address;
   /** A mint, written straight into the VM (a real client sends System CreateAccount + InitializeMint2). */
   const mint = async (authority: Address) => {
     const address = (await generateKeyPairSigner()).address;
     const data = getMintEncoder().encode({ mintAuthority: authority, supply: 0n, decimals: 6, isInitialized: true, freezeAuthority: null });
-    svm.setAccount({ address, data: new Uint8Array(data), executable: false, lamports: lamports(1_461_600n), programAddress: TOKEN, space: BigInt(getMintSize()) });
+    t.svm.setAccount({ address, data: new Uint8Array(data), executable: false, lamports: lamports(1_461_600n), programAddress: TOKEN, space: BigInt(getMintSize()) });
     return address;
   };
-  /** A token account of \`owner\` for \`mint\` holding \`amount\`, written straight into the VM. */
+  /** A token account of owner for mint holding amount, written straight into the VM. */
   const tokenAccount = async (owner: Address, mintAddress: Address, amount: bigint) => {
     const address = (await generateKeyPairSigner()).address;
     const data = getTokenEncoder().encode({
@@ -354,73 +279,43 @@ export function refund(
       delegatedAmount: 0n,
       closeAuthority: null,
     });
-    svm.setAccount({ address, data: new Uint8Array(data), executable: false, lamports: lamports(2_039_280n), programAddress: TOKEN, space: BigInt(getTokenSize()) });
+    t.svm.setAccount({ address, data: new Uint8Array(data), executable: false, lamports: lamports(2_039_280n), programAddress: TOKEN, space: BigInt(getTokenSize()) });
     return address;
   };
   const balance = (address: Address) => {
-    const account = svm.getAccount(address);
+    const account = t.svm.getAccount(address);
     return account.exists ? getTokenDecoder().decode(account.data).amount : null;
   };
 
   it("escrows mint A for mint B; the taker swaps, the maker can refund", async () => {
-    const maker = await generateKeyPairSigner();
-    const taker = await generateKeyPairSigner();
-    svm.airdrop(maker.address, lamports(1_000_000_000n));
-    svm.airdrop(taker.address, lamports(1_000_000_000n));
+    const maker = await t.wallet();
+    const taker = await t.wallet();
     const mintA = await mint(maker.address);
     const mintB = await mint(taker.address);
-    const makerA = await tokenAccount(maker.address, mintA, 1_000n);
-    const makerB = await tokenAccount(maker.address, mintB, 0n);
-    const takerA = await tokenAccount(taker.address, mintA, 0n);
-    const takerB = await tokenAccount(taker.address, mintB, 500n);
+    const makerTokenA = await tokenAccount(maker.address, mintA, 1_000n);
+    const makerTokenB = await tokenAccount(maker.address, mintB, 0n);
+    const takerTokenA = await tokenAccount(taker.address, mintA, 0n);
+    const takerTokenB = await tokenAccount(taker.address, mintB, 500n);
 
-    const open = async (seed: number) => {
-      const [offer] = await getProgramDerivedAddress({
-        programAddress: programId,
-        seeds: ["offer", getAddressEncoder().encode(maker.address), new Uint8Array(new BN(seed).toArray("le", 8))],
-      });
+    const open = async (seed: bigint) => {
+      const offer = await t.pda("offer", maker, seed);
       // The client creates the vault: an empty token account for mint A owned by the offer PDA.
       const vault = await tokenAccount(offer, mintA, 0n);
-      const make = ix("make", { seed: new BN(seed), amount_a: new BN(400), want_b: new BN(300), mint_b: { toBuffer: () => Buffer.from(getAddressEncoder().encode(mintB)) } }, [
-        { address: maker.address, signer: maker, writable: true },
-        { address: offer, writable: true },
-        { address: makerA, writable: true },
-        { address: vault, writable: true },
-        { address: SYSTEM },
-        { address: TOKEN },
-      ]);
-      expect(await send(maker, [make])).toBeInstanceOf(TransactionMetadata);
+      t.ok(await t.send(maker, t.ix("make", { seed, amountA: 400n, wantB: 300n, mintB }, { maker, offer, makerTokenA, vault })));
       return { offer, vault };
     };
 
-    const first = await open(1);
+    const first = await open(1n);
     expect(balance(first.vault)).toBe(400n);
-    const take = ix("take", {}, [
-      { address: taker.address, signer: taker, writable: true },
-      { address: maker.address, writable: true },
-      { address: first.offer, writable: true },
-      { address: takerA, writable: true },
-      { address: takerB, writable: true },
-      { address: makerB, writable: true },
-      { address: first.vault, writable: true },
-      { address: TOKEN },
-    ]);
-    expect(await send(taker, [take])).toBeInstanceOf(TransactionMetadata);
-    expect([balance(takerA), balance(makerB), balance(first.vault)]).toEqual([400n, 300n, null]);
+    t.ok(await t.send(taker, t.ix("take", {}, { taker, maker: maker.address, offer: first.offer, takerTokenA, takerTokenB, makerTokenB, vault: first.vault })));
+    expect([balance(takerTokenA), balance(makerTokenB), balance(first.vault)]).toEqual([400n, 300n, null]);
 
-    const second = await open(2);
-    const refund = (signer: KeyPairSigner) =>
-      ix("refund", {}, [
-        { address: signer.address, signer, writable: true },
-        { address: second.offer, writable: true },
-        { address: makerA, writable: true },
-        { address: second.vault, writable: true },
-        { address: TOKEN },
-      ]);
+    const second = await open(2n);
+    const refund = (who: KeyPairSigner) => t.ix("refund", {}, { maker: who, offer: second.offer, makerTokenA, vault: second.vault });
     // EscrowError.WrongMaker (third member, 6002): only the maker refunds.
-    expect(errorCode(await send(taker, [refund(taker)]))).toBe(6002);
-    expect(await send(maker, [refund(maker)])).toBeInstanceOf(TransactionMetadata);
-    expect([balance(makerA), svm.getAccount(second.offer).exists]).toEqual([600n, false]);
+    expect(t.errorCode(await t.send(taker, refund(taker)))).toBe(6002);
+    t.ok(await t.send(maker, refund(maker)));
+    expect([balance(makerTokenA), await t.account("Offer", second.offer)]).toEqual([600n, null]);
   });
 `,
         }),