@typesol/cli 0.13.0 → 0.15.0

package/CHANGELOG.md

@@ -5,6 +5,40 @@ until 1.0, a minor version may change the language, the IDL layout or error code
 
 ## Unreleased
 
+## 0.15.0 — 2026-10-27
+
+Project templates for `typesol init`, a mainnet deployment guide, and clearer `typesol idl publish` failures. No
+language, IDL or error-code changes. Not externally audited (see SECURITY.md).
+
+### Added
+- `typesol init --template counter|vault|escrow`: start from a PDA counter (the default, as before), a SOL vault or an
+  SPL token escrow. Each template is the matching `examples/` program with a LiteSVM test of its main flow and of a
+  refused call; the escrow project also gets `@solana-program/token`.
+
+### Fixed
+- `typesol idl publish` names the reason a write failed (the transaction's error and its last log lines) instead of
+  "The provided transaction plan failed to execute".
+
+### Docs
+- docs/mainnet.md: from `typesol init` to a verified program on mainnet-beta (wallet, cost, deploy, IDL, `verify`,
+  freezing and closing).
+- README: the official escrow on mainnet-beta in all four versions, with each transaction's compute units linked to
+  Solscan; the TypeSOL program's IDL is published on chain.
+
+## 0.14.0 — 2026-10-27
+
+PDAs are derived without the PDA syscalls, so instructions that create, check or search for PDAs use up to a few
+thousand fewer compute units. No language, IDL or error-code changes. Not externally audited (see SECURITY.md).
+
+### Performance
+- PDAs are derived with the `sol_sha256` and `sol_curve_validate_point` syscalls instead of
+  `sol_try_find_program_address` / `sol_create_program_address` (1,500 CU per bump tried): the
+  same addresses, bumps and limits (16 seeds to check, 15 to search, 32 bytes each). `init` with seeds, `Seeds<…>`,
+  `create`, `signer` and `findProgramAddress` all use it. Benchmarks: counter.initialize 3,030 → 1,872 CU,
+  escrow.make 5,974 → 3,638; in the official examples escrow take_offer 14,519 → 7,117 and close_user 1,728 → 586.
+  Binaries grow 0.4–1.2 KB. New tests compare it with @solana/kit's derivation over random seeds, canonical bumps
+  below 255 and on-curve bumps. Needs the curve25519 syscalls (active on mainnet-beta since epoch 637).
+
 ## 0.13.0 — 2026-10-27
 
 Every program in solana-developers/program-examples now ports to TypeSOL: PDA seeds from account fields, remaining

package/README.md

@@ -152,6 +152,9 @@ npx typesol build                             # target/counter/{counter.so, coun
 npx typesol deploy --url http://127.0.0.1:8899 --keypair ~/.config/solana/id.json
 ```
 
+`--template vault` or `--template escrow` starts from a SOL vault or an SPL token escrow instead of the counter, each
+with a passing LiteSVM test.
+
 The npm package is [`@typesol/cli`](https://www.npmjs.com/package/@typesol/cli). Projects install it under the name
 `typesol`, which is what programs import (`import { … } from "typesol"`); `typesol init` sets that up. To add it to an
 existing project: `npm install -D typesol@npm:@typesol/cli`.
@@ -159,6 +162,8 @@ existing project: `npm install -D typesol@npm:@typesol/cli`.
 Deploying again upgrades the program in place. Keep `target/deploy/<name>-keypair.json`: that keypair is your
 program's address.
 
+To go to mainnet (wallet, cost, deploy, IDL, verification), follow [docs/mainnet.md](docs/mainnet.md).
+
 ## How it works
 
 ```
@@ -227,24 +232,46 @@ shows mean compute units per call (generated by `scripts/readme-bench.ts` from t
 <!-- bench:table -->
 | Instruction | TypeSOL | Pinocchio 0.10 | Native Rust | Anchor 1.0.2 |
 | --- | ---: | ---: | ---: | ---: |
-| counter.initialize | **3,030** | 3,186 | 4,601 | 6,573 |
+| counter.initialize | **1,872** | 3,186 | 4,601 | 6,573 |
 | counter.increment | **110** | 113 | 857 | 2,323 |
-| vault.open | **3,044** | 3,185 | 4,613 | 6,627 |
+| vault.open | **1,891** | 3,185 | 4,613 | 6,627 |
 | vault.deposit | **1,314** | 1,377 | 2,832 | 4,355 |
 | vault.withdraw | **315** | 370 | 1,176 | 3,628 |
 | vault.shut | **161** | 167 | 950 | 2,024 |
-| escrow.make | **5,974** | 6,179 | 9,240 | 13,304 |
+| escrow.make | **3,638** | 6,179 | 9,240 | 13,304 |
 | escrow.take | **4,035** | 4,051 | 8,500 | 14,365 |
 | escrow.refund | **2,716** | 2,769 | 5,695 | 8,449 |
-| binary, counter / vault / escrow | 12.8 / 16.1 / 23.5 KB | 19.6 / 22.9 / 29.4 KB | 27.9 / 35.0 / 46.5 KB | 145.2 / 158.9 / 190.7 KB |
+| binary, counter / vault / escrow | 13.2 / 16.5 / 24.0 KB | 19.6 / 22.9 / 29.4 KB | 27.9 / 35.0 / 46.5 KB | 145.2 / 158.9 / 190.7 KB |
 <!-- /bench:table -->
 
-`initialize`, `open` and `make` include the PDA bump search, which costs the same in every implementation. The
+`initialize`, `open` and `make` include the PDA bump search. TypeSOL hashes PDA candidates with the sha256 and
+curve-check syscalls instead of the 1,500-CU PDA syscalls the others call, with the same results. The
 escrow moves SPL tokens through CPIs (`take` makes three). Like Pinocchio, TypeSOL reads accounts in place and builds
 CPI account records only for the accounts a call lists. It uses fewer compute units than Pinocchio on every
 instruction here, while also refusing duplicate writable accounts as Anchor does. Fewer compute
 units are not a safety claim. The differential tests also run the escrow against its Anchor twin ([docs/testing.md](docs/testing.md)).
 
+### On mainnet
+
+The official escrow ([tokens/escrow](https://github.com/solana-developers/program-examples/tree/de090195e4de698e150572c4f886c333323a64a5/tokens/escrow)),
+deployed to Solana mainnet-beta in all four versions on 2026-10-27 and called with the same mints, amounts and accounts,
+one instruction per transaction. Each figure is the compute units of that transaction, linked to Solscan; the lowest per row is in bold. The deployed
+programs match these builds byte for byte (`typesol verify` for TypeSOL), and the TypeSOL program's IDL is published
+on chain with `typesol idl publish`.
+
+| Transaction | TypeSOL | Pinocchio | Native Rust | Anchor |
+| --- | ---: | ---: | ---: | ---: |
+| make_offer (offer 1) | [20,304](https://solscan.io/tx/32PVva77dT1rSWrMWX2sHTMPZiwztdEZYtpANaxrsuJxPcd3hnV6pDgJJaV4LkL3bX6ALDoHMNF8fjngtodYHBS1) | [**19,645**](https://solscan.io/tx/528BdMTrnLWauSXVh2vaFfy4XwKFpbyt95hQ6w3fwjtpkT85RPkRhGydunAizNDRqTTLPxcEVMrdcDvRer4H9LRE) | [30,698](https://solscan.io/tx/4MQgt75MvojaAkfxnvrE2yJWabGpE8bsZhNq2CeGJxHZg6uD6A64Kv71JmrsgiGnaEovvv8K34DYL49owLjhs4QJ) | [38,648](https://solscan.io/tx/9T1ZY9JaSMb1GMqv1i22AuZuJQN6B5XcgqeDv5tGqEm5Uox3MBTdXsECt59GwcXkFG9QKgXJyqndTEzpSXhbAVM) |
+| take_offer (offer 1) | [**7,998**](https://solscan.io/tx/49EQwgnKShFdsAs37AEzYmv6tLY8DipcCjmRgqwj4fVTFEgVVWdEXw5AvuEufL5ymJYs4T4hVFdkENW9XK9een5m) | [25,206](https://solscan.io/tx/21MGkXpKRe4c7EeA1hC6JHevsk78xUdbcWmyqG47EbLeCNKSMTzTjkJQqtydnQmV8uHPmr6bJHnvQmmQTSZB7Am2) | [28,612](https://solscan.io/tx/B1hu1EL4Y5vWhBVWdyZEpzRNJb8kd6G9CgN7KtyNNGpQ84o9dfn1sdy9Z1UCHECNtp24Mw8bEH2iYz2YADdEUjx) | [32,835](https://solscan.io/tx/3ZLuQQz7Bx5YdgmFXpVQWHn5kyc8v39jr2BnfofH6sqenzfJpAdVm4h38uYcHwYygnfso92kJe7HRHeASsABoKPQ) |
+| make_offer (offer 2) | [21,804](https://solscan.io/tx/xuu9KXbZvzGDpTEEcDE9LYvBqmPen81y6ty92e6crRxT8m4Mc4XyxhjWHbjVNsr9RE3QY4M1j1Sw9cH7PRMKKuc) | [**19,645**](https://solscan.io/tx/LLzS13AJrqACGoT1VHZN278ij39pNkttb1Z4Wh2AYXknWxwjaiaiMeD7WZomjP6TBv18RHfQHUfogQzApvXr2mC) | [35,198](https://solscan.io/tx/4xiKfzyccVatef1T52tZ3VAJwcx5R7iWgHWezBzZ3p2WpvoLzMp1PSUgr7x3sspE53mDE5JaghaNPKuUohVgPuwc) | [47,648](https://solscan.io/tx/4mxW8D5zpY8t4fL8JRbvhp6ejU6CUvB3iWmFjACipzexW6tZfFeatfnEnDTX3Y97BxsvAftoX9eQauiVu84xrLxh) |
+| refund_offer (offer 2) | [**5,961**](https://solscan.io/tx/4kY7s3y95Lrd2WGCWGPWW3zFBVtEKH6EskdscuYmRCRRgPt2rJTZ1CmZMGUUkHs7aai9AygEiTSUG23EMUrFr7rg) | [13,387](https://solscan.io/tx/QUXWwdbKRcT6WhZvSe4U8nxr4GAMaPNV6pZ1fwrC28kRxdJm7HKXVr2DFRuKD9bEzoS6hFdiA2rLr1mQWyrN3oz) | [17,731](https://solscan.io/tx/5zj7E4c61j1JzUsUPC1fNs9ECFLVmCug9rsdYsVLn7YD1RSxdbAJUQDam1BX3epTzW6ed2uFGwTiNhwaYo7vqdwm) | [23,576](https://solscan.io/tx/5Kjwnq5tN8mzj5s67VGxSry4kRzZk6HLdgXW65FyTvpUeC1D7aQoDGTwzrA7kqyYEvV9y9znnZmLaqU98zFrJJo4) |
+| program | [65ybkcg6…](https://solscan.io/account/65ybkcg6mQa9t5EuHtirRdvf2qAu12qRiK6wYBbGk16P) | [FrQwq3iU…](https://solscan.io/account/FrQwq3iUa8ZkWEne1y27webXTAyLgH4Hj6t986t6VS2G) | [5pnmi1Md…](https://solscan.io/account/5pnmi1MdxzXKmgX7ooRSE212rzZK8rb7nNpRTSMqP8V1) | [EG7M3sLL…](https://solscan.io/account/EG7M3sLLwB7MhmtzwYsaxbhZaFDbshL9hmVK79bQVyVq) |
+
+Most of make_offer is the Associated Token Account program creating the vault (about 13,500 CU in every version); it
+searches for the vault address's bump itself at 1,500 CU a try, which is why TypeSOL's offer 2 cost 1,500 more than
+offer 1 (its own part was 6,719 CU both times). The Pinocchio version takes the offer PDA's bump from the client instead
+of searching for it (its own part: 6,051 CU). Mainnet figures differ from the LiteSVM means above.
+
 ## How it is tested
 
 - **Execution tests.** Every feature is compiled and run in LiteSVM.
@@ -275,7 +302,7 @@ Details are in [docs/testing.md](docs/testing.md).
 
 ## Status
 
-**TypeSOL is pre-1.0 (0.13).** Releases follow the organization's
+**TypeSOL is pre-1.0 (0.15).** Releases follow the organization's
 [versioning policy](https://github.com/typesol/.github/blob/main/VERSIONING.md); [CHANGELOG.md](CHANGELOG.md) lists every
 change.
 - The compiler, runtime and tooling have been through internal security reviews and are covered by the tests above.

package/dist/cli.js

@@ -11,6 +11,7 @@ import { generateClient, writeClient } from "./clientgen.js";
 import { buildIdl } from "./compiler/idl.js";
 import { decodeAddress, loadOrCreateKeypair, readKeypair } from "./keys.js";
 import { formatProfile, profileLogs } from "./profile.js";
+import { TEMPLATE_NAMES } from "./templates.js";
 import { buildWorkspace, CONFIG, deployArgs, findWorkspace, programAddress, programForEntry, programPaths, scaffold } from "./workspace.js";
 const ASSETS = fileURLToPath(new URL("../assets/", import.meta.url));
 /** A usage problem: printed with the command's help, exit code 2. */
@@ -38,14 +39,23 @@ function banner() {
 const SBPF = `--sbpf v0|v1|v2      SBPF version (default v0, or "sbpf" in ${CONFIG}); v1/v2 need clusters that enabled them`;
 const COMMANDS = {
     init: {
-        usage: "typesol init [<dir>] [--name <program>]",
-        help: "Create a project: typesol.json, programs/<name>.ts, tests/<name>.test.ts (LiteSVM), package.json, tsconfig.json, .gitignore.\n  Refuses to overwrite files. <name> must be snake_case (default: derived from <dir>).",
-        options: { name: { type: "string" } },
+        usage: "typesol init [<dir>] [--name <program>] [--template counter|vault|escrow]",
+        help: [
+            "Create a project: typesol.json, programs/<name>.ts, tests/<name>.test.ts (LiteSVM), package.json, tsconfig.json, .gitignore.",
+            "Refuses to overwrite files. <name> must be snake_case (default: derived from <dir>).",
+            "--template counter   a PDA counter per user (default)",
+            "--template vault     a SOL vault at a PDA: deposit, withdraw above rent, close",
+            "--template escrow    an SPL token escrow: make, take, refund, with the offer PDA signing for its vault",
+        ].join("\n  "),
+        options: { name: { type: "string" }, template: { type: "string" } },
         run(v, args) {
             if (args.length > 1)
                 throw new UsageError("init takes at most one directory");
             if (v.name !== undefined && !/^[a-z][a-z0-9_]*$/.test(v.name))
                 throw new UsageError(`--name "${v.name}" must be snake_case (a-z, 0-9, _; starting with a letter)`);
+            const template = v.template ?? "counter";
+            if (!TEMPLATE_NAMES.includes(template))
+                throw new UsageError(`--template "${template}" is not one of ${TEMPLATE_NAMES.join(", ")}`);
             const root = path.resolve(args[0] ?? ".");
             const derived = path
                 .basename(root)
@@ -53,7 +63,7 @@ const COMMANDS = {
                 .replace(/^_+|_+$/g, "")
                 .toLowerCase();
             const name = v.name ?? (/^[a-z]/.test(derived) ? derived : `p_${derived || "program"}`);
-            for (const f of scaffold(root, name))
+            for (const f of scaffold(root, name, template))
                 log(`  created ${path.join(root, f)}`);
             log(`\n  next: cd ${path.relative(process.cwd(), root) || "."} && npm install && npm test`);
             return 0;

package/dist/compiler/emit/calls.js

@@ -361,7 +361,7 @@ export class CallEmitter extends ExpressionEmitter {
                 const t = this.tmp("pda");
                 const b = this.tmp("bump");
                 this.line(`SolPubkey ${t}; uint8_t ${b};`);
-                this.line(`if (sol_try_find_program_address(${seeds.name}, ${seeds.count}, ${program.c}, &${t}, &${b}) != SUCCESS) TS_FAIL(TS_ERR_SEEDS, "TypeSOL: no program address for these seeds");`);
+                this.line(`if (ts_find_pda(${seeds.name}, ${seeds.count}, ${program.c}, &${t}, &${b}) != SUCCESS) TS_FAIL(TS_ERR_SEEDS, "TypeSOL: no program address for these seeds");`);
                 return { c: `(&${t})`, type: PUBKEY };
             }
             case "metadataAddress": {

package/dist/compiler/emit/function.js

@@ -444,7 +444,7 @@ export class FunctionEmitter extends StatementEmitter {
                 else {
                     bumpDecls.push(`  uint8_t sb_${a.name}; (void)sb_${a.name};`);
                     out.push(`  { SolPubkey pda_${a.name};`);
-                    out.push(`    if (sol_try_find_program_address(${seeds}, ${parts.length}, ${program}, &pda_${a.name}, &sb_${a.name}) != SUCCESS || !ts_key_eq(&pda_${a.name}, &a_${a.name}->key)) TS_FAIL(TS_ERR_SEEDS, "TypeSOL: ${a.name} is not the expected PDA"); }`);
+                    out.push(`    if (ts_find_pda(${seeds}, ${parts.length}, ${program}, &pda_${a.name}, &sb_${a.name}) != SUCCESS || !ts_key_eq(&pda_${a.name}, &a_${a.name}->key)) TS_FAIL(TS_ERR_SEEDS, "TypeSOL: ${a.name} is not the expected PDA"); }`);
                     this.bumps.set(a.name, `sb_${a.name}`);
                 }
             }

package/dist/idlpublish.js

@@ -62,17 +62,51 @@ export async function publishIdl(chain, opts) {
             seeds: [getAddressEncoder().encode(opts.program)],
         }))[0]
         : undefined;
-    await writeMetadata(client, {
-        payer: opts.payer,
-        authority,
-        program: opts.program,
-        ...(programData ? { programData } : {}),
-        seed: "idl",
-        format: Format.Json,
-        ...packed,
-    });
+    try {
+        await writeMetadata(client, {
+            payer: opts.payer,
+            authority,
+            program: opts.program,
+            ...(programData ? { programData } : {}),
+            seed: "idl",
+            format: Format.Json,
+            ...packed,
+        });
+    }
+    catch (e) {
+        throw new Error(planFailure(e));
+    }
     return metadataAddress(opts.program, canonical ? null : authority.address);
 }
+/**
+ * The transaction planner reports a failed write as "The provided transaction plan failed to execute" and keeps the
+ * reason inside: name the first failed transaction's own error instead.
+ */
+function planFailure(e) {
+    const seen = new Set();
+    const messages = [];
+    let logs = [];
+    const walk = (v, depth) => {
+        if (!v || typeof v !== "object" || seen.has(v) || depth > 8)
+            return;
+        seen.add(v);
+        const o = v;
+        if (Array.isArray(o.logs) && !logs.length)
+            logs = o.logs.map(String);
+        if (v instanceof Error && v.message && !/transaction plan failed to execute/.test(v.message))
+            messages.push(v.message);
+        for (const k of ["transactionPlanResult", "plans", "error", "cause", "context"]) {
+            const c = o[k];
+            if (Array.isArray(c))
+                c.forEach((x) => walk(x, depth + 1));
+            else
+                walk(c, depth + 1);
+        }
+    };
+    walk(e, 0);
+    const tail = logs.length ? `\n  ${logs.slice(-6).join("\n  ")}` : "";
+    return messages.length ? `IDL write failed: ${messages[0]}${tail}` : e instanceof Error ? e.message : String(e);
+}
 export async function metadataAddress(program, authority) {
     return (await findMetadataPda({ program, authority, seed: "idl" }))[0];
 }

package/dist/templates.d.ts

@@ -0,0 +1,9 @@
+export declare const TEMPLATE_NAMES: readonly ["counter", "vault", "escrow"];
+export type TemplateName = (typeof TEMPLATE_NAMES)[number];
+export interface Template {
+    program: string;
+    test: (name: string) => string;
+    /** devDependencies beyond the ones every project gets. */
+    devDependencies?: Record<string, string>;
+}
+export declare const TEMPLATES: Record<TemplateName, Template>;

package/dist/templates.js

@@ -0,0 +1,429 @@
+// Programs and tests that `typesol init --template <name>` writes. Each test runs its program in LiteSVM and covers its
+// 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. */
+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";
+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;
+  };
+  /** 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 = {
+    counter: {
+        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;
+}
+
+/** Read-only check that callers can simulate. */
+export function assertAtLeast(counter: Account<Counter>, min: u64): void {
+  require(counter.count >= min, "counter is below the expected minimum");
+}
+`,
+        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");
+
+    // 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);
+  });
+`,
+        }),
+    },
+    vault: {
+        program: `import {
+  type Init,
+  type Mut,
+  type Pubkey,
+  type Signer,
+  type SystemProgram,
+  type u8,
+  type u64,
+  close,
+  minimumBalance,
+  require,
+} from "typesol";
+
+/** A personal SOL vault at PDA ["vault", owner]. Lamports above rent are the balance. */
+export interface Vault {
+  owner: Pubkey;
+  deposited: u64;
+  withdrawn: u64;
+  bump: u8;
+}
+
+export enum VaultError {
+  NotOwner = "Only the vault owner can do this",
+  ZeroAmount = "Amount must be greater than zero",
+  InsufficientFunds = "Withdrawal would dip below the rent-exempt minimum",
+}
+
+export function open(owner: Mut<Signer>, vault: Init<Vault>, systemProgram: SystemProgram): void {
+  vault.bump = vault.create(owner, ["vault", owner.key]);
+  vault.owner = owner.key;
+}
+
+export function deposit(owner: Mut<Signer>, vault: Mut<Vault>, systemProgram: SystemProgram, amount: u64): void {
+  require(amount > 0n, VaultError.ZeroAmount);
+  require(vault.owner === owner.key, VaultError.NotOwner);
+  systemProgram.transfer(owner, vault, amount);
+  vault.deposited += amount;
+}
+
+export function withdraw(owner: Mut<Signer>, vault: Mut<Vault>, amount: u64): void {
+  require(amount > 0n, VaultError.ZeroAmount);
+  require(vault.owner === owner.key, VaultError.NotOwner);
+  const floor = minimumBalance(vault);
+  require(vault.lamports - amount >= floor, VaultError.InsufficientFunds);
+  // The vault is owned by this program, so it can move lamports directly.
+  vault.lamports -= amount;
+  owner.lamports += amount;
+  vault.withdrawn += amount;
+}
+
+/** Close the vault and return everything, rent included, to the owner. */
+export function shut(owner: Mut<Signer>, vault: Mut<Vault>): void {
+  require(vault.owner === owner.key, VaultError.NotOwner);
+  close(vault, owner);
+}
+`,
+        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);
+
+    // 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(await send(owner, [ix("shut", {}, [me, v])])).toBeInstanceOf(TransactionMetadata);
+    expect(svm.getAccount(vault).exists).toBe(false);
+  });
+
+  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,
+    );
+    // VaultError.NotOwner: 6000.
+    expect(errorCode(await send(thief, [ix("shut", {}, [{ address: thief.address, signer: thief, writable: true }, v])]))).toBe(6000);
+  });
+`,
+        }),
+    },
+    escrow: {
+        program: `import {
+  type AccountInfo,
+  type Init,
+  type Mut,
+  type Pubkey,
+  type Signer,
+  type SystemProgram,
+  type TokenAccount,
+  type TokenProgram,
+  type u8,
+  type u64,
+  close,
+  require,
+} from "typesol";
+
+/**
+ * A maker escrows \`amountA\` of mint A and asks for \`wantB\` of mint B.
+ * Anyone can take the offer atomically; the maker can refund while it is open.
+ *
+ * The client creates \`vault\` beforehand as a token account for mint A whose
+ * owner is the offer PDA ["offer", maker, seed].
+ */
+export interface Offer {
+  maker: Pubkey;
+  mintA: Pubkey;
+  mintB: Pubkey;
+  vault: Pubkey;
+  amountA: u64;
+  wantB: u64;
+  seed: u64;
+  bump: u8;
+}
+
+export enum EscrowError {
+  ZeroAmount = "Amounts must be greater than zero",
+  BadVault = "Vault must be an empty token account owned by the offer",
+  WrongMaker = "Maker does not match the offer",
+  WrongVault = "Vault does not match the offer",
+  WrongMint = "Token account has the wrong mint",
+  WrongRecipient = "Maker's token account is not owned by the maker",
+}
+
+export function make(
+  maker: Mut<Signer>,
+  offer: Init<Offer>,
+  makerTokenA: Mut<TokenAccount>,
+  vault: Mut<TokenAccount>,
+  systemProgram: SystemProgram,
+  tokenProgram: TokenProgram,
+  seed: u64,
+  amountA: u64,
+  wantB: u64,
+  mintB: Pubkey,
+): void {
+  offer.bump = offer.create(maker, ["offer", maker.key, seed]);
+  require(amountA > 0n && wantB > 0n, EscrowError.ZeroAmount);
+  require(vault.owner === offer.key && vault.mint === makerTokenA.mint && vault.amount === 0n, EscrowError.BadVault);
+
+  tokenProgram.transfer(makerTokenA, vault, maker, amountA);
+
+  offer.maker = maker.key;
+  offer.mintA = makerTokenA.mint;
+  offer.mintB = mintB;
+  offer.vault = vault.key;
+  offer.amountA = amountA;
+  offer.wantB = wantB;
+  offer.seed = seed;
+}
+
+export function take(
+  taker: Mut<Signer>,
+  maker: Mut<AccountInfo>,
+  offer: Mut<Offer>,
+  takerTokenA: Mut<TokenAccount>,
+  takerTokenB: Mut<TokenAccount>,
+  makerTokenB: Mut<TokenAccount>,
+  vault: Mut<TokenAccount>,
+  tokenProgram: TokenProgram,
+): void {
+  require(offer.maker === maker.key, EscrowError.WrongMaker);
+  require(offer.vault === vault.key, EscrowError.WrongVault);
+  require(takerTokenA.mint === offer.mintA && takerTokenB.mint === offer.mintB, EscrowError.WrongMint);
+  require(makerTokenB.mint === offer.mintB, EscrowError.WrongMint);
+  require(makerTokenB.owner === offer.maker, EscrowError.WrongRecipient);
+
+  tokenProgram.transfer(takerTokenB, makerTokenB, taker, offer.wantB);
+  tokenProgram.transfer(vault, takerTokenA, offer, offer.amountA, ["offer", offer.maker, offer.seed, offer.bump]);
+  tokenProgram.closeAccount(vault, maker, offer, ["offer", offer.maker, offer.seed, offer.bump]);
+  close(offer, maker);
+}
+
+export function refund(
+  maker: Mut<Signer>,
+  offer: Mut<Offer>,
+  makerTokenA: Mut<TokenAccount>,
+  vault: Mut<TokenAccount>,
+  tokenProgram: TokenProgram,
+): void {
+  require(offer.maker === maker.key, EscrowError.WrongMaker);
+  require(offer.vault === vault.key, EscrowError.WrongVault);
+  require(makerTokenA.mint === offer.mintA, EscrowError.WrongMint);
+
+  tokenProgram.transfer(vault, makerTokenA, offer, offer.amountA, ["offer", offer.maker, offer.seed, offer.bump]);
+  tokenProgram.closeAccount(vault, maker, offer, ["offer", offer.maker, offer.seed, offer.bump]);
+  close(offer, maker);
+}
+`,
+        test: (name) => testFile(name, {
+            imports: `import { AccountState, getMintEncoder, getMintSize, getTokenDecoder, getTokenEncoder, getTokenSize } from "@solana-program/token";\n`,
+            kit: ["generateKeyPairSigner", "getAddressEncoder", "getProgramDerivedAddress", "lamports"],
+            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()) });
+    return address;
+  };
+  /** 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({
+      mint: mintAddress,
+      owner,
+      amount,
+      delegate: null,
+      state: AccountState.Initialized,
+      isNative: null,
+      delegatedAmount: 0n,
+      closeAuthority: null,
+    });
+    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);
+    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 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 open = async (seed: number) => {
+      const [offer] = await getProgramDerivedAddress({
+        programAddress: programId,
+        seeds: ["offer", getAddressEncoder().encode(maker.address), new Uint8Array(new BN(seed).toArray("le", 8))],
+      });
+      // 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);
+      return { offer, vault };
+    };
+
+    const first = await open(1);
+    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]);
+
+    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 },
+      ]);
+    // 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]);
+  });
+`,
+        }),
+        devDependencies: { "@solana-program/token": "~0.18.0" },
+    },
+};

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,19 @@ 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"] },
             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 +133,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/cli.md

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

