@typesol/cli 0.24.1 → 0.25.0

package/CHANGELOG.md

@@ -6,6 +6,36 @@ codes, and says so here.
 
 ## Unreleased
 
+## 0.25.0 — 2026-10-29
+
+Security review (October 2026) fixes, and error codes aligned with Anchor. Some refused transactions now report a
+different error code (below): a minor version.
+
+- Fixed: `loadAccountMut` on the same remaining account twice (`rest.get(i)`, `rest.get(j)` with `i == j`) gave two
+  writable views of one account; a program reading both before writing both could be made to create value. The second
+  load is now refused with 2040.
+- Fixed: a Vec element written with a right side that resizes the Vec (`book.bids.get(i).qty += settle(book)` where the
+  helper pops, a closure, or a `push` / `pop` / `clear` in the expression) wrote through the element's old position,
+  into the bytes of the next Vec. Such an assignment is now a compile error ("store its result in a local first"),
+  as it already was for a plain `=` with a helper.
+- Fixed: `Ata<Init<…>>` / `Ata<InitIfNeeded<…>>` creation and `Ata<AccountInfo, …>` with two token program parameters
+  used the first one; they now need exactly one (use `TokenInterface`).
+- New: `TokenOf<…, …, …, "tokenProgram">` / `MintOf<…, …, …, "tokenProgram">`, Anchor's `token::token_program` /
+  `mint::token_program` (2021 / 2022). The escrow port uses it.
+- New: `pythPrice(update, feedId, maxAge, exponent)` refuses a feed whose exponent is not the one given;
+  `switchboardValue(…, minSamples)` refuses a result resting on fewer oracle samples.
+- Changed: each account's constraints are checked in Anchor's order (seeds, associated token account, has_one, owner,
+  executable, address, token::, mint::), so a transaction breaking several fails with Anchor's code: e.g. a stranger's
+  call on a `Seeds<HasOne<…>>` account now fails with 2006 (ConstraintSeeds) instead of 2001, and an `Ata<…>` of
+  another wallet with 2015 instead of 2009. A `Mut<…>` account passed read-only fails with 2000 (ConstraintMut), as
+  Anchor's `#[account(mut)]`, instead of 3006. docs/errors.md lists the order and the differences left.
+- Docs: unchecked raw Pyth fields, `requirePda` with a bump from the arguments, Merkle leaves, and what
+  `createIfNeeded` leaves unchecked on an existing account.
+- Docs: [Case study: porting Anchor's escrow](docs/case-study-escrow.md), one Anchor program ported end to end, with the
+  differences, the checks run against the original and the cost.
+- Releases: the release workflow checks that CHANGELOG.md has the version, and after publishing installs the package
+  from npm, scaffolds a project from each template and runs its typecheck, build and test.
+
 ## 0.24.1 — 2026-10-28
 
 Smaller programs and fewer compute units, with the same results; no change to the language, IDLs or error codes. Also

package/README.md

@@ -162,8 +162,9 @@ existing project: `npm install -D typesol@npm:@typesol/cli`.
 Deploying again upgrades the program in place. Keep `target/deploy/<name>-keypair.json`: that keypair is your
 program's address.
 
-Coming from Anchor: [docs/migrate-from-anchor.md](docs/migrate-from-anchor.md) maps every construct, and `typesol port`
-starts from your program's IDL. Tests use `typesol/testing` (accounts by name, plain values; [docs/test-your-program.md](docs/test-your-program.md)). To go to
+Coming from Anchor: [docs/migrate-from-anchor.md](docs/migrate-from-anchor.md) maps every construct, `typesol port`
+starts from your program's IDL, and [docs/case-study-escrow.md](docs/case-study-escrow.md) follows one complete Anchor
+program through the port. Tests use `typesol/testing` (accounts by name, plain values; [docs/test-your-program.md](docs/test-your-program.md)). To go to
 mainnet (wallet, cost, deploy, IDL, verification), follow [docs/mainnet.md](docs/mainnet.md).
 
 ## How it works

package/dist/clientgen.js

@@ -32,6 +32,7 @@ export const TYPESOL_ERRORS = {
     100: "InstructionMissing",
     101: "InstructionFallbackNotFound",
     102: "InstructionDidNotDeserialize",
+    2000: "ConstraintMut",
     2001: "ConstraintHasOne",
     2002: "ConstraintSigner",
     2004: "ConstraintOwner",
@@ -45,6 +46,8 @@ export const TYPESOL_ERRORS = {
     2016: "ConstraintMintMintAuthority",
     2017: "ConstraintMintFreezeAuthority",
     2018: "ConstraintMintDecimals",
+    2021: "ConstraintTokenTokenProgram",
+    2022: "ConstraintMintTokenProgram",
     2040: "ConstraintDuplicateMutableAccount",
     3000: "AccountDiscriminatorAlreadySet",
     3002: "AccountDiscriminatorMismatch",

package/dist/compiler/analyze.js

@@ -1473,6 +1473,13 @@ function analyzeInstruction(fn, reporter, scope, structs) {
                 if (entry.includes("=")) {
                     if (!accounts.some((o) => o.name === param))
                         reporter.fail(a.node, `add an account parameter named "${param}"`);
+                    if (f === "tokenProgram") {
+                        if (a.kind.kind !== "token" && a.kind.kind !== "mint")
+                            reporter.fail(a.node, "TokenOf / MintOf apply to a TokenAccount / Mint");
+                        if (accounts.find((o) => o.name === param).kind.kind !== "tokenProgram")
+                            reporter.fail(a.node, `"${param}" must be a TokenProgram, Token2022Program or TokenInterface parameter`);
+                        continue;
+                    }
                     if (a.kind.kind === "token" ? f !== "mint" && f !== "owner" : a.kind.kind === "mint" ? false : true)
                         reporter.fail(a.node, a.kind.kind === "token" || a.kind.kind === "mint" ? "TokenOf<…> applies to a TokenAccount" : "TokenOf / MintOf apply to a TokenAccount / Mint");
                     if (a.kind.kind === "mint" && f !== "mintAuthority" && f !== "freezeAuthority")
@@ -1610,12 +1617,15 @@ function unwrapConstraints(node, reporter, imports, out) {
         const one = (t) => (t && t.kind !== ts.SyntaxKind.NeverKeyword ? lit(t)[0] : undefined);
         const p1 = one(args[1]);
         const p2 = one(args[2]);
-        if (!p1 && !p2)
+        const p3 = one(args[3]);
+        if (!p1 && !p2 && !p3)
             reporter.fail(node, `${name}<…> names at least one parameter`);
         if (p1)
             out.hasOne.push(`${first}=${p1}`);
         if (p2)
             out.hasOne.push(`${second}=${p2}`);
+        if (p3)
+            out.hasOne.push(`tokenProgram=${p3}`);
     }
     if (name === "CloseTo")
         out.closeTo = lit(args[1])[0];

package/dist/compiler/emit/calls.js

@@ -3,7 +3,7 @@ import { calleeName, resolveScalarType, resolveValueType } from "../analyze.js";
 import { ANCHOR_ERRORS } from "../anchor-errors.js";
 import { decodeAddress } from "../../keys.js";
 import { INT_INFO, INT_NAMES, isScalar, isWritable, sameType, scalarSize, typeName, } from "../model.js";
-import { U64, U8, I64, BOOL, PUBKEY, STRING, HASH, cBytes, cString, scalarC, scalarStorageC, optC, valueC, fieldC, storageDecl, accountMismatch, vecCount, emptySizeC, vecLenCheck, } from "./shared.js";
+import { U64, U8, I64, I32, BOOL, PUBKEY, STRING, HASH, cBytes, cString, scalarC, scalarStorageC, optC, valueC, fieldC, storageDecl, accountMismatch, vecCount, emptySizeC, vecLenCheck, } from "./shared.js";
 import { ExpressionEmitter } from "./expressions.js";
 /**
  * Calls: built-in functions, Vec methods, helpers, remaining accounts, foreign account reads and return data.
@@ -344,29 +344,29 @@ export class CallEmitter extends ExpressionEmitter {
                 return { c: `ts_secp256k1_verify(${h.c}, (uint64_t)${id.c}, ${r.c}, ${sv.c}, ${eth.c})`, type: BOOL };
             }
             case "pythPrice": {
-                if (args.length !== 3)
-                    this.fail(node, "pythPrice(update, feedId, maxAgeSeconds) takes three arguments");
+                if (args.length !== 3 && args.length !== 4)
+                    this.fail(node, "pythPrice(update, feedId, maxAgeSeconds, exponent?) takes three or four arguments");
                 const u = this.accountParam(args[0], "the price update");
                 if (u.kind.kind !== "pyth")
                     this.fail(args[0], "pass a PythPriceUpdate parameter");
-                const [feed, age] = this.lowerInOrder(args.slice(1), [HASH, U64]);
+                const [feed, age, expo] = this.lowerInOrder(args.slice(1), [HASH, U64, I32]);
                 const t = this.tmp("px");
                 this.line(`int64_t ${t};`);
-                this.line(`TS_TRY(ts_pyth_price(a_${u.name}, ${feed.c}, ${age.c}, &${t}));`);
+                this.line(`TS_TRY(ts_pyth_price(a_${u.name}, ${feed.c}, ${age.c}, ${expo ? `true, ${expo.c}` : "false, 0"}, &${t}));`);
                 return { c: t, type: I64 };
             }
             case "switchboardValue": {
                 // Anyone can create a Switchboard feed: like pythPrice's feed id, the expected feed address is required.
-                if (args.length !== 4)
-                    this.fail(node, "switchboardValue(feed, expectedFeed, maxStaleSlots, decimals) takes four arguments");
+                if (args.length !== 4 && args.length !== 5)
+                    this.fail(node, "switchboardValue(feed, expectedFeed, maxStaleSlots, decimals, minSamples?) takes four or five arguments");
                 const f = this.accountParam(args[0], "the feed");
                 if (f.kind.kind !== "switchboard")
                     this.fail(args[0], "pass a SwitchboardFeed parameter");
-                const [expected, stale, dec] = this.lowerInOrder(args.slice(1), [PUBKEY, U64, U8]);
+                const [expected, stale, dec, min] = this.lowerInOrder(args.slice(1), [PUBKEY, U64, U8, U8]);
                 const t = this.tmp("sb");
                 this.line(`int64_t ${t};`);
                 this.line(`if (!ts_key_eq(&a_${f.name}->key, ${expected.c})) TS_FAIL(TS_ERR_ORACLE, "TypeSOL: not the expected Switchboard feed");`);
-                this.line(`TS_TRY(ts_switchboard_value(a_${f.name}, ${stale.c}, ${dec.c}, &${t}));`);
+                this.line(`TS_TRY(ts_switchboard_value(a_${f.name}, ${stale.c}, ${dec.c}, ${min ? min.c : "1"}, &${t}));`);
                 return { c: t, type: I64 };
             }
             case "associatedTokenAddress": {
@@ -980,7 +980,7 @@ export class CallEmitter extends ExpressionEmitter {
                 this.line(l);
         if (mut) {
             this.line(`TS_TRY(ts_check_writable(${h}));`);
-            this.line(`TS_TRY(ts_check_unaliased(params, ${h}));`);
+            this.line(`TS_TRY(ts_claim_mut(params, ${h}));`);
         }
         return { c: `((TSS_${s.name} *)(${h}->data + 8))`, type: { kind: "structRef", struct: s.name, writable: mut } };
     }

package/dist/compiler/emit/cpi.js

@@ -774,6 +774,10 @@ export class CpiEmitter extends CallEmitter {
         const ataProgram = need("ataProgram", "an AssociatedTokenProgram");
         const system = need("system", "a SystemProgram");
         const tokenProgram = need("tokenProgram", "a token program (TokenProgram, Token2022Program or TokenInterface)");
+        // The address is derived under the token program: with two, which one the mint uses is not known here.
+        const tokenPrograms = this.ix.accounts.filter((o) => o.kind.kind === "tokenProgram");
+        if (tokenPrograms.length > 1)
+            this.fail(node, `${call}(...) needs exactly one token program parameter (found ${tokenPrograms.map((o) => o.name).join(", ")}); use TokenInterface`);
         const { owner, mint } = target.constraints.ata;
         const a = `a_${target.name}`;
         const create = `TS_TRY(ts_ata_create(params, a_${ataProgram.name}, a_${payer.name}, ${a}, a_${owner}, a_${mint}, a_${system.name}, a_${tokenProgram.name}, false));`;

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

@@ -9,7 +9,16 @@ export declare class FunctionEmitter extends StatementEmitter {
     emitInstruction(): string;
     /** CloseTo<…> accounts are closed when the instruction succeeds, at every return. */
     protected epilogue(): string[];
+    /**
+     * 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.
+     */
     protected constraintChecks(ix: Instruction): string[];
+    /** Ata<…>: the account's owner (2015) and address (2009) as Anchor checks them, then its mint. */
+    private ataCheck;
+    /** Seeds<…>: the account is the PDA of its seeds (with the stored bump, or the canonical one found here). */
+    private seedsCheck;
     /** Optional account parameters a piece of generated C refers to (a_name / d_name). */
     protected optionalIn(code: string): string[];
 }

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/case-study-escrow.md

@@ -0,0 +1,224 @@
+# Case study: porting Anchor's escrow
+
+This page follows one complete Anchor program into TypeSOL: the token escrow from
+[solana-developers/program-examples](https://github.com/solana-developers/program-examples/tree/de090195e4de698e150572c4f886c333323a64a5/tokens/escrow/anchor)
+(`tokens/escrow`, commit `de09019`). It shows the original and the port side by side, what changed, how the two were
+checked against each other, where they still differ, and what the port costs to run. The port is
+[`test/ports/tokens/escrow.ts`](../test/ports/tokens/escrow.ts); [Migrate from Anchor](migrate-from-anchor.md) is the
+general reference.
+
+## The program
+
+A maker offers an amount of token A for an amount of token B.
+
+- `make_offer(id, token_a_offered_amount, token_b_wanted_amount)` creates the offer account, a PDA at
+  `["offer", maker, id]`, creates the vault (the offer's associated token account for mint A) and moves the offered
+  tokens into it.
+- `take_offer()` sends token B from the taker to the maker, releases the vault to the taker, closes the vault and the
+  offer, and returns their rent to the maker. It creates the taker's mint A account and the maker's mint B account if
+  they do not exist.
+- `refund_offer()` returns the vault to the maker and closes both accounts.
+
+Upstream, this is 398 lines of Rust in ten files. The port is one 95-line TypeScript file.
+
+## Side by side
+
+### State
+
+```rust
+#[account]
+#[derive(InitSpace)]
+pub struct Offer {
+    pub id: u64,
+    pub maker: Pubkey,
+    pub token_mint_a: Pubkey,
+    pub token_mint_b: Pubkey,
+    pub token_b_wanted_amount: u64,
+    pub bump: u8,
+}
+```
+
+```ts
+export interface Offer {
+  id: u64;
+  maker: Pubkey;
+  tokenMintA: Pubkey;
+  tokenMintB: Pubkey;
+  tokenBWantedAmount: u64;
+  bump: u8;
+}
+```
+
+The account has the same discriminator and the same Borsh bytes: an Anchor client decodes a TypeSOL offer unchanged.
+Field names are camelCase in TypeScript and snake_case in the IDL, as Anchor writes them.
+
+### make_offer
+
+Anchor declares the accounts in a struct with constraint attributes, then splits the work into helper functions:
+
+```rust
+#[derive(Accounts)]
+#[instruction(id: u64)]
+pub struct MakeOffer<'info> {
+    #[account(mut)]
+    pub maker: Signer<'info>,
+    #[account(mint::token_program = token_program)]
+    pub token_mint_a: InterfaceAccount<'info, Mint>,
+    #[account(mint::token_program = token_program)]
+    pub token_mint_b: InterfaceAccount<'info, Mint>,
+    #[account(mut, associated_token::mint = token_mint_a, associated_token::authority = maker,
+              associated_token::token_program = token_program)]
+    pub maker_token_account_a: InterfaceAccount<'info, TokenAccount>,
+    #[account(init, payer = maker, space = ANCHOR_DISCRIMINATOR + Offer::INIT_SPACE,
+              seeds = [b"offer", maker.key().as_ref(), id.to_le_bytes().as_ref()], bump)]
+    pub offer: Account<'info, Offer>,
+    #[account(init, payer = maker, associated_token::mint = token_mint_a, associated_token::authority = offer,
+              associated_token::token_program = token_program)]
+    pub vault: InterfaceAccount<'info, TokenAccount>,
+    pub associated_token_program: Program<'info, AssociatedToken>,
+    pub token_program: Interface<'info, TokenInterface>,
+    pub system_program: Program<'info, System>,
+}
+// + send_offered_tokens_to_vault (a TransferChecked CPI through a shared transfer_tokens helper)
+// + save_offer (offer.set_inner(Offer { … bump: context.bumps.offer }))
+```
+
+In TypeSOL the accounts are the function's parameters, in the same order, and each constraint is part of the
+parameter's type:
+
+```ts
+export function makeOffer(
+  maker: Mut<Signer>,
+  tokenMintA: MintOf<Mint, never, never, "tokenProgram">,
+  tokenMintB: MintOf<Mint, never, never, "tokenProgram">,
+  makerTokenAccountA: Ata<Mut<TokenAccount>, "maker", "tokenMintA">,
+  offer: Init<Offer>,
+  vault: Ata<Init<TokenAccount>, "offer", "tokenMintA">,
+  associatedTokenProgram: AssociatedTokenProgram,
+  tokenProgram: TokenInterface,
+  systemProgram: SystemProgram,
+  id: u64,
+  tokenAOfferedAmount: u64,
+  tokenBWantedAmount: u64,
+): void {
+  offer.bump = offer.create(maker, ["offer", maker.key, id]);
+  vault.create(maker);
+  tokenProgram.transferChecked(makerTokenAccountA, tokenMintA, vault, maker, tokenAOfferedAmount);
+  offer.id = id;
+  offer.maker = maker.key;
+  offer.tokenMintA = tokenMintA.key;
+  offer.tokenMintB = tokenMintB.key;
+  offer.tokenBWantedAmount = tokenBWantedAmount;
+}
+```
+
+`MintOf<Mint, never, never, "tokenProgram">` is `mint::token_program = token_program`: the mint must be owned by
+the token program passed (2022 otherwise). `offer.create` finds the canonical bump, creates the PDA with the computed space and returns the bump, which Anchor
+exposes as `context.bumps.offer`. `transferChecked` reads the mint's decimals itself.
+
+### take_offer and refund_offer
+
+The offer is checked declaratively, as in Anchor: the seeds come from the maker account and the offer's own `id`
+field, and the stored bump is used.
+
+```rust
+#[account(mut, close = maker, has_one = maker, has_one = token_mint_a, has_one = token_mint_b,
+          seeds = [b"offer", maker.key().as_ref(), offer.id.to_le_bytes().as_ref()], bump = offer.bump)]
+offer: Account<'info, Offer>,
+```
+
+```ts
+offer: Seeds<CloseTo<HasOne<Mut<Offer>, "maker" | "tokenMintA" | "tokenMintB">, "maker">, ["offer", "@maker", "@offer.id"], "bump">,
+```
+
+The body signs for the vault with the offer's seeds, where Anchor builds a `signer_seeds` array and a
+`CpiContext::new_with_signer` for each call:
+
+```ts
+takerTokenAccountA.createIfNeeded(taker);
+makerTokenAccountB.createIfNeeded(taker);
+tokenProgram.transferChecked(takerTokenAccountB, tokenMintB, makerTokenAccountB, taker, offer.tokenBWantedAmount);
+tokenProgram.transferChecked(vault, tokenMintA, takerTokenAccountA, offer, vault.amount, ["offer", maker.key, offer.id, offer.bump]);
+tokenProgram.closeAccount(vault, maker, offer, ["offer", maker.key, offer.id, offer.bump]);
+```
+
+`CloseTo<…, "maker">` closes the offer after the body returns, as Anchor's `close = maker` does.
+
+## What changed
+
+| Anchor | Port |
+| --- | --- |
+| `Signer`, `SystemAccount` (`#[account(mut)]`) | `Mut<Signer>`, `Mut<SystemAccount>` |
+| `InterfaceAccount<Mint>`, `InterfaceAccount<TokenAccount>` | `Mint`, `TokenAccount` |
+| `mint::token_program = token_program` | `MintOf<Mint, never, never, "tokenProgram">` |
+| `associated_token::mint = m, associated_token::authority = a` | `Ata<TokenAccount, "a", "m">` |
+| `init` / `init_if_needed` on an associated token account | `Ata<Init<…>>` + `vault.create(payer)` / `Ata<InitIfNeeded<…>>` + `createIfNeeded(payer)` |
+| `init, seeds, bump` + `context.bumps.offer` | `Init<Offer>` + `offer.bump = offer.create(maker, seeds)` |
+| `seeds = […], bump = offer.bump` | `Seeds<…, ["offer", "@maker", "@offer.id"], "bump">` |
+| `has_one`, `close` | `HasOne<…>`, `CloseTo<…>` |
+| `transfer_checked(CpiContext::new_with_signer(…), amount, decimals)` | `tokenProgram.transferChecked(from, mint, to, authority, amount, seeds)` |
+| `ErrorCode::CustomError` (unused upstream) | `enum ErrorCode`, the same code 6000 |
+
+Nothing in the program needed a construct TypeSOL lacks, and every account constraint has its TypeSOL form; the port
+is marked PORTED in [the ports table](../test/ports/README.md).
+
+## Same inputs, same results
+
+Two independent checks run the original and the port against each other.
+
+- **The port's own test** ([`test/ports-tokens.test.ts`](../test/ports-tokens.test.ts)) runs the upstream flow with SPL
+  Token mints and again with Token-2022 mints: make, take (creating the taker's and the maker's missing token accounts),
+  make again, a refund attempt by someone other than the maker, and the refund. It checks balances, the decoded offer
+  and that offer and vault are closed.
+- **The four-way comparison** in [typesol/benchmarks](https://github.com/typesol/benchmarks) builds the upstream Anchor,
+  native and Pinocchio versions unmodified and sends all four the same 21 offers (ten taken, ten refunded, one left
+  open). The decoded open offer, every token balance, the vault's authority and which accounts were closed must be
+  identical before any number is reported. They are.
+
+Both implementations refuse the hostile calls the comparison makes:
+
+| Hostile call | Anchor | TypeSOL |
+| --- | --- | --- |
+| refund_offer signed by someone other than the maker | 2006 ConstraintSeeds | 2006 ConstraintSeeds |
+| take_offer naming the taker as the maker | 2015 ConstraintTokenOwner | 2040 ConstraintDuplicateMutableAccount |
+
+TypeSOL checks each account's constraints in Anchor's order, so a refused transaction usually gets the same error
+code (see [which error a transaction gets](errors.md#which-error-a-transaction-gets)). The second call differs on
+purpose: taker and maker are then the same writable account, which TypeSOL refuses for any two writable parameters,
+where Anchor only compares program and token accounts and fails later, on the maker's token account. A client that
+matches on this code needs to accept either.
+
+## Cost
+
+Mean compute units per instruction in LiteSVM (21 make_offer, 10 take_offer and 10 refund_offer calls), and the
+program size, from typesol/benchmarks (TypeSOL at this version; Anchor 1.0.2). Lower is better.
+
+| | TypeSOL | Anchor | Native Rust | Pinocchio |
+| --- | ---: | ---: | ---: | ---: |
+| make_offer | **19,697** | 35,726 | 33,206 | 20,581 |
+| take_offer | **7,053** | 29,235 | 24,995 | 21,606 |
+| refund_offer | **4,271** | 15,326 | 12,477 | 8,137 |
+| Binary | 32.0 KB | 244.5 KB | 120.4 KB | **25.1 KB** |
+
+Most of `make_offer` in every version is the Associated Token Account program creating the vault. The native and
+Pinocchio versions are teaching code with fewer checks (no owner or type check on the offer, `Transfer` instead of
+`TransferChecked`; Pinocchio takes the offer's bump from the client).
+
+The same program, built with an earlier TypeSOL, runs on mainnet next to the other three; the transactions are listed
+with their Solscan links in the [performance report](https://typesol.com/report/) and the
+[README](../README.md#on-mainnet).
+
+## Porting your own program
+
+The steps this port followed, in order:
+
+1. Generate the skeleton from the Anchor IDL: `npx typesol port target/idl/escrow.json --out programs/escrow.ts`. It
+   keeps instruction names, discriminators, account order and error codes.
+2. Turn each `#[account(...)]` into the parameter's type, using the table above and
+   [Accounts and constraints](migrate-from-anchor.md#accounts-and-constraints). Keep the account order: it is the
+   wire format.
+3. Port the bodies. Helpers like `transfer_tokens` usually disappear into one call; `signer_seeds` arrays become the
+   last argument of the CPI.
+4. Run the upstream test flow against the port with `typesol/testing`, including the failure paths, and compare the
+   decoded accounts.
+5. Compare the IDLs, and check the error codes your clients match on (the table above shows how they can differ).

package/docs/errors.md

@@ -5,6 +5,7 @@ Framework errors use Anchor's numbers where Anchor has the same check, so client
 | Code | Meaning |
 | --- | --- |
 | 100 / 101 / 102 | instruction data missing / unknown instruction / malformed arguments (InstructionMissing / FallbackNotFound / DidNotDeserialize) |
+| 2000 | a `Mut<…>` / `Init<…>` account passed read-only (ConstraintMut) |
 | 2001 | HasOne constraint failed (ConstraintHasOne) |
 | 2002 | event authority did not sign (ConstraintSigner) |
 | 2004 | Owner constraint failed (ConstraintOwner) |
@@ -15,6 +16,7 @@ Framework errors use Anchor's numbers where Anchor has the same check, so client
 | 2012 | not the expected address (ConstraintAddress) |
 | 2014 / 2015 | token account mint / owner mismatch (ConstraintTokenMint / ConstraintTokenOwner) |
 | 2016 / 2017 / 2018 | mint authority / freeze authority / decimals mismatch (2018: an existing mint `createIfNeeded` found) |
+| 2021 / 2022 | token account / mint not owned by the token program `TokenOf` / `MintOf` names (ConstraintTokenTokenProgram / ConstraintMintTokenProgram) |
 | 2024–2039 | an existing mint `createIfNeeded` found lacks a Token-2022 extension it was given, or holds other keys in it: group pointer 2024–2026, group member pointer 2027–2029, metadata pointer 2030–2032, close authority 2033–2034, permanent delegate 2035–2036, transfer hook 2037–2039 (the first code of each: the extension is missing; the next: the authority / address differs) (ConstraintMint…Extension…) |
 | 2040 | the same account passed in two writable slots (ConstraintDuplicateMutableAccount) |
 | 3000 | account already exists / initialized (AccountDiscriminatorAlreadySet) |
@@ -22,7 +24,7 @@ Framework errors use Anchor's numbers where Anchor has the same check, so client
 | 3003 | data too small, not an initialized token account / mint, a read past the end, or a `@layout borsh` account whose bytes are not a valid Borsh value (AccountDidNotDeserialize) |
 | 3004 | a `@layout borsh` account too small for the value it would now hold (AccountDidNotSerialize) |
 | 3005 | not enough accounts (AccountNotEnoughKeys) |
-| 3006 | account must be writable (AccountNotMutable) |
+| 3006 | a remaining account or CPI account the program needs writable was passed read-only (AccountNotMutable) |
 | 3007 | wrong owner program (AccountOwnedByWrongProgram) |
 | 3008 / 3009 | wrong program address / not executable (InvalidProgramId / InvalidProgramExecutable) |
 | 3010 | account must sign (AccountNotSigner; also a new keypair account a `create(payer, null, …)` makes) |
@@ -47,3 +49,26 @@ Framework errors use Anchor's numbers where Anchor has the same check, so client
 
 Any of Anchor's own codes can be raised directly: `require(cond, AnchorError.RequireKeysEqViolated)` fails with 2502,
 as `require_keys_eq!` does.
+
+## Which error a transaction gets
+
+A transaction can break several checks; it fails with the first. Within each account's constraints the checks run in
+the order Anchor's generated code runs them, so a transaction gets the same code under both:
+
+1. The account count (3005), then each account in parameter order: its type, signer (3010), `Mut` (2000), owner,
+   discriminator and size of a program account (3007 / 3012 / 3002 / 3003), token account or mint, program address.
+2. Two writable parameters naming one account (2040).
+3. The instruction's arguments (102).
+4. Each account in parameter order, its constraints in Anchor's order: seeds (2006), associated token account (owner
+   2015, then address 2009), `has_one` (2001), owner (2004), executable (2007), address (2012), then `TokenOf` /
+   `MintOf` (2015, 2014, 2021 / 2016, 2017, 2022).
+
+Where TypeSOL's order differs, only a transaction that breaks two of these checks at once sees it:
+
+- Anchor decodes the arguments first, and checks `mut` with the constraints (after seeds and the associated token
+  account). TypeSOL keeps both earlier and later as above, which keeps binaries smaller.
+- Too few accounts fails with 3005 before any account is checked; Anchor fails on the first account it cannot find.
+- Accounts the instruction creates (`Init<…>`, `create(…)`) are created in the body, after every other check, where
+  Anchor creates them before checking the other accounts.
+- TypeSOL refuses any two writable parameters naming one account (2040), where Anchor only compares program and token
+  accounts: a signer passed as two writable parameters fails with 2040 here and later, or not at all, under Anchor.

package/docs/language.md

@@ -38,8 +38,8 @@ The full reference. For a tour, start with the [README](../README.md).
 | Option of structs | `home: Option<Point>` in account data — `=== null`, `p.home.x` after narrowing, `p.home = null` / `{ x, y }` |
 | Strings at runtime | `"hello, " + name`, `` `#${n}` ``, `` `owner ${acct.owner}` `` (a Pubkey or Hash as base58) — built on the 32 KiB heap (5110 when full): a template is joined in one allocation, text known at compile time (literals, string and Pubkey constants) is folded in, and `s += …` grows the newest heap string in place |
 | `switch` | on integers (128-bit ones too), enums and data-enum `.kind`, with JS `break` / fallthrough; case labels are literals, constants or enum members |
-| Hashing & signatures | `sha256(...)`, `keccak256(...)` → `Hash`; `findProgramAddress(seeds, program)` → the canonical PDA of any program (Rust `Pubkey::find_program_address(..).0`, e.g. a Bubblegum asset id); `merkleVerify(leaf, proof: Vec<Hash>, root)` (sorted-pair keccak, OpenZeppelin convention); `verifyEd25519(instructionsSysvar, signer, message)` checks an Ed25519 precompile instruction in the same transaction; `verifySecp256k1(keccak256(...message) | ethMessageHash(message), recoveryId, r, s, ethAddress)` (the hash must be computed in the program; a passed-in hash could be forged) |
-| Oracles | `pythPrice(update: PythPriceUpdate, feedId, maxAgeSeconds)` (fully verified, feed-matched, fresh); raw `update.price / conf / exponent / publishTime`; `switchboardValue(feed: SwitchboardFeed, expectedFeed, maxStaleSlots, decimals)` (the feed must be the expected one: anyone can create feeds) (mainnet program unless `SwitchboardFeed<"devnet">`) |
+| Hashing & signatures | `sha256(...)`, `keccak256(...)` → `Hash`; `findProgramAddress(seeds, program)` → the canonical PDA of any program (Rust `Pubkey::find_program_address(..).0`, e.g. a Bubblegum asset id); `merkleVerify(leaf, proof: Vec<Hash>, root)` (sorted-pair keccak, OpenZeppelin convention; inner nodes and leaves are hashed alike, so hash leaves as OpenZeppelin does, `keccak256(keccak256(data))`, and never take the leaf itself from the arguments: an inner node would pass as a leaf); `verifyEd25519(instructionsSysvar, signer, message)` checks an Ed25519 precompile instruction in the same transaction; `verifySecp256k1(keccak256(...message) | ethMessageHash(message), recoveryId, r, s, ethAddress)` (the hash must be computed in the program; a passed-in hash could be forged) |
+| Oracles | `pythPrice(update: PythPriceUpdate, feedId, maxAgeSeconds, exponent?)` (fully verified, feed-matched, fresh; with `exponent`, a feed at another scale is refused); raw `update.price / conf / exponent / publishTime` are unchecked (any feed, partially verified or stale: check `feedId`, `fullyVerified` and the age yourself, or use `pythPrice`); `switchboardValue(feed: SwitchboardFeed, expectedFeed, maxStaleSlots, decimals, minSamples?)` (the feed must be the expected one: anyone can create feeds; `minSamples`, default 1, the fewest oracle samples accepted) (mainnet program unless `SwitchboardFeed<"devnet">`) |
 | Multiple files | `import { Side, min } from "./math"` — structs, enums, constants and helpers can live in other files; only the entry file's exported functions are instructions; names are program-wide, so imports from TypeSOL files cannot be renamed; error codes number imported files first |
 | Loops | `for (let i = 0n; i < n; i++)`, `while`, `do … while`, `for (const x of list)` over a `Vec` or `FixedArray` (each `x` is what `list.get(i)` gives: a value, or a reference into account data for structs; the length is read again every step, as in JS), `break`, `continue` — bounded by the compute budget. Remaining accounts are iterated by index |
 | Helpers | non-exported functions (and every function of an imported file): take values, structs, Vec arguments, `SignerSeeds` and accounts the instruction already checked (`Signer`, `AccountInfo`/`AccountMeta`, `Mut<T>`, token accounts, programs); return `void`, a scalar, a `string`, a function (see below) or a fixed-size struct (`function at(x: u64, y: u64): Point { return { x, y }; }`: the caller gets its own copy, to bind, store with `acct.home = at(…)` / `arr.set(i, at(…))` or read as `at(…).x`); no recursion. A helper that takes a struct account as `Mut<T>` can grow its Vec (`push(value, payer)`: the account's size at instruction entry is passed along) |
@@ -65,9 +65,9 @@ The full reference. For a tour, start with the [README](../README.md).
 | `Signer` / `Mut<Signer>` | signed (and writable) |
 | `Account<T>` / `Mut<T>` | owned by this program, 8-byte discriminator matches, data large enough (and writable) |
 | `Init<T>` | writable; `create(payer, seeds)` derives the PDA, verifies it, funds rent, writes the discriminator (up to 10 KiB); `create(payer, null)` creates a new keypair account that signs the transaction instead (3010 if it did not; a signer in the IDL); a third argument is Anchor's `space = …` (discriminator included, at least 8 + the struct's size) |
-| `InitIfNeeded<T>` | `const created = acct.createIfNeeded(payer, seeds)` — creates once; afterwards re-derives the PDA and checks owner, discriminator and size (Anchor `init_if_needed`); `acct.pdaBump` after create |
+| `InitIfNeeded<T>` | `const created = acct.createIfNeeded(payer, seeds)` — creates once; afterwards re-derives the PDA and checks owner, discriminator and size (Anchor `init_if_needed`); `acct.pdaBump` after create. An existing account is used as it is: check the fields you rely on |
 | `HasOne<A, "owner">`, `Seeds<A, ["vault", "@owner"], "bump">`, `CloseTo<A, "owner">` | declarative constraints like Anchor's `has_one`, `seeds`/`bump` and `close`: checked before the body (2001 / 2006), close runs when the instruction succeeds; `"@name"` = account key or argument bytes, `"@acct.field"` = a Pubkey, integer or unit enum field of a struct account parameter (also the account's own: `["offer", "@maker", "@offer.id"]`), other strings are literals; recorded as `relations` / `pda` in the IDL. `acct.pdaBump` is the bump (Anchor `ctx.bumps.acct`): the stored field when one is named, else the canonical bump the check found — use it to sign as the PDA |
-| `HasOne<TokenAccount, "mint" \| "owner">`, `HasOne<Mint, "mintAuthority" \| "freezeAuthority">` | token constraints (2014 / 2015 / 2016 / 2017) against the parameter with that name; `TokenOf<TokenAccount, "mintParam", "authorityParam">` / `MintOf<Mint, "authorityParam", "freezeParam">` name the parameters, as Anchor's `token::mint = …` / `mint::authority = …` do (`never` leaves one out) |
+| `HasOne<TokenAccount, "mint" \| "owner">`, `HasOne<Mint, "mintAuthority" \| "freezeAuthority">` | token constraints (2014 / 2015 / 2016 / 2017) against the parameter with that name; `TokenOf<TokenAccount, "mintParam", "authorityParam", "tokenProgramParam">` / `MintOf<Mint, "authorityParam", "freezeParam", "tokenProgramParam">` name the parameters, as Anchor's `token::mint = …` / `mint::authority = …` / `…::token_program = …` do (`never` leaves one out; the token program one: owned by that token program, 2021 / 2022) |
 | `Ata<TokenAccount, "owner", "mint">` | the account is the associated token account of those parameters (2009; ATA `pda` in the IDL) |
 | `Ata<Init<TokenAccount>, "owner", "mint">`, `Ata<InitIfNeeded<TokenAccount>, "owner", "mint">` | Anchor `init` / `init_if_needed` with `associated_token::…`: `acct.create(payer)` creates the ATA (fails if it exists); `const created = acct.createIfNeeded(payer)` creates it only when missing, otherwise checks it is that ATA (2009). Then it is a `TokenAccount` of that mint and owner (2014 / 2015). Needs `AssociatedTokenProgram`, `SystemProgram` and a token program parameter; call it at the top level before using the account |
 | `Address<A, "4Nd1…">` | exact address (2012; `address` in the IDL) |
@@ -77,8 +77,8 @@ The full reference. For a tour, start with the [README](../README.md).
 | `ProgramData` | this program's ProgramData (address derived from the program id, upgradeable-loader owner and state checked); `upgradeAuthority`, `deploySlot` — gate admin setup on `programData.upgradeAuthority === admin.key` |
 | `EventAuthority`, `SelfProgram` | Anchor's `["__event_authority"]` PDA, and this program's own address, for `emitCpi` |
 | `Zeroed<T>` | large accounts (up to 10 MiB) the client allocated with System `CreateAccount`: owned by this program, big enough, rent-exempt, discriminator still zero — then initialized; like Anchor's zero-copy `zero` |
-| `Init<Mint>`, `InitIfNeeded<Mint>` | Anchor `init` / `init_if_needed` with `mint::decimals` / `mint::authority` / `mint::freeze_authority`: `const bump = mint.create(payer, ["mint", payer.key], 6n, authority, freezeAuthority \| null)` creates the mint at that PDA of this program, or with `null` seeds as a new keypair account that signs (3010 if it did not), under the instruction's token program (its only token program parameter, or one passed as the last argument of `create` / `createIfNeeded`; plus `SystemProgram`). Token-2022 extensions (Anchor's `extensions::…`) go after the freeze authority: `mint.create(payer, null, 6n, authority, null, { metadataPointer: { authority, metadataAddress: mint.key }, transferHook: { authority, programId }, closeAuthority, permanentDelegate, nonTransferable: true, defaultAccountState: true, interestBearing: { rateAuthority, rate }, transferFee: { configAuthority, withdrawAuthority, basisPoints, maximumFee }, groupPointer, groupMemberPointer })` sizes the mint for them and initializes each before InitializeMint2. With `createIfNeeded` an existing mint must carry groupPointer / groupMemberPointer / metadataPointer / closeAuthority / permanentDelegate / transferHook with those keys (Anchor's 2024–2039). `createIfNeeded(…)` returns whether it created it; an existing one must be that PDA and have those decimals and authorities (2018 / 2016 / 2017) |
-| `Init<TokenAccount>`, `InitIfNeeded<TokenAccount>` (no `Ata<…>`) | Anchor `init` / `init_if_needed` with `token::mint` / `token::authority`: `vault.create(payer, ["vault", mint.key], mint, authority)` (the authority may be `vault.key` itself) creates a token account at that PDA (or a keypair account with `null`), sized for the mint's extensions under Token-2022. `createIfNeeded` checks an existing one has that mint and owner (2014 / 2015) |
+| `Init<Mint>`, `InitIfNeeded<Mint>` | Anchor `init` / `init_if_needed` with `mint::decimals` / `mint::authority` / `mint::freeze_authority`: `const bump = mint.create(payer, ["mint", payer.key], 6n, authority, freezeAuthority \| null)` creates the mint at that PDA of this program, or with `null` seeds as a new keypair account that signs (3010 if it did not), under the instruction's token program (its only token program parameter, or one passed as the last argument of `create` / `createIfNeeded`; plus `SystemProgram`). Token-2022 extensions (Anchor's `extensions::…`) go after the freeze authority: `mint.create(payer, null, 6n, authority, null, { metadataPointer: { authority, metadataAddress: mint.key }, transferHook: { authority, programId }, closeAuthority, permanentDelegate, nonTransferable: true, defaultAccountState: true, interestBearing: { rateAuthority, rate }, transferFee: { configAuthority, withdrawAuthority, basisPoints, maximumFee }, groupPointer, groupMemberPointer })` sizes the mint for them and initializes each before InitializeMint2. With `createIfNeeded` an existing mint must carry groupPointer / groupMemberPointer / metadataPointer / closeAuthority / permanentDelegate / transferHook with those keys (Anchor's 2024–2039); extensions not listed are not looked at, so an existing mint may carry others (a permanent delegate, say). `createIfNeeded(…)` returns whether it created it; an existing one must be that PDA and have those decimals and authorities (2018 / 2016 / 2017) |
+| `Init<TokenAccount>`, `InitIfNeeded<TokenAccount>` (no `Ata<…>`) | Anchor `init` / `init_if_needed` with `token::mint` / `token::authority`: `vault.create(payer, ["vault", mint.key], mint, authority)` (the authority may be `vault.key` itself) creates a token account at that PDA (or a keypair account with `null`), sized for the mint's extensions under Token-2022. `createIfNeeded` checks an existing one has that mint and owner (2014 / 2015), not its delegate or close authority (as Anchor) |
 | `TokenAccount` / `Mut<TokenAccount>` | owned by SPL Token or Token-2022 (extensions allowed, multisig accounts refused), initialized; `mint`, `owner`, `amount`, `delegate`, `delegatedAmount`, `isFrozen`, `isNative`, `closeAuthority`, `tokenProgram` |
 | `Mint` / `Mut<Mint>` | owned by SPL Token or Token-2022, initialized; `decimals`, `supply`, `mintAuthority`, `freezeAuthority`, `tokenProgram` |
 | `SystemProgram`, `TokenProgram`, `Token2022Program` | exact program address |
@@ -94,7 +94,9 @@ The full reference. For a tour, start with the [README](../README.md).
 Every account exposes `key`, `lamports`, `dataLen`, `isSigner`, `isWritable`. At most 32 accounts per instruction (more is refused, 5113).
 
 Two writable parameters can never be the same account: aliasing is refused with error 2040 (also when a remaining
-account written through `.lamports` or `loadAccountMut` is another account of the instruction).
+account written through `.lamports` or `loadAccountMut` is another account of the instruction). A remaining account
+can be loaded with `loadAccountMut` once per instruction: loading the same one again (`rest.get(i)` and `rest.get(j)`
+with `i == j`) is refused with 2040 too, since the two views would alias.
 
 ## Built-ins
 
@@ -106,7 +108,9 @@ account written through `.lamports` or `loadAccountMut` is another account of th
   `freezeAccount` / `thawAccount(account, mint, freezeAuthority)`, `syncNative(account)`, `initializeMint2(mint, decimals, mintAuthority, freezeAuthority | null)`,
   `initializeAccount3(account, mint, owner)`, and on Token-2022 `initializeMetadata(mint, updateAuthority, mintAuthority, name, symbol, uri)` (metadata extension) and the extension initializers to call between `createAccount` and `initializeMint2` / `initializeAccount3`: `initializeTransferFeeConfig(mint, configAuthority | null, withdrawAuthority | null, basisPoints, maximumFee)`, `initializeMintCloseAuthority(mint, authority | null)`, `initializeNonTransferableMint(mint)`, `initializePermanentDelegate(mint, delegate)`, `initializeDefaultAccountState(mint, frozen)`, `initializeMetadataPointer` / `initializeGroupPointer` / `initializeGroupMemberPointer` / `initializeTransferHook(mint, authority | null, address | null)`, `initializeInterestBearingMint(mint, rateAuthority | null, rate)`, `initializeImmutableOwner(account)`; the extension instructions `updateDefaultAccountState(mint, freezeAuthority, frozen)`, `updateTransferHook(mint, authority, programId | null)`, `enableRequiredMemoTransfers` / `disableRequiredMemoTransfers(account, owner)`, `updateInterestRate(mint, rateAuthority, rate)`, `transferCheckedWithFee(from, mint, to, authority, amount, fee)`, `harvestWithheldTokensToMint(mint, remainingAccounts())`, `withdrawWithheldTokensFromMint(mint, destination, authority)`, `setTransferFee(mint, authority, basisPoints, maximumFee)`; and the Token Metadata interface `updateMetadataField(mint, updateAuthority, field, value)` ("name" / "symbol" / "uri" or any other key), `removeMetadataKey(mint, updateAuthority, key, idempotent)`, `updateMetadataAuthority(mint, updateAuthority, next | null)`, `emitMetadata(mint)`. Each takes optional signerSeeds
 - `account.lamports` read/write on `Mut` accounts, `close(account, destination)` for program accounts
-- `requirePda(account, seeds, bump)`
+- `requirePda(account, seeds, bump)`: any bump that gives a valid PDA passes, as with Anchor's `bump = expr`. Use a bump
+  stored when the account was created (or `Seeds<…>`); one taken from the instruction's arguments lets the caller pick
+  among up to 256 addresses for the same seeds
 
 ## Implementing another program's interface (transfer hooks)
 

package/docs/migrate-from-anchor.md

@@ -2,7 +2,8 @@
 
 TypeSOL programs speak Anchor's wire format: the same instruction and account discriminators, Borsh arguments, an
 Anchor-format IDL, the same error numbering and event logs. A ported program can keep its clients. This page maps
-Anchor's constructs to TypeSOL's and shows the porting workflow.
+Anchor's constructs to TypeSOL's and shows the porting workflow. For one complete program ported this way, with the
+original side by side, the checks run against it and its cost, see [Case study: porting Anchor's escrow](case-study-escrow.md).
 
 ## Start from the IDL
 
@@ -50,6 +51,7 @@ and error codes. Its notes (on stderr) list what an existing Anchor client would
 | `Program<'info, Token>` / `Token2022` / `Interface<'info, TokenInterface>` | `TokenProgram` / `Token2022Program` / `TokenInterface` |
 | `Account<'info, TokenAccount>` / `Account<'info, Mint>` (`InterfaceAccount`) | `TokenAccount` / `Mint` (`Mut<…>` when written) |
 | `token::mint = m, token::authority = a` | `TokenOf<TokenAccount, "m", "a">` (2014 / 2015), or `HasOne<TokenAccount, "mint" \| "owner">` when the parameters have those names; `mint::authority = a, mint::freeze_authority = f` on an existing mint: `MintOf<Mint, "a", "f">` (2016 / 2017) |
+| `mint::token_program = tp` / `token::token_program = tp` | `MintOf<Mint, never, never, "tp">` / `TokenOf<TokenAccount, never, never, "tp">` (2022 / 2021) |
 | `extensions::metadata_pointer::authority = a, …` (with `mint::…`) | `mint.create(p, …, { metadataPointer: { authority: a.key, metadataAddress: mint.key }, … })`: transferHook, closeAuthority, permanentDelegate, nonTransferable, groupPointer, groupMemberPointer and more |
 | `#[account(init, payer = p, seeds = […], bump, mint::decimals = 6, mint::authority = a, mint::freeze_authority = f)]` | `Init<Mint>`, then `const bump = mint.create(p, […], 6n, a.key, f.key)` (`null` seeds: a keypair mint; `InitIfNeeded<Mint>` + `createIfNeeded`) |
 | `#[account(init, payer = p, seeds = […], bump, token::mint = m, token::authority = a)]` | `Init<TokenAccount>`, then `vault.create(p, […], m, a.key)` (`InitIfNeeded<TokenAccount>` + `createIfNeeded`) |

package/lib/typesol.d.ts

@@ -162,7 +162,8 @@ export declare function remainingAccounts(): RemainingAccounts;
 
 /**
  * Read a struct of this program from a remaining account: owner, discriminator and size are checked.
- * `loadAccountMut` also requires it to be writable and not aliased by another writable account.
+ * `loadAccountMut` also requires it to be writable, not aliased by another writable account, and not already loaded
+ * with `loadAccountMut` in this instruction (2040).
  */
 export declare function loadAccount<T>(account: RemainingAccount): Readonly<T>;
 export declare function loadAccountMut<T>(account: RemainingAccount): T;
@@ -180,7 +181,8 @@ export declare function keccak256(...parts: (string | Pubkey | Hash | bigint | b
 
 /**
  * Verify a Merkle proof (keccak256, sorted pairs: the OpenZeppelin convention most airdrop tools use).
- * `proof` must be a `Vec<Hash>` instruction argument.
+ * `proof` must be a `Vec<Hash>` instruction argument. Leaves and inner nodes hash alike: build the leaf in the program
+ * as OpenZeppelin does, `keccak256(keccak256(data))`, never take it from the arguments (an inner node would pass).
  */
 export declare function merkleVerify(leaf: Hash, proof: Vec<Hash>, root: Hash): boolean;
 
@@ -211,7 +213,8 @@ export declare function ethMessageHash(message: string): Hash;
 
 /**
  * A Pyth `PriceUpdateV2` account (Pyth Solana Receiver, rec5EKMG…). Owner and discriminator are checked.
- * The fields are the raw update; use pythPrice() for a verified, fresh, feed-matched price.
+ * The fields are the raw update and are NOT checked: it may be only partially verified, for another feed, or stale.
+ * Use pythPrice() for a verified, fresh, feed-matched price (with `exponent` to pin the scale).
  */
 export interface PythPriceUpdate extends AccountMeta {
   readonly __pyth: void;
@@ -223,8 +226,12 @@ export interface PythPriceUpdate extends AccountMeta {
   readonly publishTime: i64;
   readonly fullyVerified: boolean;
 }
-/** Like Pyth's get_price_no_older_than: fully verified, `feedId` matches, published within `maxAgeSeconds`. */
-export declare function pythPrice(update: PythPriceUpdate, feedId: Hash, maxAgeSeconds: u64): i64;
+/**
+ * Like Pyth's get_price_no_older_than: fully verified, `feedId` matches, published within `maxAgeSeconds` (5111
+ * otherwise). The price is in units of 10^exponent: pass the `exponent` your arithmetic assumes and a feed whose
+ * exponent differs is refused, instead of read at the wrong scale.
+ */
+export declare function pythPrice(update: PythPriceUpdate, feedId: Hash, maxAgeSeconds: u64, exponent?: i32): i64;
 
 /**
  * A Switchboard On-Demand pull feed (PullFeedAccountData). Mainnet program unless `SwitchboardFeed<"devnet">`
@@ -237,7 +244,14 @@ export interface SwitchboardFeed<Cluster extends "mainnet" | "devnet" = "mainnet
  * The feed's current result scaled to `decimals` (from 18), if `feed` is `expectedFeed` (anyone can create feeds),
  * it has samples and it is at most `maxStaleSlots` old.
  */
-export declare function switchboardValue(feed: SwitchboardFeed<"mainnet" | "devnet">, expectedFeed: Pubkey, maxStaleSlots: u64, decimals: u8): i64;
+export declare function switchboardValue(
+  feed: SwitchboardFeed<"mainnet" | "devnet">,
+  expectedFeed: Pubkey,
+  maxStaleSlots: u64,
+  decimals: u8,
+  /** The fewest oracle samples the result may rest on (default 1). */
+  minSamples?: u8,
+): i64;
 
 /** The Associated Token Account program (ATokenGP…). Its address is checked. */
 export interface AssociatedTokenProgram extends AccountMeta {
@@ -570,13 +584,18 @@ export type InitIfNeeded<T> = T extends TokenAccount
  */
 export type HasOne<A, Field extends string> = A & { readonly __hasOne?: Field };
 /**
- * Anchor's `token::mint = mintParam, token::authority = authorityParam` on an existing token account, naming the
- * parameters (2014 / 2015); `never` leaves one out.
+ * Anchor's `token::mint = mintParam, token::authority = authorityParam, token::token_program = tokenProgramParam` on an
+ * existing token account, naming the parameters (2014 / 2015 / 2021: owned by that token program); `never` leaves one out.
  */
-export type TokenOf<A, MintParam extends string, AuthorityParam extends string = never> = A & { readonly __tokenOf?: [MintParam, AuthorityParam] };
-/** Anchor's `mint::authority = a, mint::freeze_authority = f` on an existing mint, naming the parameters (2016 / 2017). */
-export type MintOf<A, AuthorityParam extends string, FreezeAuthorityParam extends string = never> = A & {
-  readonly __mintOf?: [AuthorityParam, FreezeAuthorityParam];
+export type TokenOf<A, MintParam extends string, AuthorityParam extends string = never, TokenProgramParam extends string = never> = A & {
+  readonly __tokenOf?: [MintParam, AuthorityParam, TokenProgramParam];
+};
+/**
+ * Anchor's `mint::authority = a, mint::freeze_authority = f, mint::token_program = tp` on an existing mint, naming the
+ * parameters (2016 / 2017 / 2022: owned by that token program); `never` leaves one out.
+ */
+export type MintOf<A, AuthorityParam extends string, FreezeAuthorityParam extends string = never, TokenProgramParam extends string = never> = A & {
+  readonly __mintOf?: [AuthorityParam, FreezeAuthorityParam, TokenProgramParam];
 };
 export type Seeds<A, Names extends readonly string[], Bump extends string = never, ProgramId extends string = never> = A & {
   readonly __seeds?: [Names, Bump, ProgramId];
@@ -1642,7 +1661,10 @@ export declare function emit<T>(event: T): void;
  */
 export declare function returnData<T extends bigint | boolean | Pubkey | Hash>(program: AccountMeta): T;
 
-/** Verify `account.key` is the PDA for `seeds` + `bump` under this program. */
+/**
+ * Verify `account.key` is the PDA for `seeds` + `bump` under this program. Any bump that gives a PDA passes (Anchor's
+ * `bump = expr`): use a stored bump, not one from the arguments, or the caller picks among up to 256 addresses.
+ */
 export declare function requirePda(account: AccountMeta, seeds: Seed[], bump: u8): void;
 
 /** Close a program-owned account: move all lamports to `destination` and wipe it. */

package/package.json

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

package/runtime/typesol_rt.h

@@ -18,6 +18,7 @@
 #define TS_ERR_INSTRUCTION_NOT_FOUND 101   /* InstructionFallbackNotFound */
 #define TS_ERR_INSTRUCTION_DATA 102        /* InstructionDidNotDeserialize */
 #define TS_ERR_NOT_WRITABLE 3006           /* AccountNotMutable */
+#define TS_ERR_CONSTRAINT_MUT 2000         /* ConstraintMut */
 #define TS_ERR_CONSTRAINT 2001             /* ConstraintHasOne */
 #define TS_ERR_NOT_RENT_EXEMPT 2005        /* ConstraintRentExempt */
 #define TS_ERR_CONSTRAINT_SIGNER 2002      /* ConstraintSigner */
@@ -31,6 +32,8 @@
 #define TS_ERR_MINT_AUTHORITY 2016         /* ConstraintMintMintAuthority */
 #define TS_ERR_FREEZE_AUTHORITY 2017       /* ConstraintMintFreezeAuthority */
 #define TS_ERR_MINT_DECIMALS 2018          /* ConstraintMintDecimals */
+#define TS_ERR_TOKEN_TOKEN_PROGRAM 2021    /* ConstraintTokenTokenProgram */
+#define TS_ERR_MINT_TOKEN_PROGRAM 2022     /* ConstraintMintTokenProgram */
 #define TS_ERR_DUPLICATE_MUT 2040          /* ConstraintDuplicateMutableAccount */
 #define TS_ERR_ALREADY_INITIALIZED 3000    /* AccountDiscriminatorAlreadySet */
 #define TS_ERR_DISCRIMINATOR 3002          /* AccountDiscriminatorMismatch */
@@ -275,6 +278,7 @@ typedef struct {
   const SolPubkey *program_id;
   TsAccount *ka[TS_MAX_ACCOUNTS];             /* ka_num entries */
   SolAccountInfo infos[TS_MAX_ACCOUNTS];      /* scratch for CPI account lists (ts_invoke) */
+  uint64_t loaded_mut;                        /* bit i: ka[i] loaded with loadAccountMut (zeroed by the entrypoint of a program that uses it) */
 } TsParams;
 
 /*
@@ -410,6 +414,12 @@ static inline uint64_t ts_check_writable(const TsAccount *a) {
   if (!a->is_writable) TS_FAIL(TS_ERR_NOT_WRITABLE, "TypeSOL: account must be writable");
   return SUCCESS;
 }
+/* A Mut<…> parameter passed read-only: Anchor's `#[account(mut)]` (ConstraintMut). ts_check_writable is for accounts
+   the program makes writable at runtime (remaining accounts, CPI metas). */
+static inline uint64_t ts_check_mut(const TsAccount *a) {
+  if (!a->is_writable) TS_FAIL(TS_ERR_CONSTRAINT_MUT, "TypeSOL: account must be writable (mut)");
+  return SUCCESS;
+}
 
 static inline uint64_t ts_check_program_account(const TsAccount *a, const SolPubkey *program_id,
                                                 const uint8_t disc[8], uint64_t size) {
@@ -428,7 +438,7 @@ static inline uint64_t ts_check_vec_len(const TsAccount *a, uint64_t fixed, uint
   return SUCCESS;
 }
 
-/* No other account in the instruction may be the same account (for loadAccountMut). */
+/* No other account in the instruction may be the same account (remaining accounts written in place). */
 static inline uint64_t ts_check_unaliased(const TsParams *params, const TsAccount *a) {
   /* The loader passes each account once and marks repeats as duplicates, which share its record. */
   uint64_t seen = 0;
@@ -437,6 +447,18 @@ static inline uint64_t ts_check_unaliased(const TsParams *params, const TsAccoun
   return SUCCESS;
 }
 
+/* loadAccountMut: unaliased, and not already loaded mutably in this instruction. Two loads of the same slot would be
+   two writable views of one account, as two slots naming it would (read both, write both: the classic drain). */
+static inline uint64_t ts_claim_mut(TsParams *params, const TsAccount *a) {
+  uint64_t seen = 0, at = 0;
+  for (uint64_t i = 0; i < params->ka_num; i++)
+    if (params->ka[i] == a) seen++, at = i;
+  if (seen > 1) TS_FAIL(TS_ERR_DUPLICATE_MUT, "TypeSOL: account passed more than once");
+  if (params->loaded_mut >> at & 1) TS_FAIL(TS_ERR_DUPLICATE_MUT, "TypeSOL: account already loaded with loadAccountMut");
+  params->loaded_mut |= (uint64_t)1 << at;
+  return SUCCESS;
+}
+
 static inline uint64_t ts_check_address(const TsAccount *a, const SolPubkey *expected) {
   if (!ts_key_eq(&a->key, expected)) TS_FAIL(TS_ERR_WRONG_PROGRAM, "TypeSOL: unexpected program address");
   return SUCCESS;
@@ -1466,7 +1488,8 @@ static inline int64_t ts_le_i64(const uint8_t *p) {
 }
 
 /* Like get_price_no_older_than: fully verified, matching feed id, publish_time + max_age >= now. */
-static inline uint64_t ts_pyth_price(const TsAccount *a, const SolPubkey *feed, uint64_t max_age, int64_t *out) {
+/* expo: the exponent the caller scales by; checked when check_expo (a feed's exponent can change). */
+static inline uint64_t ts_pyth_price(const TsAccount *a, const SolPubkey *feed, uint64_t max_age, bool check_expo, int32_t expo, int64_t *out) {
   uint64_t m;
   bool full;
   TS_TRY(ts_pyth_message(a, &m, &full));
@@ -1478,6 +1501,11 @@ static inline uint64_t ts_pyth_price(const TsAccount *a, const SolPubkey *feed,
   int64_t deadline;
   if (__builtin_add_overflow(published, (int64_t)(max_age > INT64_MAX ? INT64_MAX : max_age), &deadline)) deadline = INT64_MAX;
   if (deadline < now) TS_FAIL(TS_ERR_ORACLE, "TypeSOL: Pyth price is too old");
+  if (check_expo) {
+    int32_t e;
+    ts_memcpy(&e, a->data + m + 48, 4);
+    if (e != expo) TS_FAIL(TS_ERR_ORACLE, "TypeSOL: Pyth exponent is not the expected one");
+  }
   *out = ts_le_i64(a->data + m + 32);
   return SUCCESS;
 }
@@ -1503,9 +1531,10 @@ static inline uint64_t ts_check_switchboard(const TsAccount *a, bool devnet) {
  * The feed's current result (an 18-decimal fixed-point i128) scaled to `decimals`, if it has samples
  * and was produced within `max_stale_slots` slots of now.
  */
-static inline uint64_t ts_switchboard_value(const TsAccount *a, uint64_t max_stale_slots, uint8_t decimals, int64_t *out) {
+static inline uint64_t ts_switchboard_value(const TsAccount *a, uint64_t max_stale_slots, uint8_t decimals, uint8_t min_samples, int64_t *out) {
   if (decimals > 18) TS_FAIL(TS_ERR_ORACLE, "TypeSOL: at most 18 decimals");
-  if (a->data[TS_SB_RESULT_SAMPLES] == 0) TS_FAIL(TS_ERR_ORACLE, "TypeSOL: Switchboard feed has no samples");
+  if (a->data[TS_SB_RESULT_SAMPLES] == 0 || a->data[TS_SB_RESULT_SAMPLES] < min_samples)
+    TS_FAIL(TS_ERR_ORACLE, "TypeSOL: Switchboard feed has too few samples");
   uint64_t clock[5] = {0};
   if (sol_get_clock_sysvar(clock) != SUCCESS) TS_FAIL(TS_ERR_SYSVAR, "TypeSOL: clock sysvar unavailable");
   uint64_t slot = (uint64_t)ts_le_i64(a->data + TS_SB_RESULT_SLOT);