@typesol/cli 0.22.0 → 0.24.0

package/dist/compiler/emit/storage.js

@@ -1,7 +1,7 @@
 import ts from "typescript";
 import { resolveScalarType } from "../analyze.js";
 import { INT_INFO, isScalar, isWritable, sameType, scalarSize, typeName } from "../model.js";
-import { U64, BOOL, PUBKEY, STRING, optC, fieldC, fixedVecC, storageDecl, vecCount } from "./shared.js";
+import { U64, BOOL, PUBKEY, STRING, optC, fieldC, fixedVecC, storageDecl, vecCount, vecPlace, emptySizeC } from "./shared.js";
 import { EmitterBase } from "./base.js";
 /**
  * Places in account data and locals: references, reads and writes, Vec/array indexing, aliasing rules and
@@ -73,16 +73,7 @@ export class StorageEmitter extends EmitterBase {
         return r?.type.kind === "dataEnum" ? r : undefined;
     }
     looksLikeDataEnum(node) {
-        const saved = { lines: this.lines.length, hoisted: this.hoisted.length, temp: this.temp, diagnostics: this.reporter.diagnostics.length };
-        try {
-            return this.reporter.guard(() => this.ref(node))?.type.kind === "dataEnum";
-        }
-        finally {
-            this.lines.length = saved.lines;
-            this.hoisted.length = saved.hoisted; // a probed helper call may hoist declarations
-            this.temp = saved.temp;
-            this.reporter.diagnostics.length = saved.diagnostics;
-        }
+        return this.probe(() => this.ref(node))?.type.kind === "dataEnum";
     }
     variantIndex(enumName, lit) {
         const e = this.model.dataEnums.get(enumName);
@@ -137,11 +128,37 @@ export class StorageEmitter extends EmitterBase {
                     : `"${name}" still refers to ${hit}; replacing it here would change what "${name}" reads (in JS it keeps the old value). Copy the fields you need into locals first`);
             }
     }
-    /** Whether the variable declared by `decl` is read after `at` (later in its block, or anywhere in a loop around `at`). */
+    /**
+     * Whether the variable declared by `decl` is read after `at` (later in its block, or anywhere in a loop around `at`).
+     * A parameter (of a closure or helper expanded here) is read after `at` when its function reads it after `at`; when
+     * `at` is in another function (a closure or helper it calls), any read of it in its own function counts.
+     */
     usedAfter(decl, at) {
         const symbol = this.checker.getSymbolAtLocation(decl.name);
         if (!symbol)
             return true;
+        if (ts.isParameter(decl)) {
+            const fn = decl.parent;
+            const inside = at.getSourceFile() === fn.getSourceFile() && at.pos >= fn.pos && at.end <= fn.end;
+            let read = false;
+            const visitParam = (n) => {
+                if (read)
+                    return;
+                if (ts.isIdentifier(n) && n !== decl.name && this.checker.getSymbolAtLocation(n) === symbol) {
+                    if (!inside || n.pos >= at.end)
+                        read = true;
+                    // A loop inside the function, around `at`, reads it again on its next turn.
+                    for (let p = at.parent; inside && p && p !== fn; p = p.parent)
+                        if ((ts.isForStatement(p) || ts.isForOfStatement(p) || ts.isWhileStatement(p) || ts.isDoStatement(p)) && n.pos >= p.pos && n.end <= p.end)
+                            read = true;
+                }
+                ts.forEachChild(n, visitParam);
+            };
+            const body = fn.body;
+            if (body)
+                visitParam(body);
+            return read;
+        }
         // Loops around `at` that do not also contain the declaration run their earlier statements again later.
         let loop;
         for (let n = at.parent; n && n !== decl.parent; n = n.parent)
@@ -208,17 +225,8 @@ export class StorageEmitter extends EmitterBase {
             return this.looksLikeStructPlace(node.expression);
         if (ts.isConditionalExpression(node))
             return this.looksLikeStructPlace(node.whenTrue) && this.looksLikeStructPlace(node.whenFalse);
-        const saved = { lines: this.lines.length, hoisted: this.hoisted.length, temp: this.temp, diagnostics: this.reporter.diagnostics.length };
-        try {
-            const r = this.reporter.guard(() => this.ref(node));
-            return r?.type.kind === "struct";
-        }
-        finally {
-            this.lines.length = saved.lines;
-            this.hoisted.length = saved.hoisted; // a probed helper call may hoist declarations
-            this.temp = saved.temp;
-            this.reporter.diagnostics.length = saved.diagnostics;
-        }
+        const r = this.probe(() => this.ref(node));
+        return r?.type.kind === "struct";
     }
     /** `fixedArray<T, N>(fill)` as a local declaration. */
     localArray(init, c) {
@@ -258,6 +266,8 @@ export class StorageEmitter extends EmitterBase {
             const l = this.lookup(node.text);
             if (l && l.type.kind === "array")
                 return { lv: l.c, type: l.type, writable: !l.readonly };
+            if (l && l.type.kind === "vec")
+                return this.withFixedVec({ lv: l.c, type: l.type, writable: true });
             // A struct loaded from a remaining account.
             if (l && l.type.kind === "structRef")
                 return { lv: `(*${l.c})`, type: { kind: "struct", name: l.type.struct }, writable: l.type.writable };
@@ -278,15 +288,35 @@ export class StorageEmitter extends EmitterBase {
                     const r = { lv: `d_${a.name}->${f.name}`, type: f.type, writable: isWritable(a.kind), account: a, path: [f.name] };
                     if (f.type.kind === "vec" && f.type.cap !== undefined)
                         r.vec = this.fixedVec(r.lv, f.type.elem, f.type.cap);
-                    else if (f.type.kind === "vec")
+                    else if (f.type.kind === "vec") {
                         // Growing needs the account's length at instruction entry: instructions have it, helpers get it passed.
-                        r.vec = {
-                            len: `d_${a.name}->${f.name}__len`,
-                            items: r.lv,
-                            fixed: `sizeof(TSS_${a.kind.struct.name})`,
-                            elemSize: a.kind.struct.vec.elemSize,
-                            resizable: isWritable(a.kind),
-                        };
+                        const s = a.kind.struct;
+                        const k = s.vecs.findIndex((v) => v.name === f.name);
+                        if (s.vecs.length === 1)
+                            r.vec = {
+                                len: `d_${a.name}->${f.name}__len`,
+                                items: r.lv,
+                                fixed: `sizeof(TSS_${s.name})`,
+                                elemSize: s.vec.elemSize,
+                                resizable: isWritable(a.kind),
+                            };
+                        else {
+                            const base = `(*d_${a.name})`;
+                            const at = vecPlace(s, base, k);
+                            const others = s.vecs.map((v, j) => (j === k ? "" : ` + (uint64_t)${vecPlace(s, base, j).len} * ${v.elemSize}`)).join("");
+                            r.lv = at.items;
+                            r.vec = {
+                                len: at.len,
+                                items: at.items,
+                                fixed: `(${emptySizeC(s)}${others})`,
+                                elemSize: s.vecs[k].elemSize,
+                                resizable: isWritable(a.kind),
+                                tail: k < s.vecs.length - 1
+                                    ? { end: at.end, dataEnd: `(a_${a.name}->data + a_${a.name}->data_len)`, paths: s.vecs.slice(k + 1).map((v) => `${a.name}.${v.name}[]`) }
+                                    : undefined,
+                            };
+                        }
+                    }
                     return r;
                 }
             }
@@ -330,8 +360,12 @@ export class StorageEmitter extends EmitterBase {
                     this.fail(node.name, `${s.name} has no field "${field}"`);
                 const r = { ...base, lv: `${base.lv}.${f.name}`, type: f.type, path: base.path && [...base.path, f.name], vec: undefined };
                 // Vecs of loaded accounts can be read and updated in place but not resized (no entry length known).
-                if (f.type.kind === "vec" && f.type.cap === undefined)
-                    r.vec = { len: `${base.lv}.${f.name}__len`, items: r.lv, fixed: `sizeof(TSS_${s.name})`, elemSize: s.vec.elemSize, resizable: false };
+                if (f.type.kind === "vec" && f.type.cap === undefined) {
+                    const k = s.vecs.findIndex((v) => v.name === f.name);
+                    const at = s.vecs.length === 1 ? { len: `${base.lv}.${f.name}__len`, items: r.lv } : vecPlace(s, base.lv, k);
+                    r.lv = at.items;
+                    r.vec = { len: at.len, items: at.items, fixed: emptySizeC(s), elemSize: s.vecs[k].elemSize, resizable: false };
+                }
                 return this.withFixedVec(r);
             }
             return undefined;
@@ -565,6 +599,11 @@ export class StorageEmitter extends EmitterBase {
             const els = valueNode.elements;
             if (els.length > t.cap)
                 this.fail(valueNode, `${els.length} elements do not fit in ${typeName(t)}`);
+            // Empty: nothing reads the old list, so it is cleared in place (length 0, every slot zero).
+            if (els.length === 0) {
+                this.line(`ts_memzero(&${target.lv}, sizeof(${target.lv}));`);
+                return;
+            }
             const tmp = this.tmp("fv");
             this.line(`${fixedVecC(t)} ${tmp};`);
             this.line(`ts_memzero(&${tmp}, sizeof(${tmp}));`);
@@ -655,24 +694,15 @@ export class StorageEmitter extends EmitterBase {
     }
     /** The kind of storage an expression names (struct, array, dataEnum…), without emitting code or failing. */
     peekKind(node) {
-        const saved = { lines: this.lines.length, hoisted: this.hoisted.length, temp: this.temp, diagnostics: this.reporter.diagnostics.length };
-        try {
-            return this.reporter.guard(() => this.ref(node))?.type.kind;
-        }
-        finally {
-            this.lines.length = saved.lines;
-            this.hoisted.length = saved.hoisted; // a probed helper call may hoist declarations
-            this.temp = saved.temp;
-            this.reporter.diagnostics.length = saved.diagnostics;
-        }
+        return this.probe(() => this.ref(node))?.type.kind;
     }
     place(node) {
         if (ts.isIdentifier(node)) {
             const l = this.lookup(node.text);
             if (!l)
                 this.fail(node, `"${node.text}" is not a local variable`);
-            if (l.type.kind === "array")
-                this.fail(node, `use ${node.text}.set(i, v) to change array elements`);
+            if (l.type.kind === "array" || l.type.kind === "vec")
+                this.fail(node, `use ${node.text}.set(i, v) to change list elements`);
             if (!l.mutable)
                 this.fail(node, `"${node.text}" is const or an argument and cannot be reassigned`);
             if (l.type.kind === "pubkey")

package/dist/compiler/model.d.ts

@@ -38,9 +38,11 @@ export type ValueType = ScalarType | {
     inner: ScalarType;
 }
 /** `Vec<T>` instruction argument: a read-only view into instruction data. T is a scalar or a fixed-size struct. */
+/** A Vec argument (Borsh), read in place; `FixedVec<T, N>` arguments are the same with at most `cap` elements. */
  | {
     kind: "vecArg";
     elem: FieldType;
+    cap?: number;
 }
 /** `FixedArray<T, N>` instruction argument (Borsh [T; N]), parsed into a read-only copy. */
  | {
@@ -119,6 +121,8 @@ export type FieldType = ScalarType | {
 export interface StructField {
     name: string;
     type: FieldType;
+    /** The declaration, while the struct is being analyzed (for messages). */
+    node?: ts.Node;
 }
 /** Every exported interface. Used as account data, nested in other structs, or emitted as an event. */
 export interface StructDef {
@@ -129,12 +133,21 @@ export interface StructDef {
      * or undefined when a field is a variable-length string (event-only structs).
      */
     size: number | undefined;
-    /** The trailing Vec field, if any. Such structs can only be account data. */
+    /** The first growable Vec field, if any. Such structs can only be account data. */
     vec?: {
         name: string;
         elem: FieldType;
         elemSize: number;
     };
+    /**
+     * Every growable Vec, in stored order (after the fixed-size fields). The first ends the C struct (its u32 length,
+     * then its elements); each further one follows the previous one's elements: a u32 length, then its elements.
+     */
+    vecs?: {
+        name: string;
+        elem: FieldType;
+        elemSize: number;
+    }[];
     accountDiscriminator: number[];
     eventDiscriminator: number[];
     node: ts.InterfaceDeclaration;
@@ -410,6 +423,14 @@ export interface ProgramModel {
     helperDecls: Map<ts.Node, string>;
     /** Local closures (they read the enclosing function's variables): their declaration -> name; expanded where called. */
     closureDecls: Map<ts.Node, string>;
+    /**
+     * Functions that return a function (`function adder(n: u64): (x: u64) => u64 { return (x) => x + n; }`): no C
+     * function; a call binds the returned function, with the arguments, as a closure where it is made.
+     */
+    factories: Map<string, {
+        node: HelperNode;
+        imports: Map<string, string>;
+    }>;
     errors: ErrorDef[];
     /** Enum name -> member name -> error */
     errorEnums: Map<string, Map<string, ErrorDef>>;
@@ -436,6 +457,10 @@ export interface ProgramModel {
     fixedVecs: Map<string, FieldType & {
         kind: "vec";
     }>;
+    /** FixedVec types of local lists (`const ys = xs.map(…)`), filled in while emitting: C typedefs only, not the IDL. */
+    localVecs: Map<string, FieldType & {
+        kind: "vec";
+    }>;
 }
 export declare function isWritable(k: ParamKind): boolean;
 export declare function typeName(t: ValueType | FieldType): string;

package/dist/idlpublish.d.ts

@@ -25,7 +25,12 @@ export interface PublishOptions {
 /** Write (create or update) the IDL metadata account; returns its address. */
 export declare function publishIdl(chain: Chain, opts: PublishOptions): Promise<Address>;
 export declare function metadataAddress(program: Address, authority: Address | null): Promise<Address>;
-/** Read an IDL back (canonical, or the one `authority` wrote). */
+/** The most an IDL read from the chain may inflate to: compressed data can expand far past the account's size. */
+export declare const MAX_IDL_BYTES: number;
+/**
+ * Read an IDL back (canonical, or the one `authority` wrote). Only an IDL stored in the metadata account itself is
+ * read: one that links to a URL or points at another account is refused (nothing is fetched from where it points).
+ */
 export declare function fetchIdl(rpc: Chain["rpc"], program: Address, authority?: Address | null): Promise<object>;
 /** Where `anchor idl init` keeps a program's IDL: an account derived with seed "anchor:idl" from the program's base PDA. */
 export declare function anchorIdlAddress(program: Address): Promise<Address>;

package/dist/idlpublish.js

@@ -5,8 +5,9 @@
  *
  * Works against an RPC (`rpcChain`) or anything else that can read accounts and send transactions (tests use LiteSVM).
  */
-import { inflateSync } from "node:zlib";
-import { Compression, Encoding, Format, fetchMetadataContent, findMetadataPda, packDirectData, writeMetadata } from "@solana-program/program-metadata";
+import { createHash } from "node:crypto";
+import { gunzipSync, inflateSync } from "node:zlib";
+import { Compression, DataSource, Encoding, Format, decodeData, fetchMaybeMetadata, findMetadataPda, packDirectData, writeMetadata, } from "@solana-program/program-metadata";
 import { createAddressWithSeed, createClient, createTransactionMessage, createTransactionPlanExecutor, createTransactionPlanner, extendClient, getAddressEncoder, getBase64EncodedWireTransaction, getProgramDerivedAddress, getSignatureFromTransaction, lamports, pipe, setTransactionMessageFeePayerSigner, setTransactionMessageLifetimeUsingBlockhash, signTransactionMessageWithSigners, } from "@solana/kit";
 export const PROGRAM_METADATA_ID = "ProgM6JCCvbYkfKqJYHePx4xxSUSqJp7rh8Lyv7nk7S";
 /** A Chain over an RPC endpoint (polls signature status: no websocket needed). */
@@ -111,15 +112,54 @@ function planFailure(e) {
 export async function metadataAddress(program, authority) {
     return (await findMetadataPda({ program, authority, seed: "idl" }))[0];
 }
-/** Read an IDL back (canonical, or the one `authority` wrote). */
+/** The most an IDL read from the chain may inflate to: compressed data can expand far past the account's size. */
+export const MAX_IDL_BYTES = 16 * 1024 * 1024;
+/** Decompress `data` (zlib or gzip), refusing output past MAX_IDL_BYTES. */
+function inflateCapped(data, gzip, what) {
+    try {
+        return (gzip ? gunzipSync : inflateSync)(data, { maxOutputLength: MAX_IDL_BYTES });
+    }
+    catch (e) {
+        if (e.code === "ERR_BUFFER_TOO_LARGE" || e instanceof RangeError)
+            throw new Error(`${what} inflates to more than ${MAX_IDL_BYTES / 1024 / 1024} MiB; refusing it`);
+        throw new Error(`${what} is not valid compressed data: ${e.message}`);
+    }
+}
+/**
+ * Read an IDL back (canonical, or the one `authority` wrote). Only an IDL stored in the metadata account itself is
+ * read: one that links to a URL or points at another account is refused (nothing is fetched from where it points).
+ */
 export async function fetchIdl(rpc, program, authority = null) {
-    return JSON.parse(await fetchMetadataContent(rpc, program, "idl", authority));
+    const at = await metadataAddress(program, authority);
+    const account = await fetchMaybeMetadata(rpc, at);
+    if (!account.exists)
+        throw new Error(`no IDL metadata account at ${at}`);
+    const m = account.data;
+    if (m.dataLength > m.data.length)
+        throw new Error(`the IDL metadata at ${at} is truncated`);
+    const content = (what) => {
+        const raw = new Uint8Array(m.data.subarray(0, m.dataLength));
+        const bytes = m.compression === Compression.None ? raw : inflateCapped(raw, m.compression === Compression.Gzip, what);
+        // Base58 decodes in quadratic time: only small contents.
+        if (m.encoding === Encoding.Base58 && bytes.length > 64 * 1024)
+            throw new Error(`${what} is too large for base58`);
+        return decodeData(bytes, m.encoding);
+    };
+    if (m.dataSource === DataSource.Url) {
+        const url = content(`the IDL link at ${at}`);
+        throw new Error(`the IDL at ${at} is not stored on chain but linked: ${JSON.stringify(url.slice(0, 200))}. Fetch it yourself and pass the file (typesol client <idl.json>)`);
+    }
+    if (m.dataSource !== DataSource.Direct)
+        throw new Error(`the IDL at ${at} is stored in another account (external data), which is not read`);
+    return JSON.parse(content(`the IDL at ${at}`));
 }
 /** Where `anchor idl init` keeps a program's IDL: an account derived with seed "anchor:idl" from the program's base PDA. */
 export async function anchorIdlAddress(program) {
     const [base] = await getProgramDerivedAddress({ programAddress: program, seeds: [] });
     return createAddressWithSeed({ baseAddress: base, programAddress: program, seed: "anchor:idl" });
 }
+/** Anchor's account discriminator for IdlAccount: sha256("account:IdlAccount")[0..8]. */
+const IDL_ACCOUNT_DISCRIMINATOR = createHash("sha256").update("account:IdlAccount").digest().subarray(0, 8);
 /** The IDL in Anchor's IDL account (`anchor idl init`), or null when the program has none. */
 export async function fetchAnchorIdl(rpc, program) {
     const { value } = await rpc.getAccountInfo(await anchorIdlAddress(program), { encoding: "base64" }).send();
@@ -129,10 +169,12 @@ export async function fetchAnchorIdl(rpc, program) {
     // IdlAccount: 8-byte discriminator, authority (32 bytes), a u32 length, then the zlib-compressed JSON.
     if (data.length < 44)
         throw new Error("Anchor IDL account is too short");
+    if (!data.subarray(0, 8).equals(IDL_ACCOUNT_DISCRIMINATOR))
+        throw new Error("the account at Anchor's IDL address is not an IdlAccount");
     const len = data.readUInt32LE(40);
     if (44 + len > data.length)
         throw new Error("Anchor IDL account is truncated");
-    return JSON.parse(inflateSync(data.subarray(44, 44 + len)).toString("utf8"));
+    return JSON.parse(inflateCapped(data.subarray(44, 44 + len), false, "the Anchor IDL").toString("utf8"));
 }
 /**
  * A program's IDL from the chain: the canonical Program Metadata IDL (`typesol idl publish`, Codama) first, else

package/dist/portgen.js

@@ -152,7 +152,7 @@ export function generatePort(idl) {
         if (t.vec) {
             const inner = tsType(t.vec, where, at);
             if (where === "variant" || where === "struct" || (where === "account" && !last)) {
-                notes.push(`${at}: a Vec here (TypeSOL keeps a Vec only as an account's last field or as an argument); replaced by FixedArray, so the layout differs.`);
+                notes.push(`${at}: a Vec here (TypeSOL keeps Anchor's bytes for a growable Vec only as an account's last field or as an argument); replaced by FixedArray, so the layout differs.`);
                 return `${use("FixedArray")}<${inner}, 8> /* TODO: Anchor has a Vec here */`;
             }
             return `${use("Vec")}<${inner}>`;

package/dist/svmrpc.d.ts

@@ -8,7 +8,11 @@
  *   await counter.accounts.Counter.fetch(rpc, address);
  *
  * Transactions run as they are sent (confirmed at once). LiteSVM cannot list accounts, so `getProgramAccounts` scans
- * the accounts transactions sent through this connection named, plus those passed to `track`.
+ * the accounts transactions sent through this connection named, plus those passed to `track`. Subscriptions see the
+ * transactions sent through this connection: `logsNotifications` replays those sent so far (failed ones too, with
+ * `err` set), then each new one, as `{ mentions: [address] }` filters them; `accountNotifications` yields the account
+ * after each later transaction that names it. Errors are in the JSON shape RPC nodes return
+ * (`{ InstructionError: [0, { Custom: 6000 }] }`).
  */
 import { type Address, type Rpc, type RpcSubscriptions, type SolanaRpcApi, type SolanaRpcSubscriptionsApi } from "@solana/kit";
 import { type LiteSVM, type TransactionMetadata } from "litesvm";
@@ -23,4 +27,6 @@ export interface SvmConnection {
     /** Add accounts for `getProgramAccounts` to scan (accounts the transactions named are scanned already). */
     track(...addresses: Address[]): void;
 }
+/** A LiteSVM transaction error in the JSON shape RPC nodes return: `{ InstructionError: [0, { Custom: 6000 }] }`. */
+export declare function rpcError(err: unknown): unknown;
 export declare function svmConnection(svm: LiteSVM): SvmConnection;

package/dist/svmrpc.js

@@ -8,15 +8,81 @@
  *   await counter.accounts.Counter.fetch(rpc, address);
  *
  * Transactions run as they are sent (confirmed at once). LiteSVM cannot list accounts, so `getProgramAccounts` scans
- * the accounts transactions sent through this connection named, plus those passed to `track`.
+ * the accounts transactions sent through this connection named, plus those passed to `track`. Subscriptions see the
+ * transactions sent through this connection: `logsNotifications` replays those sent so far (failed ones too, with
+ * `err` set), then each new one, as `{ mentions: [address] }` filters them; `accountNotifications` yields the account
+ * after each later transaction that names it. Errors are in the JSON shape RPC nodes return
+ * (`{ InstructionError: [0, { Custom: 6000 }] }`).
  */
 import { getAddressDecoder, getBase58Decoder, getBase58Encoder, getBase64Decoder, getBase64Encoder, getCompiledTransactionMessageDecoder, getTransactionDecoder, } from "@solana/kit";
 import { FailedTransactionMetadata } from "litesvm";
 const b64 = (bytes) => getBase64Decoder().decode(bytes);
 const reply = (value) => ({ send: async () => value });
+// LiteSVM's fieldless error enums by value (const enums: their names are not there at run time).
+const TX_ERRORS = ("AccountInUse AccountLoadedTwice AccountNotFound ProgramAccountNotFound InsufficientFundsForFee InvalidAccountForFee " +
+    "AlreadyProcessed BlockhashNotFound CallChainTooDeep MissingSignatureForFee InvalidAccountIndex SignatureFailure " +
+    "InvalidProgramForExecution SanitizeFailure ClusterMaintenance AccountBorrowOutstanding WouldExceedMaxBlockCostLimit " +
+    "UnsupportedVersion InvalidWritableAccount WouldExceedMaxAccountCostLimit WouldExceedAccountDataBlockLimit " +
+    "TooManyAccountLocks AddressLookupTableNotFound InvalidAddressLookupTableOwner InvalidAddressLookupTableData " +
+    "InvalidAddressLookupTableIndex InvalidRentPayingAccount WouldExceedMaxVoteCostLimit WouldExceedAccountDataTotalLimit " +
+    "MaxLoadedAccountsDataSizeExceeded ResanitizationNeeded InvalidLoadedAccountsDataSizeLimit UnbalancedTransaction " +
+    "ProgramCacheHitMaxLimit CommitCancelled").split(" ");
+const IX_ERRORS = ("GenericError InvalidArgument InvalidInstructionData InvalidAccountData AccountDataTooSmall InsufficientFunds " +
+    "IncorrectProgramId MissingRequiredSignature AccountAlreadyInitialized UninitializedAccount UnbalancedInstruction " +
+    "ModifiedProgramId ExternalAccountLamportSpend ExternalAccountDataModified ReadonlyLamportChange ReadonlyDataModified " +
+    "DuplicateAccountIndex ExecutableModified RentEpochModified NotEnoughAccountKeys AccountDataSizeChanged " +
+    "AccountNotExecutable AccountBorrowFailed AccountBorrowOutstanding DuplicateAccountOutOfSync InvalidError " +
+    "ExecutableDataModified ExecutableLamportChange ExecutableAccountNotRentExempt UnsupportedProgramId CallDepth " +
+    "MissingAccount ReentrancyNotAllowed MaxSeedLengthExceeded InvalidSeeds InvalidRealloc ComputationalBudgetExceeded " +
+    "PrivilegeEscalation ProgramEnvironmentSetupFailure ProgramFailedToComplete ProgramFailedToCompile Immutable " +
+    "IncorrectAuthority AccountNotRentExempt InvalidAccountOwner ArithmeticOverflow UnsupportedSysvar IllegalOwner " +
+    "MaxAccountsDataAllocationsExceeded MaxAccountsExceeded MaxInstructionTraceLengthExceeded " +
+    "BuiltinProgramsMustConsumeComputeUnits BorshIoError").split(" ");
+/** A LiteSVM transaction error in the JSON shape RPC nodes return: `{ InstructionError: [0, { Custom: 6000 }] }`. */
+export function rpcError(err) {
+    if (typeof err === "number")
+        return TX_ERRORS[err] ?? String(err);
+    if (typeof err !== "object" || err === null)
+        return String(err);
+    const o = err;
+    if (typeof o.err === "function" && typeof o.index === "number") {
+        const inner = o.err.call(err);
+        const fields = (typeof inner === "object" && inner !== null ? inner : {});
+        const ix = typeof inner === "number"
+            ? (IX_ERRORS[inner] ?? String(inner))
+            : typeof fields.code === "number"
+                ? { Custom: fields.code }
+                : typeof fields.msg === "string"
+                    ? { BorshIoError: fields.msg }
+                    : String(inner);
+        return { InstructionError: [o.index, ix] };
+    }
+    if (typeof o.index === "number")
+        return { DuplicateInstruction: o.index };
+    if (typeof o.accountIndex === "number")
+        return /Restricted/.test(String(err))
+            ? { ProgramExecutionTemporarilyRestricted: { account_index: o.accountIndex } }
+            : { InsufficientFundsForRent: { account_index: o.accountIndex } };
+    return String(err);
+}
 export function svmConnection(svm) {
     const transactions = [];
     const known = new Set();
+    // Every transaction sent (failed ones too) for log subscriptions, the account keys of each, and live subscribers.
+    const sent = [];
+    const accountKeys = new Map();
+    const logListeners = new Set();
+    const accountListeners = new Map();
+    const record = (n) => {
+        sent.push(n);
+        for (const l of [...logListeners])
+            l(n);
+        // A failed transaction changed no account.
+        if (n.err === null)
+            for (const k of new Set(n.keys))
+                for (const l of [...(accountListeners.get(k) ?? [])])
+                    l();
+    };
     const decode = (wire) => {
         const tx = getTransactionDecoder().decode(getBase64Encoder().encode(wire));
         return { tx, keys: getCompiledTransactionMessageDecoder().decode(tx.messageBytes).staticAccounts };
@@ -50,12 +116,17 @@ export function svmConnection(svm) {
                 const { tx, keys } = decode(wire);
                 const res = svm.sendTransaction(tx);
                 svm.expireBlockhash();
-                if (res instanceof FailedTransactionMetadata)
-                    throw new Error(`transaction failed: ${String(res.err())}\n${res.meta().logs().join("\n")}`);
+                if (res instanceof FailedTransactionMetadata) {
+                    const meta = res.meta();
+                    record({ signature: getBase58Decoder().decode(meta.signature()), logs: meta.logs(), err: rpcError(res.err()), keys });
+                    throw new Error(`transaction failed: ${String(res.err())}\n${meta.logs().join("\n")}`);
+                }
                 for (const k of keys)
                     known.add(k);
                 const signature = getBase58Decoder().decode(res.signature());
                 transactions.push({ signature, meta: res });
+                accountKeys.set(signature, keys);
+                record({ signature, logs: res.logs(), err: null, keys });
                 return signature;
             },
         }),
@@ -77,7 +148,7 @@ export function svmConnection(svm) {
                 if (res instanceof FailedTransactionMetadata)
                     return {
                         context: { slot: 0n },
-                        value: { err: String(res.err()), logs: res.meta().logs(), unitsConsumed: res.meta().computeUnitsConsumed(), returnData: null },
+                        value: { err: rpcError(res.err()), logs: res.meta().logs(), unitsConsumed: res.meta().computeUnitsConsumed(), returnData: null },
                     };
                 const meta = res.meta();
                 const ret = meta.returnData();
@@ -108,38 +179,81 @@ export function svmConnection(svm) {
                 return want.every((b, i) => data[Number(memcmp.offset) + i] === b);
             });
         })),
-        // The json shape: log messages, and inner instructions with base58 data (what `eventsOf` reads).
+        // The json shape: account keys, log messages, and inner instructions with their program and base58 data (what
+        // `eventsOf` reads).
         getTransaction: (signature) => {
             const t = transactions.find((x) => x.signature === signature);
             return reply(t
                 ? {
                     slot: 0n,
                     blockTime: null,
+                    transaction: { signatures: [signature], message: { accountKeys: accountKeys.get(signature) ?? [] } },
                     meta: {
                         err: null,
                         logMessages: t.meta.logs(),
                         computeUnitsConsumed: t.meta.computeUnitsConsumed(),
-                        innerInstructions: t.meta
-                            .innerInstructions()
-                            .map((group, index) => ({ index, instructions: group.map((i) => ({ data: getBase58Decoder().decode(i.instruction().data()) })) })),
+                        innerInstructions: t.meta.innerInstructions().map((group, index) => ({
+                            index,
+                            instructions: group.map((i) => ({
+                                programIdIndex: i.instruction().programIdIndex(),
+                                accounts: [...i.instruction().accounts()],
+                                data: getBase58Decoder().decode(i.instruction().data()),
+                                stackHeight: i.stackHeight(),
+                            })),
+                        })),
                     },
                 }
                 : null);
         },
     };
-    /** Notifications that end when the subscriber aborts. */
-    const stream = (items) => ({
-        subscribe: async ({ abortSignal }) => (async function* () {
-            for (const item of items())
-                yield item;
-            await new Promise((resolve) => abortSignal.addEventListener("abort", resolve, { once: true }));
-        })(),
+    /**
+     * Notifications: `backlog` first, then each item `listen` pushes, until the subscriber aborts. The listener is in
+     * place once `subscribe` is called, so nothing sent after that call is missed.
+     */
+    const stream = (backlog, listen) => ({
+        subscribe: async ({ abortSignal }) => {
+            const queue = [...backlog()];
+            let wake;
+            const stop = listen((item) => {
+                queue.push(item);
+                wake?.();
+            });
+            const aborted = new Promise((resolve) => abortSignal.addEventListener("abort", () => resolve(), { once: true }));
+            void aborted.then(stop);
+            return (async function* () {
+                while (!abortSignal.aborted) {
+                    if (queue.length) {
+                        yield queue.shift();
+                        continue;
+                    }
+                    await Promise.race([aborted, new Promise((resolve) => (wake = resolve))]);
+                    wake = undefined;
+                }
+            })();
+        },
     });
+    const none = () => () => undefined;
     const rpcSubscriptions = {
-        signatureNotifications: () => stream(() => [{ context: { slot: 0n }, value: { err: null } }]),
-        slotNotifications: () => stream(() => []),
-        logsNotifications: () => stream(() => transactions.map((t) => ({ context: { slot: 0n }, value: { signature: t.signature, logs: t.meta.logs(), err: null } }))),
-        accountNotifications: (a) => stream(() => [{ context: { slot: 0n }, value: encoded(a) ?? { data: ["", "base64"], lamports: 0n } }]),
+        signatureNotifications: () => stream(() => [{ context: { slot: 0n }, value: { err: null } }], none),
+        slotNotifications: () => stream(() => [], none),
+        logsNotifications: (filter = "all") => {
+            const wanted = (n) => typeof filter !== "object" || filter.mentions.every((a) => n.keys.includes(a));
+            const shape = (n) => ({ context: { slot: 0n }, value: { signature: n.signature, logs: n.logs, err: n.err } });
+            return stream(() => sent.filter(wanted).map(shape), (push) => {
+                const l = (n) => {
+                    if (wanted(n))
+                        push(shape(n));
+                };
+                logListeners.add(l);
+                return () => logListeners.delete(l);
+            });
+        },
+        accountNotifications: (a) => stream(() => [], (push) => {
+            const l = () => push({ context: { slot: 0n }, value: encoded(a) ?? { data: ["", "base64"], lamports: 0n } });
+            const set = accountListeners.get(a) ?? new Set();
+            accountListeners.set(a, set.add(l));
+            return () => set.delete(l);
+        }),
     };
     return {
         rpc: rpc,

package/dist/testing.js

@@ -313,13 +313,33 @@ export function programHarness(svm, programId, idl) {
                 throw new Error(`${instruction} returns nothing`);
             const data = Buffer.from(harness.ok(res).returnData().data());
             const t = def.returns;
+            const short = (n) => {
+                if (data.length < n)
+                    throw new Error(`${instruction} returned ${data.length} bytes; a ${String(t)} needs ${n}`);
+            };
             if (typeof t === "string") {
                 if (t === "pubkey")
-                    return getAddressDecoder().decode(data);
+                    return (short(32), getAddressDecoder().decode(data));
                 if (t === "bool")
-                    return (data[0] !== 0);
+                    return (short(1), data[0] !== 0);
+                if (t === "f32")
+                    return (short(4), data.readFloatLE(0));
+                if (t === "f64")
+                    return (short(8), data.readDoubleLE(0));
+                if (t === "string" || t === "bytes") {
+                    // Borsh: a u32 length, then the bytes (UTF-8 for a string).
+                    short(4);
+                    const len = data.readUInt32LE(0);
+                    short(4 + len);
+                    const body = data.subarray(4, 4 + len);
+                    return (t === "string" ? body.toString("utf8") : new Uint8Array(body));
+                }
+                const int = /^[ui](8|16|32|64|128)$/.exec(t);
+                if (!int)
+                    throw new Error(`decode ${instruction}'s return data yourself (${t})`);
                 const signed = t.startsWith("i");
-                const bytes = Number(t.slice(1)) / 8;
+                const bytes = Number(int[1]) / 8;
+                short(bytes);
                 let n = 0n;
                 for (let i = bytes - 1; i >= 0; i--)
                     n = (n << 8n) | BigInt(data[i]);