@typesol/cli 0.23.0 → 0.24.0

package/CHANGELOG.md

@@ -5,6 +5,67 @@ until 1.0, a minor version may change the language, the IDL layout or error code
 
 ## Unreleased
 
+## 0.24.0 — 2026-10-28
+
+Functions as values, closures for any helper, stored `map` to structs and text, Metaplex Core external plugins, and
+the fixes and identical-result compute-unit savings from a full code review: expanded helpers see only their own
+scope, generated clients read only their program's events, and IDLs from the chain are read with limits. Not externally
+audited (see SECURITY.md).
+
+### Added
+- Functions as values: `const h = g`, and functions that return functions (`function adder(n: u64): (x: u64) => u64
+  { return (x) => x + n; }`), which make a closure where they are called (`const add5 = adder(5n)`, `adder(5n)(x)`).
+- Closures given to helpers with type parameters or accounts: the helper is expanded where it is called, its type
+  parameters bound from the call and its accounts the caller's.
+- A stored `map` to structs or text: `const ps: FixedVec<Pair, 8> = xs.map((o) => ({ qty: o.qty, doubled: o.qty * 2n }))`,
+  `const names: FixedVec<FixedString<8>, 4> = xs.map(…)`.
+- A struct argument holding a FixedVec, when the struct is only an argument: read as Anchor sends it (the FixedVec a
+  Borsh Vec), as a `@layout borsh` struct is.
+- Metaplex Core external plugin adapters: `addExternalPlugin`, `removeExternalPlugin`, `writeExternalPluginData` and
+  their Collection forms, for AppData, Oracle and LifecycleHook (and the Linked forms), checked against the Core program
+  (Core itself answers lifecycle hooks with NotAvailable for now).
+
+### Changed
+- Fewer compute units, same results: the PDA bump search builds its seed list once, a growing account reads the rent
+  sysvar once, integers become text two digits at a time, a lone `${n}` template is not copied again, and
+  `list = fixedVec([])` clears the list in place. For example escrow `make` 3638 → 3605, `take_offer` 7117 → 7058,
+  `transfer_tokens` 8467 → 8367 CU.
+- `eventsOf` takes the transaction with its account keys (`transaction.message.accountKeys`, as getTransaction returns
+  it); without them it reads log events only. `errorCode` / `isError` also read the RPC's JSON error
+  (`{ InstructionError: [0, { Custom: 6000 }] }`).
+- `svmConnection`: `accountNotifications` yields after each later transaction that names the account (no snapshot of
+  it as it is), `logsNotifications` honors `{ mentions }` and includes failed transactions (with `err`), simulation
+  errors are in the RPC's JSON shape, and `getTransaction` returns the account keys and each inner instruction's
+  program index.
+- Compiler messages about accounts with a growable Vec say "has a growable Vec" instead of "ends in a Vec", and the
+  field-type list no longer says `Vec<T> (last)`, since a Vec can be any field (0.23.0).
+
+### Fixed
+- A helper expanded where it is called (given a closure), and a function a helper made, read a module constant as
+  the instruction argument of the same name; they now see only their parameters and the module.
+- A struct parameter of a closure or expanded helper could be used after a push, pop or clear moved the Vec it points
+  into (a stale pointer); that is refused like any other reference across the move.
+- A closure parameter named like an account read the account; it is refused.
+- A helper from another file, expanded here or typed from an arrow passed to it, resolved its types with this file's
+  imports (an aliased or unimported type failed to compile, or an annotation was dropped); its own file's imports are
+  used, and `applyT<u64>((v) => …)` takes the type given at the call.
+- A struct with a FixedVec held in a data enum variant was read as Borsh when also an argument; that conflict is refused.
+- Generated clients read only this program's events: `parseEvents` follows the invoke stack and reads a `Program data:`
+  line only while the program is the innermost one running, and `eventsOf` reads only `emitCpi` inner instructions that
+  call the program. Another program can no longer forge them.
+- `watchEvents` skips failed transactions.
+- `typesol client` refuses malformed generic arguments, array lengths that are not whole numbers and `repr` alignments
+  that are not powers of two, and caps generic instantiation (256 types, 16 levels): a ClientIdlError instead of a crash
+  or a hang. Sizing deeply nested structs no longer takes exponential time.
+- Accounts named like `Object.prototype` properties (`constructor`, `toString`, …) are read as given, not inherited.
+- `resolve.<ix>` derives a has_one source that is a PDA (a `config` PDA) before reading it, and names the account to
+  pass when a source is missing.
+- Notes and errors escape control characters from the IDL.
+- Reading an IDL from the chain caps inflation at 16 MiB, checks Anchor's IdlAccount discriminator, and refuses a
+  Program Metadata IDL that links to a URL or another account instead of following it.
+- `typesol/testing`'s `returned()` decodes string, bytes, f32 and f64 return values, and throws for types it cannot
+  decode instead of misreading them.
+
 ## 0.23.0 — 2026-10-28
 
 Language limits lifted: `map` and `filter`, any number of growable Vecs per account, closures and arrow functions as

package/README.md

