@typesol/cli 0.24.0 → 0.25.0

package/dist/compiler/emit/function.js

@@ -38,8 +38,10 @@ export class FunctionEmitter extends StatementEmitter {
             const k = a.kind;
             if (k.kind === "signer")
                 head.push(`  TS_TRY(ts_check_signer(${v}));`);
+            // Mut<…>: Anchor's `mut` (2000). Anchor checks it with the constraints, after seeds and associated token; here it
+            // sits with the type checks, which keeps binaries smaller (only a transaction breaking both sees the difference).
             if (isWritable(k))
-                head.push(`  TS_TRY(ts_check_writable(${v}));`);
+                head.push(`  TS_TRY(ts_check_mut(${v}));`);
             // A @layout borsh account only has to hold its smallest Borsh form (unpacking checks the rest).
             if (k.kind === "account")
                 head.push(`  TS_TRY(ts_check_program_account(${v}, params->program_id, TS_DISC_${k.struct.name}, ${k.struct.layout === "borsh" ? borshMinSize(k.struct, this.model) : emptySizeC(k.struct)}));`);
@@ -160,7 +162,9 @@ export class FunctionEmitter extends StatementEmitter {
                 pairs.push(`if (${present}a_${writable[i].name} == a_${writable[j].name}) TS_FAIL(TS_ERR_DUPLICATE_MUT, "TypeSOL: ${writable[i].name} and ${writable[j].name} must be different accounts");`);
             }
         head.push(...pairs.map((p) => `  ${p}`));
-        // Arguments: Borsh, read sequentially (strings make later offsets dynamic).
+        // Arguments: Borsh, read sequentially (strings make later offsets dynamic). Anchor decodes them before the accounts;
+        // here they come after the account types (decoding first keeps them live across the checks: larger binaries), so
+        // only a transaction wrong in both ways sees a different error.
         if (ix.args.length)
             head.push(`  uint64_t off = ${ix.discriminator.length};`);
         const need = (bytes) => head.push(`  if (params->data_len < off + ${bytes}) TS_FAIL(TS_ERR_INSTRUCTION_DATA, "TypeSOL: instruction data too short");`);
@@ -365,6 +369,11 @@ export class FunctionEmitter extends StatementEmitter {
             }),
         ];
     }