package/docs/mainnet.md

@@ -0,0 +1,99 @@
+# Deploy to mainnet
+
+From an empty directory to a program on Solana mainnet-beta: create, test, deploy, publish the IDL, then check that
+the deployed binary is the one your source builds. The program here is the counter that `typesol init` creates
+(13.5 KB); any TypeSOL project works the same way.
+
+You need Node.js 22.12 or later and the Agave CLI with platform-tools (see the README's Requirements).
+
+## 1. Create and test
+
+```sh
+npx @typesol/cli init my-app
+cd my-app
+npm install
+npm test
+```
+
+`npm test` runs `tests/my_app.test.ts` in LiteSVM: it compiles the program and calls it, with no validator or SOL.
+Write your program in `programs/my_app.ts` and keep the tests passing before you spend anything.
+
+## 2. Build
+
+```sh
+npx typesol build
+```
+
+This writes `target/my_app/`: the program (`my_app.so`), its Anchor IDL (`my_app.json`), a TypeScript client
+(`my_app.client.ts`) and the generated C. The first build also creates `target/deploy/my_app-keypair.json`, the
+program's address, and records the address in `typesol.json`.
+
+**Back up `target/deploy/my_app-keypair.json` now.** It is not committed (`.gitignore`), and without it you cannot
+redeploy to that address.
+
+## 3. A wallet with SOL
+
+```sh
+solana-keygen new -o ~/.config/solana/deployer.json
+solana config set --url mainnet-beta --keypair ~/.config/solana/deployer.json
+solana address
+```
+
+Send SOL to that address. Most of what a deploy costs is rent for the program's bytes, which you get back if you
+ever close the program:
+
+```sh
+solana rent $(wc -c < target/my_app/my_app.so)
+```
+
+The counter needs 0.069 SOL of rent. During the deploy the program is first written to a buffer account that holds
+the same amount again; it is returned when the deploy finishes. Fund about twice the rent plus 0.01 SOL for fees.
+
+The public mainnet RPC is rate-limited; for deploys, set `--url` (or `solana config set --url`) to your RPC
+provider's endpoint.
+
+## 4. Deploy
+
+```sh
+npx typesol deploy --dry-run   # builds and prints the solana command it will run
+npx typesol deploy
+```
+
+It runs `solana program deploy` at the address in `target/deploy/my_app-keypair.json`, with your wallet as payer and
+upgrade authority, and prints the program id. Deploying again upgrades the program in place.
+
+If a deploy stops part-way, the buffer stays behind with its SOL. The error prints the buffer's address; recover it
+with `solana program close <buffer address>`, or list yours with `solana program show --buffers`.
+
+## 5. Publish the IDL
+
+```sh
+npx typesol idl publish
+```
+
+It writes the IDL to the Program Metadata program, signed by the upgrade authority, where Anchor clients and
+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
+```
+
+`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.
+
+## 7. Call it
+
+`target/my_app/my_app.client.ts` builds the program's instructions on `@solana/kit`; see [client.md](client.md).
+
+## Later
+
+- **Freeze it.** `solana program set-upgrade-authority <program id> --final` makes the program immutable. It cannot
+  be undone.
+- **Close it.** `solana program close <program id> --bypass-warning` returns the rent to the authority. The program
+  id can never be used again.
+
+A worked example: the official escrow, deployed to mainnet in TypeSOL, Pinocchio, native Rust and Anchor, with every
+transaction linked, is in the README's [On mainnet](../README.md#on-mainnet) section.

package/docs/troubleshooting.md

@@ -23,5 +23,6 @@ compiler's checks log their TypeScript location, e.g. `TypeSOL: arithmetic overf
 **Heap errors (5110) building strings** — strings are allocated on a 32 KiB heap and never freed. Build less text,
 or declare `const HEAP_SIZE_KIB = 64n` and add a ComputeBudget `requestHeapFrame` instruction to the transaction.
 
-**`typesol idl publish` fails on a local validator with "invalid instruction data"** — older validators reject a
-System instruction the current Program Metadata program uses; it works on clusters with current Agave versions.
+**`typesol idl publish` fails on a local validator with "invalid instruction data"** — the System Program of
+`solana-test-validator` (Agave 3.1 included) rejects a System instruction that the current Program Metadata program
+uses. Publishing works on mainnet-beta. The error shows the failing transaction's last log lines.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@typesol/cli",
-  "version": "0.13.0",
+  "version": "0.15.0",
   "description": "Compile a TypeScript-syntax language directly to Solana SBF programs.",
   "type": "module",
   "license": "MIT",

package/runtime/typesol_rt.h

@@ -305,6 +305,55 @@ static inline __attribute__((always_inline)) uint64_t ts_invoke(TsParams *params
   return sol_invoke_signed(ix, infos, ix->account_len, signers, nsigners);
 }
 
+/*
+ * ---- Program derived addresses ------------------------------------------------
+ * The same addresses sol_create_program_address / sol_try_find_program_address compute — sha256 of the seeds, the
+ * program id and "ProgramDerivedAddress", valid only off the ed25519 curve — from the sha256 and curve-validation
+ * syscalls, which cost a fraction of the 1500 compute units the PDA syscalls charge per attempt. The seed limits are the
+ * syscalls' (at most 16 seeds of at most 32 bytes, the bump included), and so is the result for every input.
+ */
+uint64_t sol_curve_validate_point(uint64_t curve_id, const uint8_t *point, uint8_t *result);
+#define TS_MAX_PDA_SEEDS 16
+
+/* The address of `seeds` (and `bump`, when given) under `program`; false when it lies on the curve (no PDA). */
+static inline bool ts_pda_hash(const SolSignerSeed *seeds, int n, const uint8_t *bump, const SolPubkey *program, SolPubkey *out) {
+  SolBytes parts[TS_MAX_PDA_SEEDS + 2];
+  int k = 0;
+  for (int i = 0; i < n; i++) parts[k++] = (SolBytes){seeds[i].addr, seeds[i].len};
+  if (bump) parts[k++] = (SolBytes){bump, 1};
+  parts[k++] = (SolBytes){program->x, 32};
+  parts[k++] = (SolBytes){(const uint8_t *)"ProgramDerivedAddress", 21};
+  sol_sha256(parts, k, out->x);
+  uint8_t ignored;
+  return sol_curve_validate_point(0 /* CURVE25519_EDWARDS */, out->x, &ignored) != 0; /* 0: a valid curve point */
+}
+
+static inline bool ts_pda_seeds_ok(const SolSignerSeed *seeds, int n, int max) {
+  if (n > max) return false;
+  for (int i = 0; i < n; i++)
+    if (seeds[i].len > 32) return false;
+  return true;
+}
+
+/* sol_create_program_address: the bump is the last of `seeds`. */
+static inline uint64_t ts_create_pda_address(const SolSignerSeed *seeds, int n, const SolPubkey *program, SolPubkey *out) {
+  if (!ts_pda_seeds_ok(seeds, n, TS_MAX_PDA_SEEDS) || !ts_pda_hash(seeds, n, NULL, program, out)) return 1; /* not SUCCESS: the PDA syscalls fail the same inputs */
+  return SUCCESS;
+}
+
+/* sol_try_find_program_address: the canonical (highest) bump. */
+static inline uint64_t ts_find_pda(const SolSignerSeed *seeds, int n, const SolPubkey *program, SolPubkey *out, uint8_t *bump_out) {
+  if (!ts_pda_seeds_ok(seeds, n, TS_MAX_PDA_SEEDS - 1)) return 1; /* not SUCCESS: the PDA syscalls fail the same inputs */
+  for (int b = 255; b >= 0; b--) {
+    uint8_t bump = (uint8_t)b;
+    if (ts_pda_hash(seeds, n, &bump, program, out)) {
+      *bump_out = bump;
+      return SUCCESS;
+    }
+  }
+  return 1; /* not SUCCESS: the PDA syscalls fail the same inputs */
+}
+
 /* ---- Account checks ------------------------------------------------------ */
 /* Copy between two places of the same type: distinct, or the very same place (then nothing to do). */
 static inline void ts_copy(void *dst, const void *src, uint64_t n) {
@@ -461,7 +510,7 @@ static inline uint64_t ts_check_program_data(const TsAccount *a, const SolPubkey
   SolSignerSeed seed = {(const uint8_t *)program_id, 32};
   SolPubkey expected;
   uint8_t bump;
-  if (sol_try_find_program_address(&seed, 1, &TS_BPF_UPGRADEABLE_LOADER_ID, &expected, &bump) != SUCCESS || !ts_key_eq(&expected, &a->key))
+  if (ts_find_pda(&seed, 1, &TS_BPF_UPGRADEABLE_LOADER_ID, &expected, &bump) != SUCCESS || !ts_key_eq(&expected, &a->key))
     TS_FAIL(TS_ERR_ADDRESS, "TypeSOL: not this program's ProgramData account");
   return SUCCESS;
 }
@@ -471,7 +520,7 @@ static const uint8_t TS_EVENT_IX_TAG[8] = {0xe4, 0x45, 0xa5, 0x2e, 0x51, 0xcb, 0
 static inline uint64_t ts_check_event_authority(const TsAccount *a, const SolPubkey *program_id, uint8_t *bump) {
   SolSignerSeed seed = {(const uint8_t *)"__event_authority", 17};
   SolPubkey expected;
-  if (sol_try_find_program_address(&seed, 1, program_id, &expected, bump) != SUCCESS || !ts_key_eq(&expected, &a->key))
+  if (ts_find_pda(&seed, 1, program_id, &expected, bump) != SUCCESS || !ts_key_eq(&expected, &a->key))
     TS_FAIL(TS_ERR_SEEDS, "TypeSOL: not this program's event authority");
   return SUCCESS;
 }
@@ -510,7 +559,7 @@ static inline uint64_t ts_init_zeroed(TsAccount *a, const SolPubkey *program_id,
 static inline uint64_t ts_require_pda(const TsAccount *a, const SolSignerSeed *seeds, int n,
                                       const SolPubkey *program_id) {
   SolPubkey derived;
-  if (sol_create_program_address(seeds, n, program_id, &derived) != SUCCESS || !ts_key_eq(&derived, &a->key))
+  if (ts_create_pda_address(seeds, n, program_id, &derived) != SUCCESS || !ts_key_eq(&derived, &a->key))
     TS_FAIL(TS_ERR_SEEDS, "TypeSOL: PDA seeds do not match account");
   return SUCCESS;
 }
@@ -536,7 +585,7 @@ static inline uint64_t ts_create_pda(TsParams *params, TsAccount *payer, TsAccou
                                      uint8_t *bump_out) {
   SolPubkey derived;
   uint8_t bump;
-  if (sol_try_find_program_address(seeds, n, params->program_id, &derived, &bump) != SUCCESS ||
+  if (ts_find_pda(seeds, n, params->program_id, &derived, &bump) != SUCCESS ||
       !ts_key_eq(&derived, &acct->key))
     TS_FAIL(TS_ERR_SEEDS, "TypeSOL: PDA seeds do not match account");
   if (acct->data_len != 0 || !ts_key_eq(&acct->owner, &TS_SYSTEM_PROGRAM_ID))
@@ -627,7 +676,7 @@ static inline uint64_t ts_create_pda_if_needed(TsParams *params, TsAccount *paye
   if (ts_key_eq(&acct->owner, params->program_id)) {
     SolPubkey derived;
     uint8_t bump;
-    if (sol_try_find_program_address(seeds, n, params->program_id, &derived, &bump) != SUCCESS ||
+    if (ts_find_pda(seeds, n, params->program_id, &derived, &bump) != SUCCESS ||
         !ts_key_eq(&derived, &acct->key))
       TS_FAIL(TS_ERR_SEEDS, "TypeSOL: PDA seeds do not match account");
     if (acct->data_len < space) TS_FAIL(TS_ERR_ACCOUNT_TOO_SMALL, "TypeSOL: account data too small");
@@ -1105,7 +1154,7 @@ static const SolPubkey TS_MPL_METADATA_ID = {{11,112,101,177,227,209,124,69,56,1
 static inline uint64_t ts_ata_address(const SolPubkey *owner, const SolPubkey *mint, const SolPubkey *token_program, SolPubkey *out) {
   SolSignerSeed seeds[3] = {{(const uint8_t *)owner, 32}, {(const uint8_t *)token_program, 32}, {(const uint8_t *)mint, 32}};
   uint8_t bump;
-  if (sol_try_find_program_address(seeds, 3, &TS_ATA_PROGRAM_ID, out, &bump) != SUCCESS)
+  if (ts_find_pda(seeds, 3, &TS_ATA_PROGRAM_ID, out, &bump) != SUCCESS)
     TS_FAIL(TS_ERR_SEEDS, "TypeSOL: cannot derive the associated token address");
   return SUCCESS;
 }
@@ -1155,7 +1204,7 @@ static inline uint64_t ts_t22_init_metadata(TsParams *params, const TsAccount *p
 static inline uint64_t ts_metadata_address(const SolPubkey *mint, SolPubkey *out) {
   SolSignerSeed seeds[3] = {{(const uint8_t *)"metadata", 8}, {(const uint8_t *)&TS_MPL_METADATA_ID, 32}, {(const uint8_t *)mint, 32}};
   uint8_t bump;
-  if (sol_try_find_program_address(seeds, 3, &TS_MPL_METADATA_ID, out, &bump) != SUCCESS)
+  if (ts_find_pda(seeds, 3, &TS_MPL_METADATA_ID, out, &bump) != SUCCESS)
     TS_FAIL(TS_ERR_SEEDS, "TypeSOL: cannot derive the metadata address");
   return SUCCESS;
 }
@@ -1225,7 +1274,7 @@ static inline uint64_t ts_update_extra_metas(TsParams *params, TsAccount *payer,
   SolSignerSeed seeds[2] = {{(const uint8_t *)"extra-account-metas", 19}, {(const uint8_t *)mint, 32}};
   SolPubkey pda;
   uint8_t bump;
-  if (sol_try_find_program_address(seeds, 2, params->program_id, &pda, &bump) != SUCCESS || !ts_key_eq(&pda, &acct->key))
+  if (ts_find_pda(seeds, 2, params->program_id, &pda, &bump) != SUCCESS || !ts_key_eq(&pda, &acct->key))
     TS_FAIL(TS_ERR_SEEDS, "TypeSOL: not the mint's extra-account-metas PDA");
   if (!ts_key_eq(&acct->owner, params->program_id)) TS_FAIL(TS_ERR_WRONG_OWNER, "TypeSOL: the extra-account-metas account is not this program's");
   if (acct->data_len < 16 || ts_ld64(acct->data) != ts_ld64(TS_TRANSFER_HOOK_EXECUTE_DISC))