@@ -7,7 +7,7 @@
 <p align="center">
   <a href="https://github.com/typesol/typesol/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/typesol/typesol/actions/workflows/ci.yml/badge.svg?branch=main"></a>
   <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-3178C6"></a>
-  <a href="CHANGELOG.md"><img alt="Version 0.10.0 release candidate" src="https://img.shields.io/badge/version-0.10.0--rc-9945FF"></a>
+  <a href="https://www.npmjs.com/package/@typesol/cli"><img alt="npm version" src="https://img.shields.io/npm/v/@typesol/cli"></a>
   <img alt="Target: Solana SBF" src="https://img.shields.io/badge/target-Solana%20SBF-14F195">
 </p>
 
@@ -31,9 +31,9 @@ clients read TypeSOL programs unchanged.
   - Every arithmetic operation is checked.
   - Account owner, discriminator, signer, writability and aliasing checks are generated from your parameter types.
   - Constraints follow Anchor's rules and use Anchor's error codes.
-- **Small and fast.** On the same programs, TypeSOL uses 5–46% of Anchor's compute units, with binaries about 10×
-  smaller. It also uses fewer compute units than native Rust and than hand-tuned Pinocchio on every benchmarked
-  instruction.
+- **Small and fast.** In the LiteSVM benchmarks below, TypeSOL uses 5–32% of Anchor's compute units, with binaries
+  about 10× smaller, and fewer compute units than native Rust and hand-tuned Pinocchio on every instruction. On
+  mainnet the results differ by instruction; see [the mainnet table](#on-mainnet).
 - **Reproducible.** The same sources and toolchain produce the same bytes. `typesol verify` reads a deployed program
   from the cluster and checks it, and the IDL published on chain, against its source.
 
@@ -175,14 +175,14 @@ counter.ts ─▶ tsc typecheck ─▶ subset check ─▶ C + typesol_rt.h ─
 
 1. **Typecheck.** The TypeScript compiler checks your code against [`lib/typesol.d.ts`](lib/typesol.d.ts), which
    declares every TypeSOL type and built-in.
-2. **Subset check.** TypeSOL rejects anything outside the language (floats, closures, classes, `any`, foreign imports)
+2. **Subset check.** TypeSOL rejects anything outside the language (floats, classes, `any`, foreign imports)
    with a `file:line:col` diagnostic. Nothing is half-supported.
 3. **Lower.** Instruction bodies become C. Account validation, checked arithmetic, Borsh encoding and CPI plumbing
    come from [`runtime/typesol_rt.h`](runtime/typesol_rt.h).
 4. **Build.** The Agave platform-tools `clang` and `ld.lld` produce the `.so` (SBPF v0 by default; v1 and v2 with
    `--sbpf`).
 
-Runtime failures point back to your source: `Error 6000 Unauthorized (counter.ts:21)`, or
+Runtime failures point back to your source: `Error 6000 Unauthorized (counter.ts:25)`, or
 `TypeSOL: arithmetic overflow (vault.ts:42)`.
 
 ## What you can write
@@ -225,7 +225,8 @@ import { build } from "typesol/compiler";
 const { soPath, idl } = build("programs/counter.ts", "target/counter", programAddress);
 ```
 
-Subpath exports: `typesol/compiler`, `typesol/workspace`, `typesol/cpi`, `typesol/idl`, `typesol/profile`.
+Subpath exports: `typesol/compiler`, `typesol/workspace`, `typesol/cpi`, `typesol/client`, `typesol/idl`,
+`typesol/profile`, `typesol/testing`, `typesol/ts-plugin`.
 
 ## Numbers
 
@@ -236,16 +237,16 @@ 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 | **1,872** | 3,186 | 4,601 | 6,573 |
+| counter.initialize | **1,866** | 3,186 | 4,601 | 6,573 |
 | counter.increment | **110** | 113 | 857 | 2,323 |
-| vault.open | **1,891** | 3,185 | 4,613 | 6,627 |
+| vault.open | **1,885** | 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 | **3,638** | 6,179 | 9,240 | 13,304 |
+| escrow.make | **3,605** | 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 | 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 |
+| binary, counter / vault / escrow | 13.1 / 16.5 / 23.9 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. TypeSOL hashes PDA candidates with the sha256 and
@@ -306,7 +307,7 @@ Details are in [docs/testing.md](docs/testing.md).
 
 ## Status
 
-**TypeSOL is pre-1.0 (0.23).** Releases follow the organization's
+**TypeSOL is pre-1.0 (0.24).** 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/SECURITY.md

@@ -4,7 +4,7 @@ TypeSOL generates programs that hold funds. Treat it accordingly.
 
 ## Status
 
-- Version 0.10 was reviewed internally (runtime, code generation and tooling). Every release is covered by execution
+- The compiler, runtime and tooling have been through internal security reviews. Every release is covered by execution
   tests, differential tests against Anchor, and randomized tests. **TypeSOL has not been audited by an independent
   firm.** Do not put significant value behind programs built with it until an external audit of the compiler and
   runtime is published, and audit your own programs as you would any Solana program.

package/dist/clientgen.js

@@ -93,6 +93,11 @@ const TAKEN = [
     "required",
     "meta",
     "programFromBytes",
+    "ownProp",
+    "readRelation",
+    "memcmp",
+    "cpiData",
+    "FetchedTransaction",
     "fixedString",
     "fixedOption",
     "unitEnum",
@@ -279,6 +284,8 @@ const pascal = (s) => {
     return c.charAt(0).toUpperCase() + c.slice(1);
 };
 const prop = (s) => (NAME.test(s) && !JS_RESERVED.has(s) ? s : JSON.stringify(s));
+/** Text safe to print on a terminal (notes, errors): C0 and C1 control characters and bidi overrides escaped. */
+const printable = (s) => s.replace(/[\u0000-\u001f\u007f-\u009f\u200e\u200f\u2028\u2029\u202a-\u202e\u2066-\u2069]/g, (c) => `\\u${c.charCodeAt(0).toString(16).padStart(4, "0")}`);
 /** Text that can sit inside a block comment: printable ASCII, no comment terminator. */
 const commentText = (s) => s.replace(/[^\x20-\x7e]/g, " ").replace(/\*\//g, "* /");
 const doc = (lines, indent = "") => Array.isArray(lines) && lines.length && lines.every((l) => typeof l === "string")
@@ -291,7 +298,7 @@ const sortCodeUnits = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
 /** Throws ClientIdlError unless every value that reaches the generated source is well-formed. */
 function validate(idl, programAddress) {
     const fail = (what) => {
-        throw new ClientIdlError(`invalid IDL: ${what}`);
+        throw new ClientIdlError(printable(`invalid IDL: ${what}`));
     };
     const name = (n, where) => (typeof n === "string" && NAME.test(n) ? n : fail(`${where}: name ${JSON.stringify(n)} is not an identifier`));
     const byteList = (b, where) => Array.isArray(b) && b.every((x) => Number.isInteger(x) && x >= 0 && x <= 255) ? b : fail(`${where}: expected a list of bytes (0-255)`);
@@ -304,6 +311,12 @@ function validate(idl, programAddress) {
         if (o.array !== undefined) {
             if (!Array.isArray(o.array) || o.array.length !== 2)
                 fail(`${where}: bad array type`);
+            const len = o.array[1];
+            // A length: a whole number, or a const generic parameter (`{ generic: "N" }`).
+            if (typeof len === "object" && len !== null)
+                name(len.generic, `${where} array length`);
+            else if (!(Number.isSafeInteger(len) && len >= 0))
+                fail(`${where}: array length ${JSON.stringify(len)} is not a whole number`);
             type(o.array[0], where);
             return;
         }
@@ -312,7 +325,24 @@ function validate(idl, programAddress) {
                 return type(o[k], where);
         if (o.defined !== undefined) {
             const d = o.defined;
-            name(typeof d === "string" ? d : d?.name, where);
+            if (typeof d === "string")
+                return void name(d, where);
+            if (typeof d !== "object" || d === null)
+                return fail(`${where}: bad defined type ${JSON.stringify(d)}`);
+            name(d.name, where);
+            // Generic arguments: `{ kind: "type", type }` or `{ kind: "const", value: "4" }`.
+            const args = d.generics;
+            if (args === undefined)
+                return;
+            if (!Array.isArray(args))
+                return fail(`${where}: generic arguments must be a list`);
+            for (const a of args) {
+                const g = (typeof a === "object" && a !== null ? a : {});
+                if (g.kind === "type")
+                    type(g.type, `${where} generic argument`);
+                else if (g.kind !== "const" || !(typeof g.value === "string" && /^\d{1,15}$/.test(g.value)))
+                    fail(`${where}: bad generic argument ${JSON.stringify(a)}`);
+            }
             return;
         }
         if (o.generic !== undefined)
@@ -380,6 +410,19 @@ function validate(idl, programAddress) {
         name(t.name, "type");
         if (typeof t.type !== "object" || t.type === null)
             fail(`type ${t.name} has no definition`);
+        if (t.generics !== undefined) {
+            if (!Array.isArray(t.generics))
+                fail(`type ${t.name}: generics must be a list`);
+            for (const g of t.generics)
+                name(g?.name, `type ${t.name} generic parameter`);
+        }
+        if (t.repr !== undefined) {
+            const align = t.repr?.align;
+            if (typeof t.repr !== "object" || t.repr === null)
+                fail(`type ${t.name}: bad repr`);
+            if (align !== undefined && !(Number.isSafeInteger(align) && align > 0 && Number.isInteger(Math.log2(align))))
+                fail(`type ${t.name}: repr align ${JSON.stringify(align)} is not a power of two`);
+        }
         fields(t.type.fields, `type ${t.name}`);
         for (const v of t.type.variants ?? []) {
             name(v.name, `type ${t.name} variant`);
@@ -447,7 +490,10 @@ function monomorphize(idl) {
         return pascal((definedName(t) ?? "T").replace(/[^A-Za-z0-9_]/g, ""));
     };
     const hasGeneric = (t) => JSON.stringify(t ?? null).includes('"generic"');
-    const inst = (t, env) => {
+    // Instantiations can nest without end (`A<T> { next: Option<A<Vec<T>>> }`): cap their number and nesting.
+    const MAX_INSTANCES = 256;
+    const MAX_DEPTH = 16;
+    const inst = (t, env, depth = 0) => {
         if (typeof t === "string")
             return t;
         if (t.generic !== undefined) {
@@ -455,16 +501,16 @@ function monomorphize(idl) {
             return v === undefined || typeof v === "number" ? t : v;
         }
         if (t.vec !== undefined)
-            return { vec: inst(t.vec, env) };
+            return { vec: inst(t.vec, env, depth) };
         if (t.option !== undefined)
-            return { option: inst(t.option, env) };
+            return { option: inst(t.option, env, depth) };
         if (t.coption !== undefined)
-            return { coption: inst(t.coption, env) };
+            return { coption: inst(t.coption, env, depth) };
         if (t.array) {
             const len = t.array[1];
             const g = typeof len === "object" && len !== null ? len.generic : undefined;
             const n = g !== undefined ? env.get(g) : len;
-            return { array: [inst(t.array[0], env), typeof n === "number" ? n : len] };
+            return { array: [inst(t.array[0], env, depth), typeof n === "number" ? n : len] };
         }
         const name = definedName(t);
         const args = typeof t.defined === "object" ? (t.defined.generics ?? []) : [];
@@ -476,7 +522,7 @@ function monomorphize(idl) {
                 : undefined
             : a?.type === undefined
                 ? undefined
-                : inst(a.type, env));
+                : inst(a.type, env, depth));
         const def = defs.get(name);
         const params = (def?.generics ?? []);
         if (!def ||
@@ -487,6 +533,8 @@ function monomorphize(idl) {
         const key = JSON.stringify([name, values]);
         let made1 = made.get(key);
         if (!made1) {
+            if (extra.length >= MAX_INSTANCES || depth >= MAX_DEPTH)
+                throw new ClientIdlError(`generic type ${name} is instantiated ${depth >= MAX_DEPTH ? `more than ${MAX_DEPTH} levels deep` : `more than ${MAX_INSTANCES} times`} (a generic type that uses itself with growing arguments?)`);
             let base = `${name}${values.map((v) => label(v)).join("")}`;
             if (!NAME.test(base))
                 base = `${name}Instance`;
@@ -497,7 +545,7 @@ function monomorphize(idl) {
             made.set(key, made1);
             const env2 = new Map(params.map((p, i) => [p.name, values[i]]));
             const body = def.type;
-            const field = (f) => (isField(f) ? { ...f, type: inst(f.type, env2) } : inst(f, env2));
+            const field = (f) => (isField(f) ? { ...f, type: inst(f.type, env2, depth + 1) } : inst(f, env2, depth + 1));
             extra.push({
                 ...def,
                 name: made1,
@@ -506,7 +554,7 @@ function monomorphize(idl) {
                     ...body,
                     ...(body.fields ? { fields: body.fields.map(field) } : {}),
                     ...(body.variants ? { variants: body.variants.map((v) => ({ ...v, ...(v.fields ? { fields: v.fields.map(field) } : {}) })) } : {}),
-                    ...(body.alias !== undefined ? { alias: inst(body.alias, env2) } : {}),
+                    ...(body.alias !== undefined ? { alias: inst(body.alias, env2, depth + 1) } : {}),
                 },
             });
         }
@@ -533,6 +581,18 @@ function monomorphize(idl) {
     return { ...idl, instructions, types: [...types, ...extra] };
 }
 export function generateClient(idl, opts = {}) {
+    try {
+        const res = generate(idl, opts);
+        return { ...res, notes: res.notes.map(printable) };
+    }
+    catch (e) {
+        if (e instanceof ClientIdlError)
+            throw e;
+        // A malformed IDL that validation let through is still the IDL's fault: the same error, the original as cause.
+        throw new ClientIdlError(printable(`cannot generate a client from this IDL: ${e instanceof Error ? e.message : String(e)}`), { cause: e });
+    }
+}
+function generate(idl, opts) {
     const programAddress = opts.address ?? idl.address;
     validate(idl, programAddress);
     idl = monomorphize(idl);
@@ -633,7 +693,7 @@ export function generateClient(idl, opts = {}) {
         if (typeof t === "string") {
             if (t in INTS || t in FLOATS || ["bool", "pubkey", "publicKey", "string", "bytes"].includes(t))
                 return undefined;
-            return `type "${t}" is not supported`;
+            return `type ${JSON.stringify(t)} is not supported`;
         }
         if (t.generic !== undefined)
             return "generic parameters are not supported";
@@ -668,7 +728,7 @@ export function generateClient(idl, opts = {}) {
                 why = l;
         }
         else if (d.serialization && d.serialization !== "borsh")
-            why = `type ${n} uses ${d.serialization} serialization, which is not supported`;
+            why = `type ${n} uses ${JSON.stringify(d.serialization)} serialization, which is not supported`;
         else if (special(n)?.kind === "foption")
             why = issue(special(n).inner);
         else if (d.type.kind === "struct")
@@ -678,7 +738,7 @@ export function generateClient(idl, opts = {}) {
         else if (d.type.kind === "type" && d.type.alias !== undefined)
             why = issue(d.type.alias);
         else
-            why = `type ${n} (${d.type.kind}) is not supported`;
+            why = `type ${n} (${JSON.stringify(d.type.kind)}) is not supported`;
         typeIssues.set(n, why);
         return why;
     }
@@ -788,7 +848,8 @@ export function generateClient(idl, opts = {}) {
             return (use("fixCodecSize"), `fixCodecSize(get${tsName(s.base)}Codec(), ${s.size})`);
         return `get${tsName(n)}Codec()`;
     }
-    /** Byte size of a fixed-size IDL type (undefined when it varies). */
+    /** Byte size of a fixed-size IDL type (undefined when it varies). Memoized by type name, so shared types are sized once. */
+    const sizes = new Map();
     function idlSize(t) {
         if (typeof t === "string") {
             if (t in INTS)
@@ -808,6 +869,14 @@ export function generateClient(idl, opts = {}) {
         const n = definedName(t);
         if (n === undefined)
             return undefined;
+        if (sizes.has(n))
+            return sizes.get(n);
+        sizes.set(n, undefined); // a type that holds itself has no fixed size
+        const size = definedSize(n);
+        sizes.set(n, size);
+        return size;
+    }
+    function definedSize(n) {
         const sp = special(n);
         if (sp?.kind === "fstring")
             return 4 + sp.cap;
@@ -1121,8 +1190,9 @@ export function generateClient(idl, opts = {}) {
             ? `export interface ${P}Args {\n${argsField.map((a) => `${doc(a.docs, "  ")}  ${prop(a.key)}: ${tsType(a.type, "in")};`).join("\n")}\n}\n`
             : "";
         // Locals: given accounts and fixed addresses first, then PDAs in dependency order. `null` leaves an optional
-        // account out (sent as the program id); `undefined` fills it in.
-        const input = (a) => `input${NAME.test(a.key) && !JS_RESERVED.has(a.key) ? `.${a.key}` : `[${JSON.stringify(a.key)}]`}`;
+        // account out (sent as the program id); `undefined` fills it in. Accounts are read as own properties, so one named
+        // `constructor` or `toString` is not taken from Object.prototype.
+        const input = (a) => `ownProp(input, ${JSON.stringify(a.key)})`;
         const fill = (a, value) => (a.optional ? `${input(a)} === null ? null : (${input(a)} ?? ${value})` : `${input(a)} ?? ${value}`);
         const lines = [];
         for (const a of flat) {
@@ -1190,7 +1260,8 @@ export function generateClient(idl, opts = {}) {
         ixKeys.push(`${prop(fn)}: build${P}`);
         // `resolve.<instruction>`: what needs the chain or the caller's wallet, filled in on a copy of the accounts in this
         // order: signers (a default signer), has_one accounts, then PDAs seeded from other accounts' fields.
-        const acc = (f) => `acc${NAME.test(f.key) && !JS_RESERVED.has(f.key) ? `.${f.key}` : `[${JSON.stringify(f.key)}]`}`;
+        const acc = (f) => `ownProp(acc, ${JSON.stringify(f.key)})`;
+        const setAcc = (f) => `acc${NAME.test(f.key) && !JS_RESERVED.has(f.key) ? `.${f.key}` : `[${JSON.stringify(f.key)}]`}`;
         // A field's value as seed bytes: scalars by their codec, strings as UTF-8, byte fields as they are.
         const seedOfField = (t, v) => {
             if (typeof t === "string") {
@@ -1330,8 +1401,7 @@ export function generateClient(idl, opts = {}) {
                     params.set(camel(p.path), `${camel(p.path)}: Address`);
                 const rewrite = (e) => e
                     .replace(/\bargs\.([A-Za-z0-9_$]+)/g, "seeds.$1")
-                    .replace(/key\(acc\.([A-Za-z0-9_$]+)!\)/g, "key(seeds.$1)")
-                    .replace(/key\(acc\["([^"]+)"\]!\)/g, 'key(seeds["$1"])');
+                    .replace(/key\(ownProp\(acc, "([^"]+)"\)!\)/g, (_, k) => `key(seeds${NAME.test(k) && !JS_RESERVED.has(k) ? `.${k}` : `[${JSON.stringify(k)}]`})`);
                 use("type ProgramDerivedAddress", "getProgramDerivedAddress");
                 pdaFns.set(pn, {
                     json,
@@ -1348,17 +1418,38 @@ export function generateClient(idl, opts = {}) {
                 lines: [
                     `      if (${acc(a)} === undefined) {`,
                     ...[...bases.values()].map(({ base, A }) => `        const ${"$$" + base.key} = await ${A}.fetch(rpc, key(${acc(base)}!));`),
-                    `        ${acc(a)} = (await getProgramDerivedAddress({ programAddress: ${program}, seeds: [${seeds.join(", ")}] }))[0];`,
+                    `        ${setAcc(a)} = (await getProgramDerivedAddress({ programAddress: ${program}, seeds: [${seeds.join(", ")}] }))[0];`,
                     `      }`,
                 ],
             });
         }
+        // A has_one source the builder derives (a `config` PDA) is derived here too, after the accounts its seeds name,
+        // so its fields can be read.
+        const needed = new Set();
+        const need = (k) => {
+            if (!resolvable.has(k) || needed.has(k))
+                return;
+            needed.add(k);
+            for (const d of resolvable.get(k).deps)
+                need(d);
+        };
+        for (const r of rels)
+            need(r.source.key);
+        const derived = order.filter((a) => needed.has(a.key));
+        const ref = (f) => (f.address ? `(${acc(f)} ?? address(${JSON.stringify(f.address)}))` : acc(f));
+        const sub = (e) => e.replace(/key\(\$([A-Za-z0-9_]+)\)/g, (_, k) => `key(${ref(flat.find((f) => f.key === k))}, ${JSON.stringify(k)})`);
+        const deriveLines = derived.map((a) => {
+            const r = resolvable.get(a.key);
+            return `      if (${acc(a)} === undefined) ${setAcc(a)} = (await getProgramDerivedAddress({ programAddress: ${sub(r.program ?? "PROGRAM_ADDRESS")}, seeds: [${r.seeds.map(sub).join(", ")}] }))[0];`;
+        });
         if (rels.length || fieldPdas.length || signers.length) {
             const filled = [...signers, ...rels.map((r) => r.a), ...fieldPdas.map((f) => f.a)];
             const keysOf = [...new Set(filled.map((a) => JSON.stringify(a.key)))].join(" | ");
-            const withArgs = fieldPdas.some((f) => f.usesArgs);
+            const withArgs = fieldPdas.some((f) => f.usesArgs) ||
+                derived.some((a) => /\bargs\./.test([...resolvable.get(a.key).seeds, resolvable.get(a.key).program ?? ""].join(" ")));
             const what = [
                 ...(signers.length ? [`${signers.map((a) => a.key).join(", ")} (options.signer when left out)`] : []),
+                ...derived.map((a) => `${a.key} (derived, to read it)`),
                 ...rels.map((r) => `${r.a.key} (from ${r.source.key}.${camel(r.a.name)})`),
                 ...fieldPdas.map((f) => `${f.a.key} (a PDA seeded from account fields)`),
             ].join(", ");
@@ -1366,8 +1457,9 @@ export function generateClient(idl, opts = {}) {
                 `    async ${prop(fn)}(rpc: Rpc<GetAccountInfoApi>, input: Omit<${P}Accounts, ${keysOf}> & Partial<Pick<${P}Accounts, ${keysOf}>>${withArgs ? `, args: ${P}Args` : ""}, options: { signer?: TransactionSigner } = {}): Promise<${P}Accounts> {\n` +
                 `      const acc: Partial<${P}Accounts> = { ...input };\n` +
                 [
-                    ...signers.map((a) => `      if (${acc(a)} === undefined) {\n        if (!options.signer) throw new Error(${JSON.stringify(`${ix.name}: pass ${a.key}, or a default signer as options.signer`)});\n        ${acc(a)} = options.signer;\n      }`),
-                    ...rels.map((r) => `      ${acc(r.a)} ??= await readRelation(rpc, key(${acc(r.source)}!), ${JSON.stringify(r.a.key)}, [${r.readers.join(", ")}]);`),
+                    ...signers.map((a) => `      if (${acc(a)} === undefined) {\n        if (!options.signer) throw new Error(${JSON.stringify(`${ix.name}: pass ${a.key}, or a default signer as options.signer`)});\n        ${setAcc(a)} = options.signer;\n      }`),
+                    ...deriveLines,
+                    ...rels.map((r) => `      if (${acc(r.a)} === undefined) ${setAcc(r.a)} = await readRelation(rpc, ${ref(r.source)}, ${JSON.stringify(r.source.key)}, ${JSON.stringify(r.a.key)}, [${r.readers.join(", ")}]);`),
                     ...fieldPdas.flatMap((f) => f.lines),
                 ].join("\n") +
                 `\n      void rpc;\n      return acc as ${P}Accounts;\n    },`);
@@ -1420,8 +1512,8 @@ export function generateClient(idl, opts = {}) {
         {
             name: "key",
             lines: [
-                `const key = (v: TransactionSigner | Address | undefined | null): Address => {`,
-                `  if (v === undefined || v === null) throw new Error("a seed account is missing");`,
+                `const key = (v: TransactionSigner | Address | undefined | null, name?: string): Address => {`,
+                `  if (v === undefined || v === null) throw new Error(name === undefined ? "a seed account is missing" : "a seed account is missing: pass " + name);`,
                 `  return isSigner(v) ? v.address : v;`,
                 `};`,
             ],
@@ -1442,11 +1534,26 @@ export function generateClient(idl, opts = {}) {
             ],
         },
         { name: "programFromBytes", lines: [`const programFromBytes = (b: Uint8Array): Address => getAddressDecoder().decode(b);`] },
+        {
+            name: "ownProp",
+            lines: [
+                `/** An account given in \`o\` (an own property: never one inherited from Object.prototype, such as \`constructor\`). */`,
+                `const ownProp = <T extends object, K extends keyof T>(o: T, k: K): T[K] | undefined => (Object.prototype.hasOwnProperty.call(o, k) ? o[k] : undefined);`,
+            ],
+        },
         {
             name: "readRelation",
             lines: [
-                `/** A Pubkey field of an account on chain, read by the first reader that knows its type. */`,
-                `const readRelation = async (rpc: Rpc<GetAccountInfoApi>, at: Address, name: string, readers: ((data: ReadonlyUint8Array) => Address | undefined)[]): Promise<Address> => {`,
+                `/** A Pubkey field (\`name\`) of an account on chain (\`from\`), read by the first reader that knows its type. */`,
+                `const readRelation = async (`,
+                `  rpc: Rpc<GetAccountInfoApi>,`,
+                `  from: TransactionSigner | Address | undefined,`,
+                `  fromName: string,`,
+                `  name: string,`,
+                `  readers: ((data: ReadonlyUint8Array) => Address | undefined)[],`,
+                `): Promise<Address> => {`,
+                `  if (from === undefined) throw new Error("cannot fill in " + name + ": pass " + fromName + ", the account it is read from");`,
+                `  const at = key(from);`,
                 `  const found = await fetchEncodedAccount(rpc, at);`,
                 `  if (!found.exists) throw new Error("cannot fill in " + name + ": account " + at + " does not exist");`,
                 `  for (const read of readers) {`,
@@ -1581,6 +1688,11 @@ export function generateClient(idl, opts = {}) {
         `  for (let cur: unknown = e, depth = 0; cur !== undefined && cur !== null && depth < 8; depth++) {`,
         `    if (typeof cur === "number") return cur;`,
         `    if (isSolanaError(cur, SOLANA_ERROR__INSTRUCTION_ERROR__CUSTOM)) return Number(cur.context.code);`,
+        `    // The JSON an RPC node returns (simulations, signature statuses): { InstructionError: [0, { Custom: 6000 }] }.`,
+        `    if (typeof cur === "object" && "InstructionError" in cur && Array.isArray(cur.InstructionError)) {`,
+        `      const inner: unknown = cur.InstructionError[1];`,
+        `      if (typeof inner === "object" && inner !== null && "Custom" in inner) return Number(inner.Custom);`,
+        `    }`,
         `    if (typeof cur === "object" && "err" in cur && typeof cur.err === "function") cur = String(cur.err());`,
         `    if (typeof cur === "string" || cur instanceof Error) {`,
         `      const m = /custom program error: (0x[0-9a-f]+)|Custom(?:\\(|\\s*\\{\\s*code:\\s*)(\\d+)/i.exec(String(cur instanceof Error ? cur.message : cur));`,
@@ -1612,14 +1724,25 @@ export function generateClient(idl, opts = {}) {
             : `  void data;\n  return null;`,
         `}`,
         `/**`,
-        ` * Events in a transaction's log messages (\`Program data:\` lines, as \`emit\` writes them). Lines are matched by`,
-        ` * discriminator, whichever program wrote them; lines that do not decode are skipped. \`emitCpi\` events travel in inner`,
-        ` * instructions: see parseCpiEvents and eventsOf.`,
+        ` * Events in a transaction's log messages (\`Program data:\` lines, as \`emit\` writes them). Only this program's lines`,
+        ` * count: the \`Program <id> invoke\` and \`success\` / \`failed\` lines are followed, and a data line is read only while`,
+        ` * this program is the innermost one running (as Anchor's EventParser does). Lines that do not decode are skipped.`,
+        ` * \`emitCpi\` events travel in inner instructions: see eventsOf.`,
         ` */`,
         `export function parseEvents(logs: readonly string[]): Event[] {`,
         `  const found: Event[] = [];`,
+        `  const running: string[] = [];`,
         `  for (const line of logs) {`,
-        `    if (!line.startsWith("Program data: ")) continue;`,
+        `    const invoke = /^Program (\\S+) invoke \\[\\d+\\]$/.exec(line);`,
+        `    if (invoke) {`,
+        `      running.push(invoke[1]!);`,
+        `      continue;`,
+        `    }`,
+        `    if (/^Program \\S+ (success$|failed)/.test(line)) {`,
+        `      running.pop();`,
+        `      continue;`,
+        `    }`,
+        `    if (running.at(-1) !== PROGRAM_ADDRESS || !line.startsWith("Program data: ")) continue;`,
         `    let data: ReadonlyUint8Array;`,
         `    try {`,
         `      data = getBase64Encoder().encode(line.slice("Program data: ".length));`,
@@ -1631,7 +1754,10 @@ export function generateClient(idl, opts = {}) {
         `  }`,
         `  return found;`,
         `}`,
-        `/** \`emitCpi\` events: the data of inner instructions (bytes, or base58 as RPC returns them) that carry one. */`,
+        `/**`,
+        ` * \`emitCpi\` events in instruction data (bytes, or base58 as RPC returns them). This does not check which program the`,
+        ` * instructions called, so give it only this program's inner instructions; eventsOf picks them from a transaction.`,
+        ` */`,
         `export function parseCpiEvents(instructionData: Iterable<ReadonlyUint8Array | string>): Event[] {`,
         `  const tag = new Uint8Array([228, 69, 165, 46, 81, 203, 154, 29]);`,
         `  const found: Event[] = [];`,
@@ -1648,16 +1774,38 @@ export function generateClient(idl, opts = {}) {
         `  }`,
         `  return found;`,
         `}`,
-        `/** Every event of a fetched transaction (getTransaction, json encoding): its logs, then its inner instructions. */`,
-        `export function eventsOf(tx: { meta: { logMessages?: readonly string[] | null; innerInstructions?: readonly { instructions: readonly { data: string }[] }[] | null } | null } | null): Event[] {`,
-        `  const meta = tx?.meta;`,
-        `  if (!meta) return [];`,
-        `  return [...parseEvents(meta.logMessages ?? []), ...parseCpiEvents((meta.innerInstructions ?? []).flatMap((g) => g.instructions.map((i) => i.data)))];`,
+        `/** A transaction as getTransaction returns it (json encoding), as far as events need it. */`,
+        `export interface FetchedTransaction {`,
+        `  transaction?: { message: { accountKeys: readonly (string | { pubkey: string })[] } } | null;`,
+        `  meta: {`,
+        `    logMessages?: readonly string[] | null;`,
+        `    innerInstructions?: readonly { instructions: readonly { programIdIndex?: number; data: string }[] }[] | null;`,
+        `    loadedAddresses?: { writable: readonly string[]; readonly: readonly string[] } | null;`,
+        `  } | null;`,
+        `}`,
+        `/** The data of the inner instructions of \`tx\` that call this program (found by their program's account index). */`,
+        `function cpiData(tx: FetchedTransaction): string[] {`,
+        `  const keys = [`,
+        `    ...(tx.transaction?.message.accountKeys ?? []).map((k) => (typeof k === "string" ? k : k.pubkey)),`,
+        `    ...(tx.meta?.loadedAddresses?.writable ?? []),`,
+        `    ...(tx.meta?.loadedAddresses?.readonly ?? []),`,
+        `  ];`,
+        `  return (tx.meta?.innerInstructions ?? []).flatMap((g) =>`,
+        `    g.instructions.filter((i) => i.programIdIndex !== undefined && keys[i.programIdIndex] === PROGRAM_ADDRESS).map((i) => i.data),`,
+        `  );`,
+        `}`,
+        `/**`,
+        ` * Every event of a fetched transaction (getTransaction, json encoding): its log events, then the \`emitCpi\` events of`,
+        ` * its inner instructions that call this program (read only when \`tx.transaction\` gives the account keys).`,
+        ` */`,
+        `export function eventsOf(tx: FetchedTransaction | null): Event[] {`,
+        `  if (!tx?.meta) return [];`,
+        `  return [...parseEvents(tx.meta.logMessages ?? []), ...parseCpiEvents(cpiData(tx))];`,
         `}`,
         `/**`,
-        ` * Events of every transaction that mentions the program, as their logs arrive, until \`abortSignal\` aborts. With`,
-        ` * \`rpc\`, \`emitCpi\` events too: a transaction in which the program invoked itself is fetched (getTransaction) and its`,
-        ` * inner instructions read, after its log events.`,
+        ` * Events of every transaction that mentions the program and succeeded, as their logs arrive, until \`abortSignal\``,
+        ` * aborts (a failed transaction's events did not happen). With \`rpc\`, \`emitCpi\` events too: a transaction in which`,
+        ` * the program invoked itself is fetched (getTransaction) and its inner instructions read, after its log events.`,
         ` */`,
         `export async function* watchEvents(`,
         `  rpcSubscriptions: RpcSubscriptions<LogsNotificationsApi>,`,
@@ -1666,6 +1814,7 @@ export function generateClient(idl, opts = {}) {
         `  const logs = await rpcSubscriptions.logsNotifications({ mentions: [PROGRAM_ADDRESS] }, options.commitment ? { commitment: options.commitment } : {}).subscribe({ abortSignal: options.abortSignal });`,
         `  const selfInvoke = new RegExp("^Program " + PROGRAM_ADDRESS + " invoke \\\\[([2-9]|\\\\d{2,})\\\\]$");`,
         `  for await (const n of logs) {`,
+        `    if (n.value.err !== null) continue;`,
         `    for (const event of parseEvents(n.value.logs)) yield { signature: n.value.signature, event };`,
         `    if (!options.rpc || !n.value.logs.some((l) => selfInvoke.test(l))) continue;`,
         `    // The transaction can trail its logs by a moment: a few tries.`,
@@ -1674,7 +1823,7 @@ export function generateClient(idl, opts = {}) {
         `        .getTransaction(n.value.signature, { encoding: "json", maxSupportedTransactionVersion: 0, commitment: options.commitment === "finalized" ? "finalized" : "confirmed" })`,
         `        .send();`,
         `      if (tx) {`,
-        `        for (const event of parseCpiEvents((tx.meta?.innerInstructions ?? []).flatMap((g) => g.instructions.map((i) => i.data)))) yield { signature: n.value.signature, event };`,
+        `        for (const event of parseCpiEvents(cpiData(tx))) yield { signature: n.value.signature, event };`,
         `        break;`,
         `      }`,
         `      await new Promise((resolve) => setTimeout(resolve, 400));`,