+    /**
+     * Each account's constraints, account by account in parameter order and, within one account, in Anchor's order
+     * (anchor-syn's `linearize`): seeds, associated token, has_one, owner, executable, address, token::, mint::.
+     * A transaction that breaks several checks then fails with the same error code as under Anchor.
+     */
     constraintChecks(ix) {
         const out = [];
         // Bumps found by Seeds<…> checks, declared ahead of the (possibly optional-guarded) checks for `acct.pdaBump`.
@@ -375,21 +384,40 @@ export class FunctionEmitter extends StatementEmitter {
             const k = a.kind.kind;
             if (c.hasOne.length && k !== "account" && k !== "token" && k !== "mint")
                 this.reporter.fail(a.node, "HasOne applies to existing accounts (Account<T> / Mut<T>), TokenAccount and Mint");
-            for (const entry of c.hasOne) {
+            if (c.closeTo) {
+                const dest = ix.accounts.find((o) => o.name === c.closeTo);
+                if (!isWritable(dest.kind))
+                    this.reporter.fail(a.node, `CloseTo<…, "${c.closeTo}">: ${c.closeTo} must be writable (Mut<…>)`);
+            }
+            if (c.seeds)
+                out.push(...this.seedsCheck(ix, a, bumpDecls));
+            if (c.ata)
+                out.push(...this.ataCheck(ix, a));
+            // has_one on a program account; on a token account or mint the same entries are Anchor's token:: / mint::
+            // constraints, which come last.
+            const hasOne = [];
+            // Anchor's order inside token:: (authority, mint, token program) and mint:: (authorities, token program).
+            const rank = (e) => ["owner=", "mint=", "mintAuthority=", "freezeAuthority=", "tokenProgram="].findIndex((x) => e.startsWith(x));
+            const entries = k === "token" || k === "mint" ? [...c.hasOne].sort((x, y) => rank(x) - rank(y)) : c.hasOne;
+            for (const entry of entries) {
                 // "field=param" (TokenOf / MintOf) or a field checked against the parameter of the same name (HasOne).
                 const [f, p = f] = entry.split("=");
-                if (k === "token")
-                    out.push(f === "mint"
+                if (f === "tokenProgram")
+                    hasOne.push(`  if (!ts_key_eq(&a_${a.name}->owner, &a_${p}->key)) TS_FAIL(${k === "mint" ? "TS_ERR_MINT_TOKEN_PROGRAM" : "TS_ERR_TOKEN_TOKEN_PROGRAM"}, "TypeSOL: ${a.name} is not owned by ${p}");`);
+                else if (k === "token")
+                    hasOne.push(f === "mint"
                         ? `  if (!ts_key_eq(ts_token_mint(a_${a.name}), &a_${p}->key)) TS_FAIL(TS_ERR_TOKEN_MINT, "TypeSOL: ${a.name} is not a token account of ${p}");`
                         : `  if (!ts_key_eq(ts_token_owner(a_${a.name}), &a_${p}->key)) TS_FAIL(TS_ERR_TOKEN_OWNER, "TypeSOL: ${a.name} is not owned by ${p}");`);
                 else if (k === "mint") {
                     const at = f === "mintAuthority" ? 0 : 46;
                     const code = f === "mintAuthority" ? "TS_ERR_MINT_AUTHORITY" : "TS_ERR_FREEZE_AUTHORITY";
-                    out.push(`  if (ts_read_le(a_${a.name}->data + ${at}, 4) != 1 || !ts_key_eq((const SolPubkey *)(a_${a.name}->data + ${at + 4}), &a_${p}->key)) TS_FAIL(${code}, "TypeSOL: ${p} is not the ${f} of ${a.name}");`);
+                    hasOne.push(`  if (ts_read_le(a_${a.name}->data + ${at}, 4) != 1 || !ts_key_eq((const SolPubkey *)(a_${a.name}->data + ${at + 4}), &a_${p}->key)) TS_FAIL(${code}, "TypeSOL: ${p} is not the ${f} of ${a.name}");`);
                 }
                 else
-                    out.push(`  if (!ts_key_eq(&d_${a.name}->${f}, &a_${f}->key)) TS_FAIL(TS_ERR_CONSTRAINT, "TypeSOL: ${a.name}.${f} must be the ${f} account");`);
+                    hasOne.push(`  if (!ts_key_eq(&d_${a.name}->${f}, &a_${f}->key)) TS_FAIL(TS_ERR_CONSTRAINT, "TypeSOL: ${a.name}.${f} must be the ${f} account");`);
             }
+            if (k === "account")
+                out.push(...hasOne);
             if (c.owner) {
                 out.push(`  static const SolPubkey co_${a.name} = {${cBytes(c.owner.bytes)}};`);
                 out.push(`  if (!ts_key_eq(&a_${a.name}->owner, &co_${a.name})) TS_FAIL(TS_ERR_CONSTRAINT_OWNER, "TypeSOL: ${a.name} is not owned by the expected program");`);
@@ -400,138 +428,8 @@ export class FunctionEmitter extends StatementEmitter {
                 out.push(`  static const SolPubkey ca_${a.name} = {${cBytes(c.address.bytes)}};`);
                 out.push(`  if (!ts_key_eq(&a_${a.name}->key, &ca_${a.name})) TS_FAIL(TS_ERR_ADDRESS, "TypeSOL: ${a.name} is not the expected address");`);
             }
-            if (c.ata && a.kind.kind === "token" && a.kind.init) {
-                // Created in the body: the ATA program checks the address when it creates it, and createIfNeeded checks an
-                // existing one there. Only the IDL entry is recorded here.
-                const tp = ix.accounts.find((o) => o.kind.kind === "tokenProgram");
-                if (tp && !ix.pdas.has(a.name)) {
-                    ix.pdas.set(a.name, [
-                        { kind: "account", path: snakeCase(c.ata.owner) },
-                        { kind: "account", path: snakeCase(tp.name) },
-                        { kind: "account", path: snakeCase(c.ata.mint) },
-                    ]);
-                    ix.pdaPrograms.set(a.name, { kind: "const", value: ATA_PROGRAM_BYTES });
-                }
-            }
-            else if (c.ata) {
-                // The token program is the account's owner; an AccountInfo not created yet takes the instruction's token program.
-                let program = `&a_${a.name}->owner`;
-                if (k !== "token") {
-                    const tp = ix.accounts.find((o) => o.kind.kind === "tokenProgram");
-                    if (!tp)
-                        this.reporter.fail(a.node, "Ata<AccountInfo, …> needs a token program parameter to derive the address");
-                    program = `&a_${tp.name}->key`;
-                }
-                out.push(`  { SolPubkey ata_${a.name};`);
-                out.push(`    TS_TRY(ts_ata_address(&a_${c.ata.owner}->key, &a_${c.ata.mint}->key, ${program}, &ata_${a.name}));`);
-                out.push(`    if (!ts_key_eq(&ata_${a.name}, &a_${a.name}->key)) TS_FAIL(TS_ERR_ASSOCIATED, "TypeSOL: ${a.name} is not the associated token account of ${c.ata.owner} and ${c.ata.mint}"); }`);
-                // The address alone is not enough: legacy SPL Token lets an ATA's owner be reassigned.
-                if (k === "token") {
-                    out.push(`  if (!ts_key_eq(ts_token_mint(a_${a.name}), &a_${c.ata.mint}->key)) TS_FAIL(TS_ERR_TOKEN_MINT, "TypeSOL: ${a.name} is not a token account of ${c.ata.mint}");`);
-                    out.push(`  if (!ts_key_eq(ts_token_owner(a_${a.name}), &a_${c.ata.owner}->key)) TS_FAIL(TS_ERR_TOKEN_OWNER, "TypeSOL: ${a.name} is not owned by ${c.ata.owner}");`);
-                }
-                const tp = ix.accounts.find((o) => o.kind.kind === "tokenProgram");
-                if (tp && !ix.pdas.has(a.name)) {
-                    ix.pdas.set(a.name, [
-                        { kind: "account", path: snakeCase(c.ata.owner) },
-                        { kind: "account", path: snakeCase(tp.name) },
-                        { kind: "account", path: snakeCase(c.ata.mint) },
-                    ]);
-                    ix.pdaPrograms.set(a.name, { kind: "const", value: ATA_PROGRAM_BYTES });
-                }
-            }
-            if (c.closeTo) {
-                const dest = ix.accounts.find((o) => o.name === c.closeTo);
-                if (!isWritable(dest.kind))
-                    this.reporter.fail(a.node, `CloseTo<…, "${c.closeTo}">: ${c.closeTo} must be writable (Mut<…>)`);
-            }
-            if (c.seeds) {
-                const parts = [];
-                const idl = [];
-                for (const raw of c.seeds.names) {
-                    // "@name" refers to an account parameter (its key) or an argument (its bytes); anything else is a literal.
-                    const ref = raw.startsWith("@") ? raw.slice(1) : undefined;
-                    const n = ref ?? raw;
-                    // "@acct.field": a field of a struct account parameter (its data was checked in the head), Anchor's
-                    // `seeds = [pool.amm.as_ref()]`. The account may be this one (`seeds = [offer.id.to_le_bytes()]`).
-                    if (ref?.includes(".")) {
-                        const [owner, field, ...rest] = ref.split(".");
-                        const o = ix.accounts.find((x) => x.name === owner);
-                        if (!o || o.kind.kind !== "account" || rest.length)
-                            this.reporter.fail(a.node, `Seeds: "@${ref}" must name a field of a struct account parameter ("@vault.owner")`);
-                        const st = o.kind.struct;
-                        const f = st.fields.find((x) => x.name === field);
-                        if (!f)
-                            this.reporter.fail(a.node, `Seeds: ${st.name} has no field "${field}"`);
-                        const t = f.type;
-                        if (t.kind === "pubkey")
-                            parts.push(`{(const uint8_t *)&d_${owner}->${field}, 32}`);
-                        else if (t.kind === "int" || t.kind === "enum")
-                            parts.push(`{(const uint8_t *)&d_${owner}->${field}, ${scalarSize(t)}}`);
-                        else
-                            this.reporter.fail(a.node, `Seeds: field "${ref}" of type ${typeName(t)} cannot be a seed (use a Pubkey, an integer or a unit enum)`);
-                        idl.push({ kind: "account", path: `${snakeCase(owner)}.${snakeCase(field)}`, account: st.name });
-                        continue;
-                    }
-                    const acct = ref ? ix.accounts.find((o) => o.name === ref) : undefined;
-                    const arg = ref ? ix.args.find((o) => o.name === ref) : undefined;
-                    if (ref && !acct && !arg)
-                        this.reporter.fail(a.node, `Seeds: "@${ref}" is neither an account parameter nor an argument`);
-                    if (acct) {
-                        parts.push(`{(const uint8_t *)&a_${n}->key, 32}`);
-                        idl.push({ kind: "account", path: snakeCase(n) });
-                    }
-                    else if (arg) {
-                        const t = arg.type;
-                        if (t.kind === "string")
-                            parts.push(`{arg_${n}.ptr, arg_${n}.len}`);
-                        else if (t.kind === "pubkey")
-                            parts.push(`{(const uint8_t *)&arg_${n}, 32}`);
-                        else if (t.kind === "int" || t.kind === "enum")
-                            parts.push(`{(const uint8_t *)&arg_${n}, ${scalarSize(t)}}`);
-                        else
-                            this.reporter.fail(a.node, `Seeds: argument "${n}" of type ${typeName(t)} cannot be a seed`);
-                        idl.push({ kind: "arg", path: snakeCase(n) });
-                    }
-                    else {
-                        if (Buffer.byteLength(n, "utf8") > 32)
-                            this.reporter.fail(a.node, "a seed can be at most 32 bytes");
-                        parts.push(`{(const uint8_t *)${cString(n)}, ${Buffer.byteLength(n, "utf8")}}`);
-                        idl.push({ kind: "const", value: [...Buffer.from(n, "utf8")] });
-                    }
-                }
-                if (!ix.pdas.has(a.name))
-                    ix.pdas.set(a.name, idl);
-                // The deriving program: this one, another account parameter ("@name"), or a fixed address.
-                let program = "params->program_id";
-                const p = c.seeds.program;
-                if (p?.startsWith("@")) {
-                    const pa = ix.accounts.find((o) => o.name === p.slice(1));
-                    if (!pa)
-                        this.reporter.fail(a.node, `Seeds program: "${p}" is not an account parameter`);
-                    program = `&a_${pa.name}->key`;
-                    ix.pdaPrograms.set(a.name, { kind: "account", path: snakeCase(pa.name) });
-                }
-                else if (p) {
-                    const bytes = [...decodeAddress(p)];
-                    out.push(`  static const SolPubkey sp_${a.name} = {${cBytes(bytes)}};`);
-                    program = `&sp_${a.name}`;
-                    ix.pdaPrograms.set(a.name, { kind: "const", value: bytes });
-                }
-                const seeds = `cs_${a.name}`;
-                out.push(`  SolSignerSeed ${seeds}[${parts.length + 1}] = {${parts.join(", ")}};`);
-                if (c.seeds.bump) {
-                    out.push(`  ${seeds}[${parts.length}] = (SolSignerSeed){&d_${a.name}->${c.seeds.bump}, 1};`);
-                    out.push(`  TS_TRY(ts_require_pda(a_${a.name}, ${seeds}, ${parts.length + 1}, ${program}));`);
-                    this.bumps.set(a.name, `d_${a.name}->${c.seeds.bump}`);
-                }
-                else {
-                    bumpDecls.push(`  uint8_t sb_${a.name}; (void)sb_${a.name};`);
-                    out.push(`  { SolPubkey pda_${a.name};`);
-                    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}`);
-                }
-            }
+            if (k !== "account")
+                out.push(...hasOne);
             // Constraints run only when every optional account they mention was passed.
             const lines = out.splice(start);
             const optional = this.optionalIn(lines.join("\n"));
@@ -542,6 +440,138 @@ export class FunctionEmitter extends StatementEmitter {
         }
         return [...bumpDecls, ...out];
     }
+    /** Ata<…>: the account's owner (2015) and address (2009) as Anchor checks them, then its mint. */
+    ataCheck(ix, a) {
+        const out = [];
+        const c = a.constraints;
+        const k = a.kind.kind;
+        const ata = c.ata;
+        // With two token programs the address depends on which the mint uses: no IDL derivation, and an Ata<AccountInfo>
+        // (derived here) is refused.
+        const tps = ix.accounts.filter((o) => o.kind.kind === "tokenProgram");
+        const tp = tps.length === 1 ? tps[0] : undefined;
+        if (tp && !ix.pdas.has(a.name)) {
+            ix.pdas.set(a.name, [
+                { kind: "account", path: snakeCase(ata.owner) },
+                { kind: "account", path: snakeCase(tp.name) },
+                { kind: "account", path: snakeCase(ata.mint) },
+            ]);
+            ix.pdaPrograms.set(a.name, { kind: "const", value: ATA_PROGRAM_BYTES });
+        }
+        // Created in the body: the ATA program checks the address when it creates it, and createIfNeeded checks an
+        // existing one there. Only the IDL entry is recorded.
+        if (k === "token" && a.kind.init)
+            return out;
+        // The address alone is not enough: legacy SPL Token lets an ATA's owner be reassigned.
+        if (k === "token")
+            out.push(`  if (!ts_key_eq(ts_token_owner(a_${a.name}), &a_${ata.owner}->key)) TS_FAIL(TS_ERR_TOKEN_OWNER, "TypeSOL: ${a.name} is not owned by ${ata.owner}");`);
+        // The token program is the account's owner; an AccountInfo not created yet takes the instruction's token program.
+        let program = `&a_${a.name}->owner`;
+        if (k !== "token") {
+            if (!tp)
+                this.reporter.fail(a.node, tps.length
+                    ? "Ata<AccountInfo, …> needs exactly one token program parameter to derive the address; use TokenInterface"
+                    : "Ata<AccountInfo, …> needs a token program parameter to derive the address");
+            program = `&a_${tp.name}->key`;
+        }
+        out.push(`  { SolPubkey ata_${a.name};`);
+        out.push(`    TS_TRY(ts_ata_address(&a_${ata.owner}->key, &a_${ata.mint}->key, ${program}, &ata_${a.name}));`);
+        out.push(`    if (!ts_key_eq(&ata_${a.name}, &a_${a.name}->key)) TS_FAIL(TS_ERR_ASSOCIATED, "TypeSOL: ${a.name} is not the associated token account of ${ata.owner} and ${ata.mint}"); }`);
+        if (k === "token")
+            out.push(`  if (!ts_key_eq(ts_token_mint(a_${a.name}), &a_${ata.mint}->key)) TS_FAIL(TS_ERR_TOKEN_MINT, "TypeSOL: ${a.name} is not a token account of ${ata.mint}");`);
+        return out;
+    }
+    /** Seeds<…>: the account is the PDA of its seeds (with the stored bump, or the canonical one found here). */
+    seedsCheck(ix, a, bumpDecls) {
+        const out = [];
+        const c = a.constraints;
+        const parts = [];
+        const idl = [];
+        for (const raw of c.seeds.names) {
+            // "@name" refers to an account parameter (its key) or an argument (its bytes); anything else is a literal.
+            const ref = raw.startsWith("@") ? raw.slice(1) : undefined;
+            const n = ref ?? raw;
+            // "@acct.field": a field of a struct account parameter (its data was checked in the head), Anchor's
+            // `seeds = [pool.amm.as_ref()]`. The account may be this one (`seeds = [offer.id.to_le_bytes()]`).
+            if (ref?.includes(".")) {
+                const [owner, field, ...rest] = ref.split(".");
+                const o = ix.accounts.find((x) => x.name === owner);
+                if (!o || o.kind.kind !== "account" || rest.length)
+                    this.reporter.fail(a.node, `Seeds: "@${ref}" must name a field of a struct account parameter ("@vault.owner")`);
+                const st = o.kind.struct;
+                const f = st.fields.find((x) => x.name === field);
+                if (!f)
+                    this.reporter.fail(a.node, `Seeds: ${st.name} has no field "${field}"`);
+                const t = f.type;
+                if (t.kind === "pubkey")
+                    parts.push(`{(const uint8_t *)&d_${owner}->${field}, 32}`);
+                else if (t.kind === "int" || t.kind === "enum")
+                    parts.push(`{(const uint8_t *)&d_${owner}->${field}, ${scalarSize(t)}}`);
+                else
+                    this.reporter.fail(a.node, `Seeds: field "${ref}" of type ${typeName(t)} cannot be a seed (use a Pubkey, an integer or a unit enum)`);
+                idl.push({ kind: "account", path: `${snakeCase(owner)}.${snakeCase(field)}`, account: st.name });
+                continue;
+            }
+            const acct = ref ? ix.accounts.find((o) => o.name === ref) : undefined;
+            const arg = ref ? ix.args.find((o) => o.name === ref) : undefined;
+            if (ref && !acct && !arg)
+                this.reporter.fail(a.node, `Seeds: "@${ref}" is neither an account parameter nor an argument`);
+            if (acct) {
+                parts.push(`{(const uint8_t *)&a_${n}->key, 32}`);
+                idl.push({ kind: "account", path: snakeCase(n) });
+            }
+            else if (arg) {
+                const t = arg.type;
+                if (t.kind === "string")
+                    parts.push(`{arg_${n}.ptr, arg_${n}.len}`);
+                else if (t.kind === "pubkey")
+                    parts.push(`{(const uint8_t *)&arg_${n}, 32}`);
+                else if (t.kind === "int" || t.kind === "enum")
+                    parts.push(`{(const uint8_t *)&arg_${n}, ${scalarSize(t)}}`);
+                else
+                    this.reporter.fail(a.node, `Seeds: argument "${n}" of type ${typeName(t)} cannot be a seed`);
+                idl.push({ kind: "arg", path: snakeCase(n) });
+            }
+            else {
+                if (Buffer.byteLength(n, "utf8") > 32)
+                    this.reporter.fail(a.node, "a seed can be at most 32 bytes");
+                parts.push(`{(const uint8_t *)${cString(n)}, ${Buffer.byteLength(n, "utf8")}}`);
+                idl.push({ kind: "const", value: [...Buffer.from(n, "utf8")] });
+            }
+        }
+        if (!ix.pdas.has(a.name))
+            ix.pdas.set(a.name, idl);
+        // The deriving program: this one, another account parameter ("@name"), or a fixed address.
+        let program = "params->program_id";
+        const p = c.seeds.program;
+        if (p?.startsWith("@")) {
+            const pa = ix.accounts.find((o) => o.name === p.slice(1));
+            if (!pa)
+                this.reporter.fail(a.node, `Seeds program: "${p}" is not an account parameter`);
+            program = `&a_${pa.name}->key`;
+            ix.pdaPrograms.set(a.name, { kind: "account", path: snakeCase(pa.name) });
+        }
+        else if (p) {
+            const bytes = [...decodeAddress(p)];
+            out.push(`  static const SolPubkey sp_${a.name} = {${cBytes(bytes)}};`);
+            program = `&sp_${a.name}`;
+            ix.pdaPrograms.set(a.name, { kind: "const", value: bytes });
+        }
+        const seeds = `cs_${a.name}`;
+        out.push(`  SolSignerSeed ${seeds}[${parts.length + 1}] = {${parts.join(", ")}};`);
+        if (c.seeds.bump) {
+            out.push(`  ${seeds}[${parts.length}] = (SolSignerSeed){&d_${a.name}->${c.seeds.bump}, 1};`);
+            out.push(`  TS_TRY(ts_require_pda(a_${a.name}, ${seeds}, ${parts.length + 1}, ${program}));`);
+            this.bumps.set(a.name, `d_${a.name}->${c.seeds.bump}`);
+        }
+        else {
+            bumpDecls.push(`  uint8_t sb_${a.name}; (void)sb_${a.name};`);
+            out.push(`  { SolPubkey pda_${a.name};`);
+            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}`);
+        }
+        return out;
+    }
     /** Optional account parameters a piece of generated C refers to (a_name / d_name). */
     optionalIn(code) {
         return (this.ix?.accounts ?? []).filter((a) => a.optional && new RegExp(`\\b[ad]_${a.name}\\b`).test(code)).map((a) => a.name);

package/dist/compiler/emit/program.js

@@ -137,6 +137,9 @@ export function emitProgram(analysis, opts = {}) {
     // refuse more than the array holds instead (ts_deserialize relies on this bound).
     out.push(`  if (*(const uint64_t *)input > TS_MAX_ACCOUNTS) TS_FAIL(TS_ERR_TOO_MANY_ACCOUNTS, "TypeSOL: at most ${MAX_ACCOUNTS} accounts per instruction");`);
     out.push(`  ts_deserialize(input, &params);`);
+    // loadAccountMut's record of the accounts it loaded: set up only in programs that use it (one store otherwise wasted).
+    if ([...helperBodies, ...ixBodies].some((b) => b.includes("ts_claim_mut(")))
+        out.push(`  params.loaded_mut = 0;`);
     const minDisc = Math.min(8, ...model.instructions.map((ix) => ix.discriminator.length));
     out.push(`  if (params.data_len < ${minDisc}) TS_FAIL(TS_ERR_INSTRUCTION_MISSING, "TypeSOL: instruction data too short");`);
     // Self-CPI events (emitCpi): accept the event instruction when its authority PDA signed it, like Anchor.

package/dist/compiler/emit/shared.d.ts

@@ -11,6 +11,7 @@ export declare const ATA_PROGRAM_BYTES: number[];
 export declare const U64: ScalarType;
 export declare const U8: ScalarType;
 export declare const I64: ScalarType;
+export declare const I32: ScalarType;
 export declare const BOOL: ScalarType;
 export declare const PUBKEY: ScalarType;
 export declare const STRING: ValueType;

package/dist/compiler/emit/shared.js

@@ -13,6 +13,7 @@ export const ATA_PROGRAM_BYTES = [
 export const U64 = { kind: "int", name: "u64" };
 export const U8 = { kind: "int", name: "u8" };
 export const I64 = { kind: "int", name: "i64" };
+export const I32 = { kind: "int", name: "i32" };
 export const BOOL = { kind: "bool" };
 export const PUBKEY = { kind: "pubkey" };
 export const STRING = { kind: "string" };

package/dist/compiler/emit/statements.d.ts

@@ -93,4 +93,10 @@ export declare abstract class StatementEmitter extends CpiEmitter {
     /** Whether a place goes through a Vec element (`v.get(i).x`, `v.get(i)`). */
     protected writesThroughVec(node: ts.Expression): boolean;
     protected helperTakesMutAccounts(node: ts.CallExpression): boolean;
+    /**
+     * Whether evaluating `node` may resize a growable Vec (and so move the Vecs after it): a push / pop / clear, a
+     * realloc or close, a helper taking a writable account or a function argument, or a closure (its body is not
+     * looked into: it may capture the account). Conservative: it only decides whether a Vec element may be the target.
+     */
+    protected mayResizeVecs(node: ts.Node): boolean;
 }

package/dist/compiler/emit/statements.js

@@ -1085,6 +1085,10 @@ export class StatementEmitter extends CpiEmitter {
         this.fail(e, "this expression has no effect; only assignments and calls can be statements");
     }
     assign(target, valueNode, op, topLevel = false) {
+        // The place is resolved before the right side runs (JS order). A right side that can resize a Vec of the account
+        // would move the element out from under it: the write would land in the bytes that follow.
+        if (this.writesThroughVec(target) && this.mayResizeVecs(valueNode))
+            this.fail(target, "the right side may change this Vec (a helper, closure or push/pop/clear); store its result in a local first");
         if (op !== undefined) {
             const place = this.place(target);
             let current = { c: place.read, type: place.type };
@@ -1143,8 +1147,6 @@ export class StatementEmitter extends CpiEmitter {
         const structCall = isCall && ts.isIdentifier(valueNode.expression)
             ? this.helperOf(valueNode)?.returns?.kind === "struct"
             : false;
-        if (structCall && this.writesThroughVec(target) && this.helperTakesMutAccounts(valueNode))
-            this.fail(target, "the right side calls a helper that may change this Vec; store its result in a local first");
         // Whole arrays / structs: copy between identical layouts.
         const targetRef = isCall && !structCall ? undefined : this.ref(target);
         if (targetRef &&
@@ -1161,9 +1163,6 @@ export class StatementEmitter extends CpiEmitter {
         }
         const place = this.place(target);
         if (isCall && !createsFirst) {
-            // A helper that may replace a Vec element would leave `place` pointing at the new one (JS writes the old object).
-            if (this.writesThroughVec(target) && this.helperTakesMutAccounts(valueNode))
-                this.fail(target, "the right side calls a helper that may change this Vec; store its result in a local first");
             raw = this.call(valueNode, topLevel);
             if (!raw)
                 this.fail(valueNode, "this call does not produce a value");
@@ -1194,4 +1193,35 @@ export class StatementEmitter extends CpiEmitter {
         const h = this.helperOf(node);
         return !!h?.params.some((p) => p.account && isWritable(p.account));
     }
+    /**
+     * Whether evaluating `node` may resize a growable Vec (and so move the Vecs after it): a push / pop / clear, a
+     * realloc or close, a helper taking a writable account or a function argument, or a closure (its body is not
+     * looked into: it may capture the account). Conservative: it only decides whether a Vec element may be the target.
+     */
+    mayResizeVecs(node) {
+        let found = false;
+        const isClosure = (e) => ts.isArrowFunction(e) || ts.isFunctionExpression(e) || (ts.isIdentifier(e) && !!this.lookup(e.text)?.closure);
+        const visit = (n) => {
+            if (found)
+                return;
+            if (ts.isCallExpression(n)) {
+                const callee = n.expression;
+                if (ts.isPropertyAccessExpression(callee) && ["push", "pop", "clear"].includes(callee.name.text))
+                    found = true;
+                else if (ts.isCallExpression(callee))
+                    found = true; // a function a function returns
+                else if (ts.isIdentifier(callee)) {
+                    if (this.lookup(callee.text)?.closure)
+                        found = true;
+                    else if (["realloc", "close"].includes(this.exportName(callee) ?? ""))
+                        found = true;
+                    else if (this.helperOf(n) && (this.helperTakesMutAccounts(n) || n.arguments.some(isClosure)))
+                        found = true;
+                }
+            }
+            ts.forEachChild(n, visit);
+        };
+        visit(node);
+        return found;
+    }
 }

package/docs/architecture.md

@@ -22,6 +22,21 @@ program.so + program.build.json (manifest: versions, sha256 of sources and binar
 `compiler/index.ts` wires the stages together. `generate()` runs analyze, emit and IDL generation in memory, and
 `build()` also compiles and writes the output files.
 
+## Repository layout
+
+| Path | Contents |
+| --- | --- |
+| `src/` | The compiler (`src/compiler/`) and the tools around it: CLI, workspace, client, CPI and port generators, testing, IDL publishing (source map below) |
+| `runtime/` | `typesol_rt.h`, the C runtime every program includes ([runtime.md](runtime.md)) |
+| `lib/` | `typesol.d.ts`, the language surface programs typecheck against |
+| `ts-plugin/` | The editor plugin (`typesol/ts-plugin`) |
+| `examples/` | Example programs; the `typesol init` templates are copies of three of them |
+| `test/` | The test suite: `fixtures/` (programs the tests compile), `ports/` (TypeSOL rewrites of solana-developers/program-examples), `golden/` (pinned generated clients), `programs/` (third-party program binaries, see its SOURCES.md) |
+| `bench/anchor/` | Anchor twins of the counter, vault and escrow examples, for the differential tests (`pnpm bench:anchor`) and the zero-copy client test; the benchmarks themselves are in [typesol/benchmarks](https://github.com/typesol/benchmarks) |
+| `scripts/` | `smoke.ts` and `localnet.sh` (a local validator run), `fetch-programs.sh` (third-party binaries), `readme-bench.ts` (the README numbers) |
+| `docs/` | User and contributor documentation (also published on typesol.com) |
+| `assets/` | The CLI's logo and the README images (`readme/`, generated) |
+
 ## Source map
 
 | Path | Role |
@@ -34,11 +49,17 @@ program.so + program.build.json (manifest: versions, sha256 of sources and binar
 | `src/compiler/idl.ts` | Turns the model into an Anchor IDL: accounts with `pda`, `relations`, `address` and `optional`, plus types, events, errors and docs. |
 | `src/compiler/toolchain.ts` | Finds the Agave SDK and runs clang and lld with the SDK's flags, plus per-function sections, `--gc-sections` and `--strip-all` so unused code and symbol tables stay out of the binary. |
 | `src/compiler/diagnostics.ts` | `Reporter` and `CompileError`: diagnostics with file, line and column. |
+| `src/compiler/anchor-errors.ts` | Anchor's own error codes (`AnchorError.X`), shared by `require` and the generated clients. |
+| `src/compiler/index.ts` | The compiler's API (`generate`, `build`, `verifyBinary`, the build manifest). |
 | `runtime/typesol_rt.h` | The C runtime: error codes, word-wise memory helpers, the entry point's input parser (`ts_deserialize`), account checks, checked math, Borsh helpers, CPIs (System, Token, Token-2022, ATA, Metaplex), oracles and the heap allocator. Header-only and `static inline`, so unused code is dropped. |
 | `src/workspace.ts` | `typesol.json` projects, program keypairs, `typesol init` templates and deploy arguments. |
 | `src/cpigen.ts` | `typesol cpi`: reads an Anchor IDL and writes typed TypeSOL CPI helpers. |
 | `src/clientgen.ts` | The TypeScript client (`<name>.client.ts`, [client.md](client.md)): reads an IDL, validates it (it may come from anywhere), and writes one `@solana/kit` file. Not part of the compiler core: `workspace.ts` and the CLI write it after `build()`, and `typesol client` writes it for any IDL. |
-| `src/idlpublish.ts` | `typesol idl publish` through the Program Metadata program. |
+| `src/idlpublish.ts` | `typesol idl publish` through the Program Metadata program, and reading a program's IDL back from the chain (Program Metadata or Anchor's IDL account) for `typesol client --address`. |
+| `src/portgen.ts` | `typesol port`: a TypeSOL program skeleton from an Anchor IDL (structs, enums, errors, events, one function per instruction). |
+| `src/templates.ts` | The programs and tests `typesol init --template` writes (copies of `examples/`; a test checks they match). |
+| `src/svmrpc.ts` | `svmConnection`: a kit RPC and subscriptions pair answered by LiteSVM, so generated clients run in tests (exported by `typesol/testing`). |
+| `src/keys.ts` | Base58 and program keypair helpers. |
 | `ts-plugin/index.js` | `typesol/ts-plugin` (CommonJS, loaded by tsserver): runs `typesol check --json --stdin` on program entries and adds the diagnostics. |
 | `src/testing.ts` | `typesol/testing`: LiteSVM test helpers for projects (accounts by name from the IDL, plain values). |
 | `src/onchain.ts` | `typesol verify --address`: a deployed program's ELF, authority and deploy slot under loader v2, v3 or v4. |
@@ -54,7 +75,7 @@ call evaluates expressions), the method is declared `abstract` at the end of `ba
 
 | File | Layer | Contents |
 | --- | --- | --- |
-| `shared.ts` | | `Value`, `Ref` and `Local`, limits, and the C type helpers (`valueC`, `fieldC`, `storageDecl`, `cString`) |
+| `shared.ts` | | `Value`, `Ref` and `Local`, limits, and the C type helpers (`valueC`, `fieldC`, `storageDecl`, `cString`), growable Vec placement (`vecPlace`, `vecLenCheck`) |
 | `base.ts` | `EmitterBase` | function state; `line()`, `tmp()`, `settle()`, scopes, `fail()`, account lookup |
 | `storage.ts` | `StorageEmitter` | references into account data and locals, reads and writes, indexing, aliasing, argument validation |
 | `expressions.ts` | `ExpressionEmitter` | literals, operators and checked arithmetic, property reads, conditionals, text, casts |
@@ -63,6 +84,9 @@ call evaluates expressions), the method is declared `abstract` at the end of `ba
 | `statements.ts` | `StatementEmitter` | variables, assignment, `if`/loops/`switch`, `return` |
 | `function.ts` | `FunctionEmitter` | the instruction prologue (account checks, constraints, argument decoding) and epilogue |
 
+`borsh.ts` writes the Borsh pack/unpack codecs of `@layout borsh` structs, and `program.ts` assembles the C file
+(typedefs, codecs, helpers, instructions, the entry point). `index.ts` is the emitter's export.
+
 ## Rules the emitter keeps
 
 These invariants are easy to break. Each one has tests.