@typesol/cli 0.26.0 → 0.28.0

package/dist/compiler/emit/expressions.js

@@ -265,6 +265,14 @@ export class ExpressionEmitter extends StorageEmitter {
         if (field === "length") {
             if (this.isRemaining(node.expression))
                 return { c: `((uint64_t)(params->ka_num - ${this.ix.accounts.length}))`, type: U64 };
+            const sysvar = this.instructionsParam(node.expression);
+            if (sysvar) {
+                this.assertUsable(sysvar, node.expression);
+                const t = this.tmp("ixn");
+                this.line(`uint64_t ${t};`);
+                this.line(`TS_TRY(ts_ix_count(a_${sysvar.name}, &${t}));`);
+                return { c: t, type: U64 };
+            }
             // The number of elements a map / filter chain gives: counted, nothing stored.
             if (this.isPipeline(node.expression)) {
                 const n = this.tmp("count");
@@ -284,6 +292,16 @@ export class ExpressionEmitter extends StorageEmitter {
             }
             this.fail(node, "use byteLength(s) for strings; .length is available on arrays, Vecs and remainingAccounts()");
         }
+        if (this.isTxIx(node.expression)) {
+            const ix = this.expr(node.expression);
+            if (field === "programId")
+                return { c: `(${ix.c}.program_id)`, type: PUBKEY };
+            if (field === "accountsLength")
+                return { c: `((uint64_t)${ix.c}.num_accounts)`, type: U64 };
+            if (field === "dataLength")
+                return { c: `((uint64_t)${ix.c}.data_len)`, type: U64 };
+            this.fail(node.name, `a TransactionInstruction has programId, accountsLength and dataLength, not ${field}`);
+        }
         const h = this.handle(node.expression);
         if (h) {
             switch (field) {

package/dist/compiler/emit/function.js

@@ -40,8 +40,14 @@ export class FunctionEmitter extends StatementEmitter {
                 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).
+            // Zeroed<T> (Anchor's `zero`): its discriminator, owner and size come before `mut`, as under Anchor.
+            if (k.kind === "zeroed")
+                head.push(`  TS_TRY(ts_check_zeroed(${v}, params->program_id, ${k.struct.layout === "borsh" ? borshMinSize(k.struct, this.model) : `sizeof(TSS_${k.struct.name})`}));`);
             if (isWritable(k))
                 head.push(`  TS_TRY(ts_check_mut(${v}));`);
+            // Signed<…>: Anchor's `signer` constraint (2002), right after `mut`.
+            if (a.constraints.signed)
+                head.push(`  if (!${v}->is_signer) TS_FAIL(TS_ERR_CONSTRAINT_SIGNER, "TypeSOL: ${a.name} must sign");`);
             // 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)}));`);
@@ -90,11 +96,14 @@ export class FunctionEmitter extends StatementEmitter {
                 }
                 head.push(`  TS_TRY(ts_check_executable(${v}));`);
             }
+            // Migrate<From, To>: an existing From account (owner, discriminator, size), kept to be rewritten as To.
+            if (k.kind === "migrate")
+                head.push(`  TS_TRY(ts_check_program_account(${v}, params->program_id, TS_DISC_${k.from.name}, sizeof(TSS_${k.from.name})));`, `  const TSS_${k.from.name} *df_${a.name} = (const TSS_${k.from.name} *)(${v}->data + 8);`, `  uint64_t entry_${a.name} = ${v}->data_len;`);
             if (k.kind === "zeroed")
-                head.push(`  TS_TRY(ts_init_zeroed(${v}, params->program_id, TS_DISC_${k.struct.name}, sizeof(TSS_${k.struct.name})));`);
+                head.push(`  TS_TRY(ts_init_zeroed(${v}, TS_DISC_${k.struct.name}));`);
             if (k.kind === "initIfNeeded" && k.struct.vec)
                 this.reporter.fail(a.node, "InitIfNeeded accounts cannot end in a Vec yet");
-            if ((k.kind === "account" || k.kind === "init" || k.kind === "initIfNeeded") && k.struct.layout === "borsh") {
+            if ((k.kind === "account" || k.kind === "init" || k.kind === "initIfNeeded" || k.kind === "zeroed") && k.struct.layout === "borsh") {
                 // Worked on as its fixed-layout struct on the heap, packed back when the instruction returns. The heap is zero at
                 // entry and these are its first allocations (before the body uses it), so a string's padding and a list's
                 // unused slots start as zero: ts_unpack_* only writes what the Borsh bytes hold.
@@ -152,9 +161,30 @@ export class FunctionEmitter extends StatementEmitter {
         // The loader passes each account once and marks repeats as duplicates, which share its record (ts_deserialize),
         // so two parameters name the same account exactly when their pointers are equal.
         const writable = ix.accounts.filter((a) => isWritable(a.kind));
+        // Dup<…> (Anchor's `dup`) lifts the check for a pair when both accounts are read and written in place: not created
+        // here, not closed or a close destination, not a @layout borsh heap copy (a lost update when packed back).
+        const closing = new Set(ix.accounts.flatMap((a) => (a.constraints.closeTo ? [a.name, a.constraints.closeTo] : [])));
+        const inPlace = (a) => {
+            const k = a.kind;
+            if (closing.has(a.name))
+                return false;
+            if (k.kind === "account")
+                return k.struct.layout !== "borsh";
+            if (k.kind === "token" || k.kind === "mint")
+                return !k.init;
+            return k.kind === "signer" || k.kind === "info";
+        };
+        for (const a of writable)
+            if (a.constraints.dup && !inPlace(a))
+                this.reporter.fail(a.node, "Dup<…> is for accounts read and written in place: not created, closed, a close destination or @layout borsh");
+        for (const a of ix.accounts)
+            if (a.constraints.dup && !isWritable(a.kind))
+                this.reporter.fail(a.node, "Dup<…> lets a writable account alias another; this one is not writable");
         const pairs = [];
         for (let i = 0; i < writable.length; i++)
             for (let j = i + 1; j < writable.length; j++) {
+                if ((writable[i].constraints.dup || writable[j].constraints.dup) && inPlace(writable[i]) && inPlace(writable[j]))
+                    continue;
                 const present = [writable[i], writable[j]]
                     .filter((a) => a.optional)
                     .map((a) => `a_${a.name} && `)
@@ -331,6 +361,10 @@ export class FunctionEmitter extends StatementEmitter {
         for (const name of this.pendingInit) {
             const k = this.accounts.get(name).kind;
             const a = this.accounts.get(name);
+            if (k.kind === "migrate") {
+                this.reporter.error(a.node, `Migrate account "${name}" is never migrated; call ${name}.migrate(payer, value) (Anchor fails such an instruction with AccountNotMigrated)`);
+                continue;
+            }
             const how = k.kind === "token" && a.constraints.ata
                 ? `${name}.${k.init === "create" ? "create" : "createIfNeeded"}(payer)`
                 : k.kind === "token"
@@ -351,7 +385,7 @@ export class FunctionEmitter extends StatementEmitter {
             return [];
         // @layout borsh accounts go back to their Borsh bytes (unless closed, or never created).
         const packs = this.ix.accounts
-            .filter((a) => (a.kind.kind === "account" ? a.kind.mut : a.kind.kind === "init" || a.kind.kind === "initIfNeeded"))
+            .filter((a) => (a.kind.kind === "account" ? a.kind.mut : a.kind.kind === "init" || a.kind.kind === "initIfNeeded" || a.kind.kind === "zeroed"))
             .filter((a) => a.kind.struct.layout === "borsh")
             .map((a) => {
             const v = `a_${a.name}`;
@@ -560,9 +594,11 @@ export class FunctionEmitter extends StatementEmitter {
         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};`);
+            // The account's own bump field, or "@acct.field": one stored in another struct account.
+            const bump = c.seeds.bump.startsWith("@") ? `d_${c.seeds.bump.slice(1).replace(".", "->")}` : `d_${a.name}->${c.seeds.bump}`;
+            out.push(`  ${seeds}[${parts.length}] = (SolSignerSeed){&${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}`);
+            this.bumps.set(a.name, bump);
         }
         else {
             bumpDecls.push(`  uint8_t sb_${a.name}; (void)sb_${a.name};`);

package/dist/compiler/emit/shared.js

@@ -61,6 +61,8 @@ export function valueC(t) {
             return "TS_VecArg";
         case "account":
             return "TsAccount *";
+        case "txIx":
+            return "TsIx";
         case "structRef":
             return `TSS_${t.struct} *`;
         case "enumRef":

package/dist/compiler/emit/storage.js

@@ -277,6 +277,24 @@ export class StorageEmitter extends EmitterBase {
         }
         if (ts.isPropertyAccessExpression(node)) {
             const field = node.name.text;
+            // Migrate<From, To>: acct.from (the old data, read-only, until migrate()) and acct.to (after it).
+            if (ts.isIdentifier(node.expression)) {
+                const m = this.accounts.get(node.expression.text);
+                if (m?.kind.kind === "migrate") {
+                    const migrated = this.created.has(m.name);
+                    if (field === "from") {
+                        if (migrated)
+                            this.fail(node, `${m.name}.from is gone after ${m.name}.migrate(…): read what you need from it before`);
+                        return { lv: `(*df_${m.name})`, type: { kind: "struct", name: m.kind.from.name }, writable: false, account: m, path: ["from"] };
+                    }
+                    if (field === "to") {
+                        if (!migrated)
+                            this.fail(node, `${m.name}.to exists after ${m.name}.migrate(payer, value)`);
+                        return { lv: `(*dt_${m.name})`, type: { kind: "struct", name: m.kind.to.name }, writable: true, account: m, path: ["to"] };
+                    }
+                    this.fail(node.name, `a Migrate account has .from (before migrate), .to (after), key, lamports and migrate(payer, value)`);
+                }
+            }
             // acct.field on a struct account
             if (ts.isIdentifier(node.expression)) {
                 const a = this.accounts.get(node.expression.text);
@@ -667,9 +685,30 @@ export class StorageEmitter extends EmitterBase {
             this.line(`}`);
             return;
         }
+        // `list = owners`: a Vec argument, or a Vec / FixedVec of the same elements, copied whole into a FixedVec (Anchor's
+        // `multisig.owners = owners`); more elements than it holds fail with 5104, as push does.
+        if (target.type.kind === "vec" && target.type.cap !== undefined && target.type.elem.kind !== "string" && target.type.elem.kind !== "fstring") {
+            const t = target.type;
+            const l = ts.isIdentifier(valueNode) ? this.lookup(valueNode.text) : undefined;
+            const r = l?.type.kind === "vecArg" ? undefined : this.reporter.guard(() => this.ref(valueNode));
+            const from = l?.type.kind === "vecArg" && sameType(l.type.elem, t.elem)
+                ? { items: `${l.c}.ptr`, count: `((uint64_t)${l.c}.len)` }
+                : r?.vec && r.type.kind === "vec" && sameType(r.type.elem, t.elem) && !sameType(r.type, t)
+                    ? { items: r.vec.items, count: vecCount(r.vec) }
+                    : undefined;
+            if (from) {
+                const n = this.tmp("vn");
+                this.line(`uint64_t ${n} = ${from.count};`);
+                this.line(`if (${n} > ${t.cap}) TS_FAIL(TS_ERR_INDEX, "TypeSOL: more elements than the ${typeName(t)} holds");`);
+                // Slots past the new length keep what they held, as after pop() / clear().
+                this.line(`ts_memcpy(${target.lv}.items, (const uint8_t *)${from.items}, ${n} * ${this.fieldBytes(t.elem)});`);
+                this.line(`${target.lv}.len = (uint32_t)${n};`);
+                return;
+            }
+        }
         const src = this.ref(valueNode) ?? this.wholeAccount(valueNode);
         if (!src || !sameType(src.type, target.type))
-            this.fail(valueNode, `expected a ${typeName(target.type)}: an object literal or another ${typeName(target.type)}`);
+            this.fail(valueNode, `expected a ${typeName(target.type)}: an object literal, another ${typeName(target.type)}${target.type.kind === "vec" && target.type.cap !== undefined ? " or a Vec of the same elements" : ""}`);
         // Same-typed places are either distinct or identical (`a.p = a.p`); ts_copy skips the latter.
         this.line(`ts_copy(&${target.lv}, &${src.lv}, sizeof(${target.lv}));`);
     }

package/dist/compiler/idl.js

@@ -93,7 +93,7 @@ function accountEntry(ix, name, k, programAddress) {
         entry.writable = true;
     if (param?.optional)
         entry.optional = true;
-    if (k.kind === "signer" || param?.signsInit)
+    if (k.kind === "signer" || param?.signsInit || param?.constraints.signed)
         entry.signer = true;
     if (k.kind === "system")
         entry.address = SYSTEM_PROGRAM;

package/dist/compiler/model.d.ts

@@ -63,6 +63,10 @@ export type ValueType = ScalarType | {
  | {
     kind: "remaining";
 }
+/** One instruction of the transaction (InstructionsSysvar.get(i)): a `TsIx` view into the sysvar. */
+ | {
+    kind: "txIx";
+}
 /** A struct loaded from a remaining account with loadAccount / loadAccountMut. */
  | {
     kind: "structRef";
@@ -190,6 +194,12 @@ export type ParamKind = {
     kind: "zeroed";
     struct: StructDef;
 }
+/** Anchor's Migration<From, To>: an existing `from` account rewritten as `to` by `acct.migrate(payer, value)`. */
+ | {
+    kind: "migrate";
+    from: StructDef;
+    to: StructDef;
+}
 /** `init`: an associated token account this instruction creates (`Ata<Init<TokenAccount>, …>`, create) or creates when
  * missing (`Ata<InitIfNeeded<TokenAccount>, …>`, createIfNeeded); it is a TokenAccount once that call has run. */
  | {
@@ -263,6 +273,10 @@ export interface Constraints {
     };
     /** Executable<A>: the account must be an executable program. */
     executable?: boolean;
+    /** Dup<A> (Anchor's `dup`): may be the same account as another writable parameter (see function.ts). */
+    dup?: boolean;
+    /** Signed<A> (Anchor's `signer` constraint on an account of another type): it must sign (2002). */
+    signed?: boolean;
     /** Close this account into that parameter when the instruction succeeds. */
     closeTo?: string;
     /** Address<A, "base58">: the account must be exactly this address. */

package/dist/compiler/model.js

@@ -20,6 +20,7 @@ export function isWritable(k) {
         case "init":
         case "zeroed":
         case "initIfNeeded":
+        case "migrate":
             return true;
         case "signer":
         case "info":
@@ -67,6 +68,8 @@ export function typeName(t) {
             return "AccountInfo";
         case "remaining":
             return "RemainingAccounts";
+        case "txIx":
+            return "TransactionInstruction";
         case "structRef":
             return t.struct;
     }

package/docs/architecture.md

@@ -102,7 +102,8 @@ These invariants are easy to break. Each one has tests.
   pointer per account, and lengths, lamports and owners a CPI changes are seen without copying anything back. CPIs
   go through `ts_invoke`, which builds `SolAccountInfo` records only for the accounts the call lists. It finds each
   record from its meta (the key sits 8 bytes into it), so every `SolAccountMeta` must point at `&acct->key` of an
-  instruction account, never at a derived or local `SolPubkey`.
+  instruction account, never at a derived or local `SolPubkey`. `invokeInstruction` is the one exception: its metas
+  point into data, so it calls `sol_invoke_signed` directly with records for every account it was handed.
 - **Runtime messages carry the source location.** `line()` appends `(file.ts:line)` to every `"TypeSOL: …"`
   message.
 - **No SDK byte loops.** Generated code and the runtime compare, copy and zero memory with `ts_key_eq`, `ts_mem_eq`,

package/docs/audit.md

@@ -40,6 +40,7 @@ accepts. Areas where a bug would be most damaging, and where earlier internal re
   the Vecs that follow, `@layout borsh` accounts.
 - **Arithmetic**: every operator and cast at every width, compound assignment, `mulDiv`, rent.
 - **CPIs and signing**: signer-seed arrays (including their reuse across statements), account flags in `invoke`,
+  `invokeInstruction` (metas from data, the infos it hands over, `ts_alloc` of the meta array),
   account creation on pre-funded addresses, closing.
 - **The runtime's parsing**: instruction data, the serialized accounts, Token-2022 extension data, oracle accounts and
   the instructions sysvar.

package/docs/case-study-escrow.md

@@ -184,9 +184,9 @@ Both implementations refuse the hostile calls the comparison makes:
 
 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.
+purpose: taker and maker are then the same writable account, which TypeSOL refuses for any two writable parameters
+unless one is marked `Dup<…>`, 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
 

package/docs/case-study-multisig.md

@@ -0,0 +1,167 @@
+# Case study: porting coral-xyz/multisig
+
+This page ports a program that holds real authority on mainnet:
+[coral-xyz/multisig](https://github.com/coral-xyz/multisig) (`programs/multisig/src/lib.rs`, Anchor 0.25, Apache-2.0),
+deployed at `msigUdDBsR4zSUYqYEDrc1LcgtmuSDDM7KxpRUXNC6U`. The port is
+[`examples/multisig.ts`](../examples/multisig.ts). Instead of a twin built for the occasion, it is checked against the
+binary that runs on mainnet: [`test/examples/multisig.test.ts`](../test/examples/multisig.test.ts) runs both under the
+same program id and compares every outcome and every account byte. See
+[case-study-escrow.md](case-study-escrow.md) for a token program and [Migrate from Anchor](migrate-from-anchor.md) for
+the general reference.
+
+## The program
+
+A multisig executes arbitrary instructions once `threshold` of its owners approve them. Its PDA (`[multisig]`, bump
+`multisig.nonce`) signs the instruction, so it can hold anything a key can: a program's upgrade authority, a mint
+authority, a treasury.
+
+- `create_multisig(owners, threshold, nonce)` initializes an account the client allocated in the same transaction.
+- `create_transaction(pid, accs, data)` stores a proposed instruction; the proposer, an owner, approves it.
+- `approve()` adds an owner's approval.
+- `execute_transaction()` runs the stored instruction through a CPI signed by the PDA once enough owners approved.
+- `set_owners(owners)`, `change_threshold(threshold)` and `set_owners_and_change_threshold(...)` change the multisig;
+  only its PDA can sign them, so they run as stored transactions the multisig executes on itself.
+
+Upstream it is 337 lines of Rust; the port is 184 lines of TypeScript, comments included.
+
+## What it needed
+
+The port needed five features TypeSOL did not have. They are general features now, each with tests of its own
+(`test/language/dynamic-cpi.test.ts`):
+
+| Anchor | TypeSOL | |
+| --- | --- | --- |
+| `invoke_signed(&ix, ctx.remaining_accounts, …)` with `ix` built from account data | `invokeInstruction(programId, metas, data, remainingAccounts(), seeds)` | A CPI decided at run time. Each meta is a struct with `pubkey`, `isSigner`, `isWritable`. The runtime finds each account among the infos by key and checks privileges, as it does for Rust. |
+| `#[account(zero, signer)] multisig: Box<Account<'info, Multisig>>` | `Signed<Zeroed<Multisig>>` of a `/** @layout borsh */` struct | `Zeroed` now takes Borsh structs (they start empty and are written as Borsh on return). `Signed<…>` is Anchor's `signer` constraint (2002). `Zeroed` now reports an already-set discriminator first, with Anchor's 2013. |
+| `seeds = [multisig.key().as_ref()], bump = multisig.nonce` | `Seeds<Signer, ["@multisig"], "@multisig.nonce">` | A bump stored in another account. |
+| `multisig.owners = owners` | the same, into a `FixedVec<Pubkey, 34>` | A `Vec` argument copied whole into a list in account data. |
+| `TransactionAccount { pubkey, is_signer, is_writable }` | `interface TransactionAccount { pubkey; isSigner; isWritable }` | `isSigner` / `isWritable` were reserved field names everywhere; now only in structs held in an account, where they would shadow `acct.isSigner`. |
+
+## Side by side
+
+The heart of the program, executing an approved transaction:
+
+```rust
+pub fn execute_transaction(ctx: Context<ExecuteTransaction>) -> Result<()> {
+    if ctx.accounts.transaction.did_execute {
+        return Err(ErrorCode::AlreadyExecuted.into());
+    }
+    let sig_count = ctx.accounts.transaction.signers.iter().filter(|&did_sign| *did_sign).count() as u64;
+    if sig_count < ctx.accounts.multisig.threshold {
+        return Err(ErrorCode::NotEnoughSigners.into());
+    }
+    let mut ix: Instruction = (*ctx.accounts.transaction).deref().into();
+    ix.accounts = ix.accounts.iter().map(|acc| {
+        let mut acc = acc.clone();
+        if &acc.pubkey == ctx.accounts.multisig_signer.key {
+            acc.is_signer = true;
+        }
+        acc
+    }).collect();
+    let multisig_key = ctx.accounts.multisig.key();
+    let seeds = &[multisig_key.as_ref(), &[ctx.accounts.multisig.nonce]];
+    let signer = &[&seeds[..]];
+    let accounts = ctx.remaining_accounts;
+    solana_program::program::invoke_signed(&ix, accounts, signer)?;
+    ctx.accounts.transaction.did_execute = true;
+    Ok(())
+}
+```
+
+```ts
+export function executeTransaction(
+  multisig: Account<Multisig>,
+  multisigSigner: Seeds<AccountInfo, ["@multisig"], "@multisig.nonce">,
+  transaction: HasOne<Mut<Transaction>, "multisig">,
+): void {
+  require(multisig.ownerSetSeqno === transaction.ownerSetSeqno, AnchorError.ConstraintRaw);
+  require(!transaction.didExecute, ErrorCode.AlreadyExecuted);
+  let sigCount = 0n;
+  for (const didSign of transaction.signers) if (didSign) sigCount++;
+  require(sigCount >= multisig.threshold, ErrorCode.NotEnoughSigners);
+  const metas: FixedVec<TransactionAccount, 32> = transaction.accounts.map((acc) => ({
+    pubkey: acc.pubkey,
+    isSigner: acc.isSigner || acc.pubkey === multisigSigner.key,
+    isWritable: acc.isWritable,
+  }));
+  invokeInstruction(transaction.programId, metas, transaction.data, remainingAccounts(), [multisig.key, multisig.nonce]);
+  transaction.didExecute = true;
+}
+```
+
+The `#[derive(Accounts)]` structs become parameter types. Anchor's `constraint = multisig.owner_set_seqno ==
+transaction.owner_set_seqno` becomes the first `require`, raising the same 2003. The error enum keeps its order and
+messages, so the codes stay 6000–6008. Account and instruction names and the Borsh layout are the original's, so
+existing clients and existing accounts work with the port unchanged.
+
+## How it was checked
+
+`test/programs/coral_multisig.so` is the program dumped from mainnet on 2026-10-29 (sha256 in
+[`test/programs/SOURCES.md`](../test/programs/SOURCES.md)). The test loads it into one LiteSVM and the port into
+another, both at `msigUdDB…`, then sends each transaction to both. After each one it requires the same outcome (success,
+or the same error down to the code) and the same lamports, owner and data bytes for every account involved.
+
+There are 43 transactions:
+
+- **The upstream test suite** (`tests/multisig.js`): create a 2-of-3 multisig, propose `set_owners`, approve, and
+  execute through the PDA. Then `Assert Unique Owners` (6008).
+- **Every `create_multisig` refusal**: threshold 0 or above the owner count (6007), no owners, the account not signing
+  (2002), not rent-exempt (2005), owned by another program (3007), too small for the empty value (3003) or for the
+  owners (3004), already initialized (2013).
+- **Proposals, approvals and executions**:
+  - a proposer or approver outside the owner set (6000);
+  - another multisig's transaction (2001);
+  - too few approvals (6002);
+  - a wrong PDA (2006);
+  - executing twice (6006);
+  - a changed owner set invalidating a proposal (2003);
+  - `set_owners` sent directly, which the PDA cannot sign (3010);
+  - a Transaction passed as a Multisig (3002);
+  - the target program missing from the remaining accounts (the runtime's error).
+- **Self-calls through `execute_transaction`**:
+  - `change_threshold`;
+  - `set_owners` shrinking the owner set below the threshold, which drops the threshold;
+  - `set_owners_and_change_threshold`;
+  - a threshold too high, which fails inside the CPI and fails the whole execution with 6007.
+- **A real payout**: the PDA sends 1.5 SOL through a System transfer. A stored meta claiming the recipient signed is
+  refused by the runtime under both programs.
+
+## Cost
+
+These are compute units per transaction, original versus port, from that test. Each `execute` figure includes the
+instruction it runs.
+
+| Instruction | Anchor 0.25 (mainnet) | TypeSOL | |
+| --- | ---: | ---: | ---: |
+| `create_multisig` | 3,591 | 564 | −84% |
+| `create_transaction` | 6,591 | 1,077 | −84% |
+| `approve` | 5,515 | 1,003 | −82% |
+| `execute_transaction` → `set_owners` | 15,227 | 4,133 | −73% |
+| `execute_transaction` → `change_threshold` | 14,723 | 3,781 | −74% |
+| `execute_transaction` → `set_owners_and_change_threshold` | 15,129 | 4,095 | −73% |
+| `execute_transaction` → System transfer | 9,961 | 3,182 | −68% |
+
+Refusals cost less too. For example, an already-initialized account costs 3,378 against 160, and a missing signature
+4,229 against 177. The binary is 526,688 bytes on mainnet and 29,984 bytes for the port, 18 times smaller. Deploying it
+needs about 3.5 SOL less rent.
+
+The original was built with Anchor 0.25; a rebuild with a current Anchor would cost less than the mainnet figures. The
+escrow case study and the benchmarks compare against Anchor 1.x.
+
+## Where they differ
+
+- **List capacities.** Anchor's `Vec` fields are bounded only by the account's size. The port's lists are `FixedVec`s:
+  - 34 owners;
+  - 32 accounts and 1,100 data bytes per stored instruction;
+  - 34 approvals.
+
+  A transaction (1,232 bytes) cannot carry more than these, so a client never meets them. A program calling the
+  multisig through a CPI can send more (CPI data may reach 10 KiB). The original would accept that if the account were
+  large enough; the port refuses with 5104. Reading an account the original wrote with more elements fails with 3003.
+- **Check order on one double fault.** In `approve` and `execute_transaction` the original checks the owner-set
+  sequence number (2003) with the multisig account, before the transaction's `has_one` (2001). The port checks
+  `has_one` in the prologue and the sequence number first in the body. So a transaction that belongs to another
+  multisig *and* has a stale sequence number gets 2001 here and 2003 there. A transaction breaking only one of the two
+  gets the same code under both.
+- **Logs.** Error messages are logged in TypeSOL's words and the original's error names are not logged; codes are the
+  same.

package/docs/errors.md

@@ -7,19 +7,20 @@ Framework errors use Anchor's numbers where Anchor has the same check, so client
 | 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) |
+| 2002 | a `Signed<…>` account (or the event authority) did not sign (ConstraintSigner) |
 | 2004 | Owner constraint failed (ConstraintOwner) |
 | 2005 | Zeroed account is not rent-exempt (ConstraintRentExempt) |
 | 2006 | PDA seeds mismatch (ConstraintSeeds) |
 | 2007 | Executable constraint failed (ConstraintExecutable) |
 | 2009 | not the associated token account (ConstraintAssociated) |
 | 2012 | not the expected address (ConstraintAddress) |
+| 2013 | a `Zeroed<…>` account whose discriminator is already set (ConstraintZero; checked before its owner, as under Anchor) |
 | 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) |
+| 3000 | account already exists (AccountDiscriminatorAlreadySet; an `Init` account) |
 | 3002 | discriminator mismatch (AccountDiscriminatorMismatch) |
 | 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) |
@@ -70,5 +71,5 @@ Where TypeSOL's order differs, only a transaction that breaks two of these check
 - 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
+- TypeSOL refuses any two writable parameters naming one account (2040) unless one is `Dup<…>`, 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

@@ -25,8 +25,8 @@ The full reference. For a tour, start with the [README](../README.md).
 | Enums | `export enum Status { Pending, Approved }` — unit variants stored as the Borsh u8 index; `Status.Approved`, `===` |
 | Options | `best: Option<u64>` (or `u64 \| null`) — `null`, `=== null`, TypeScript narrowing; `===` between options or with a value follows JS (null equals null, empty never equals a value); empty use aborts (5108); `acct?.field` on an optional account and `x.home?.field` on an `Option<struct>` give an Option (empty when the account was left out / the option is empty), `a ?? b` takes b only when a is empty (b runs only then; the result is an Option when b can be null), `x!` is the value or aborts with 5108; `${opt}` prints the value or `null`. Borsh `option` in arguments/events, fixed `{ is_some, value }` in account data |
 | Vecs | `entries: Vec<Entry>` in account data, any number of them, declared anywhere: they are stored after the fixed-size fields in the order declared (so every other field keeps its offset; the IDL lists that order), and a push, pop or clear moves the Vecs after it (a reference into one of those cannot be used across it). In a `@layout borsh` struct a Vec is the last field (Anchor's order) — `get`, `set`, `push(v, payer)`, `pop()`, `clear()`, `.length`; the account is resized (realloc) and rent topped up by `payer`; `Vec<u64>` arguments are read-only views; `Vec<string>` arguments (Anchor's `Vec<String>`) are views of the instruction data, each checked as UTF-8 on entry (102), and go back out as Borsh through `invoke`; `pop()` of a Vec of structs works as a statement |
-| Anchor's account bytes | `/** @layout borsh */` on an account struct stores it as Anchor does (Borsh: a `FixedString<N>` is a String, a `FixedVec<T, N>` a Vec, an `Option` one byte when empty, and the fields after them move), so a TypeSOL program can take over accounts an Anchor program wrote and the IDL lists Anchor's own types. The instruction unpacks it into the usual fixed layout when it starts (bad bytes fail with 3003) and packs it back when it returns (3004 when the account is too small for the new value), so everything else works on it unchanged. Programs invoked from the body (CPIs) see the account's bytes as they were when the instruction started. Costs more compute than the fixed layout (the whole account is read and written each time; see the benchmarks); nested structs and list elements must be fixed-size (FixedString elements allowed). The same struct is Borsh as a whole instruction argument (checked like Borsh deserialization, UTF-8 included), as return data and as an event; as those (not as account data) it may also hold `string` fields and data enums carrying strings, Anchor's `String` and enums in argument structs (account data takes data enums without strings); not inside list or enum arguments, `Zeroed<T>`, `loadAccount` or a growable `Vec<T>` |
-| Fixed-capacity lists | `owners: FixedVec<Pubkey, 8>` — any field, any number of them, in nested structs too: a u32 length and room for N elements (always 4 + N × size bytes), the same `get`, `set`, `push(v)`, `pop()`, `clear()`, `.length` and `for … of`; `push` on a full one fails (5104); `acct.owners = fixedVec([a, b])` writes a whole one (unused slots zeroed). In account data, returned structs and events; as an argument (`ids: FixedVec<u64, 8>`) it is a Borsh Vec of at most N elements, read like a `Vec` argument (more fail with 102) |
+| Anchor's account bytes | `/** @layout borsh */` on an account struct stores it as Anchor does (Borsh: a `FixedString<N>` is a String, a `FixedVec<T, N>` a Vec, an `Option` one byte when empty, and the fields after them move), so a TypeSOL program can take over accounts an Anchor program wrote and the IDL lists Anchor's own types. The instruction unpacks it into the usual fixed layout when it starts (bad bytes fail with 3003) and packs it back when it returns (3004 when the account is too small for the new value), so everything else works on it unchanged. Programs invoked from the body (CPIs) see the account's bytes as they were when the instruction started. Costs more compute than the fixed layout (the whole account is read and written each time; see the benchmarks); nested structs and list elements must be fixed-size (FixedString elements allowed). The same struct is Borsh as a whole instruction argument (checked like Borsh deserialization, UTF-8 included), as return data and as an event; as those (not as account data) it may also hold `string` fields and data enums carrying strings, Anchor's `String` and enums in argument structs (account data takes data enums without strings); not inside list or enum arguments, `loadAccount` or a growable `Vec<T>` |
+| Fixed-capacity lists | `owners: FixedVec<Pubkey, 8>` — any field, any number of them, in nested structs too: a u32 length and room for N elements (always 4 + N × size bytes), the same `get`, `set`, `push(v)`, `pop()`, `clear()`, `.length` and `for … of`; `push` on a full one fails (5104); `acct.owners = fixedVec([a, b])` writes a whole one (unused slots zeroed), and `acct.owners = owners` copies a `Vec` argument (or another list of the same elements) into it, Anchor's `multisig.owners = owners` (more than N fail with 5104). In account data, returned structs and events; as an argument (`ids: FixedVec<u64, 8>`) it is a Borsh Vec of at most N elements, read like a `Vec` argument (more fail with 102) |
 | Struct arguments | `order: Order`, `ids: FixedArray<u8, 4>`, `orders: Vec<Order>` — fixed layouts, Borsh-identical, validated on entry (bools, enums, option tags, string lengths, enum tags; 102) and read-only. A struct holding a FixedVec that is only ever an argument is read as Anchor sends it (its FixedVec a Borsh Vec, as `@layout borsh`) |
 | Remaining accounts | `remainingAccounts()` — `.length`, `.get(i)` → `key`, `owner`, `lamports` (writes check writability), `isSigner`, `isWritable`; `loadAccount<T>` / `loadAccountMut<T>` give checked struct views; pass them to `invoke`, one at a time or spread: `...remainingAccounts()` (each with the flags it was passed with), `...readonly(rest)` / `...writable(rest)` (all with that role), `rest.slice(a, b)` for part of them; a CPI lists at most 32 accounts (5113) |
 | Struct literals | `book.entries.push({ who: who.key, amount, status: Status.Pending, note }, who)` — every field required |
@@ -38,7 +38,7 @@ 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; 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) |
+| 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; `stackHeight()` is 1 when the transaction calls the program directly, more under a CPI (`require(stackHeight() === 1n, …)` refuses CPI callers); `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 |
@@ -66,7 +66,7 @@ The full reference. For a tour, start with the [README](../README.md).
 | `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. 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<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. a bump stored in another struct account is named `"@acct.field"` (Anchor `bump = multisig.nonce`); `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", "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 |
@@ -76,7 +76,9 @@ The full reference. For a tour, start with the [README](../README.md).
 | `A \| null` / `Optional<A>` | optional account (Anchor `Option<Account>`): the client passes this program's id to leave it out; its checks and constraints run only when present; `x !== null` before use, or `x!` / `x!.field` to assert it was passed (5115 otherwise); `optional` in the IDL |
 | `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` |
+| `Migrate<From, To>` | Anchor 1.0's `Migration`: an existing `From` account (owner, discriminator, size) rewritten as `To` by `acct.migrate(payer, value)`, a top-level statement the instruction must reach. `acct.from` (read-only) before it, `acct.to` after; the value is built in full before the rewrite, so it may read `acct.from`. Resized to `To` (the payer tops up rent when it grows, at most 10 KiB; shrinking keeps the lamports; growing needs `SystemProgram`). Fixed-layout structs without growable Vecs; no constraints yet; the account cannot be passed to a helper (use `acct.to` fields in the instruction). An account already migrated fails with 3002. Keep the old struct under a new name with its discriminator: `/** @discriminator account:Counter */ interface CounterV1 { … }` |
+| `Zeroed<T>` | accounts (up to 10 MiB) the client allocated with System `CreateAccount`, Anchor's `zero`: discriminator still zero (2013, checked first as under Anchor), owned by this program, big enough, rent-exempt — then initialized. A `@layout borsh` struct starts empty and is written as Borsh when the instruction returns |
+| `Signed<A>` | the account must sign the transaction (Anchor's `signer` constraint, 2002), e.g. `Signed<Zeroed<Multisig>>` for an account the client creates with a fresh keypair; the IDL marks it a signer |
 | `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` |
@@ -86,6 +88,7 @@ The full reference. For a tour, start with the [README](../README.md).
 | `AssociatedTokenProgram` | `create` / `createIdempotent` CPIs; `associatedTokenAddress(owner, mint, tokenProgram)` |
 | `TokenMetadataProgram` | Metaplex `createV3(...)` (CreateMetadataAccountV3), optionally with `{ creators: [{ address, verified, share }], collection: mint }` after `isMutable` (1–5 creators, shares adding up to 100; only the update authority, signing, can be `verified: true`; the collection is written unverified; `isCollection: true` makes the NFT a sized collection); `createMasterEditionV3(edition, mint, updateAuthority, mintAuthority, payer, metadata, tokenProgram, systemProgram, maxSupply \| null)`; `verifyCollection(authority, metadata, collectionMint, collectionMetadata, collectionMasterEdition, systemProgram, instructionsSysvar)` (Verify with CollectionV1); `metadataAddress(mint)`, `masterEditionAddress(mint)` |
 | `InstructionsSysvar`, `PythPriceUpdate`, `SwitchboardFeed` | exact address / owner program + discriminator |
+| `InstructionsSysvar` (introspection) | `ixs.length`, `ixs.currentIndex()` (the top-level instruction being executed), `ixs.get(i)` → a `TransactionInstruction`: `programId`, `accountsLength`, `dataLength`, `accountKey(j)` / `accountIsSigner(j)` / `accountIsWritable(j)`, `readU8/U16/U32/U64/readPubkey(offset)` (little-endian), `is(program, "name")` (that program's instruction by its default Anchor discriminator, sha256("global:<name>"); an instruction with its own `@discriminator` is matched with `programId` and `readU64(0)` instead). Every read is bounds-checked (5104). It is the transaction author's data: require things of the transaction with it (a repay instruction after a flash loan), never treat it as proof |
 | `Program<"Address…">` | exact program address + executable |
 | `UncheckedProgram` | executable only — check `.key` yourself |
 | `AccountInfo` / `Mut<AccountInfo>` | nothing (writable for `Mut`); `owner`, `executable` |
@@ -94,7 +97,10 @@ 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). A remaining account
+account written through `.lamports` or `loadAccountMut` is another account of the instruction). `Dup<Mut<T>>`
+(Anchor's `dup`) lifts that for one parameter when both accounts are read and written in place (not created, closed,
+a close destination or `@layout borsh`): a write through either is seen through the other, so read what you need
+before writing. 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.
 
@@ -146,6 +152,20 @@ export function payOut(admin: Signer, treasury: Mut<SystemAccount>, recipient: M
 - `signerSeeds` (with the bump) signs for this program's PDA.
 - After the call, `returnData<u64>(program)` reads what the callee returned, checking the size and that it came from `program`.
 
+A call decided at run time, such as one a multisig stored in account data, is `invokeInstruction` (Rust's
+`invoke_signed(&Instruction { program_id, accounts, data }, infos, seeds)`):
+
+```ts
+invokeInstruction(transaction.programId, transaction.accounts, transaction.data, remainingAccounts(), [multisig.key, multisig.nonce]);
+```
+
+- the accounts are a list of structs with `pubkey`, `isSigner` and `isWritable` (a Vec or FixedVec in account data, a
+  Vec argument, or a stored `map` result); the data a list of u8.
+- every account in the fourth argument (`remainingAccounts()` or a slice) is handed to the runtime, which finds each
+  meta's account there by key: one that is missing fails the call, as under Rust.
+- the runtime checks the privileges: a meta may be a signer or writable only as the transaction passed that account,
+  or as a PDA of this program the seeds (fifth argument) sign for. See `examples/multisig.ts`.
+
 Typed calls from an IDL: `typesol cpi other.json --out other_cpi.ts` writes one helper per instruction
 (`vaultDeposit(program, owner, vault, systemProgram, amount, seeds)`), with the account flags, discriminator and
 argument encoding taken from the IDL (Anchor 0.30+ / 1.x, or TypeSOL's own). Call it with `signer([...seeds, bump])`