@typesol/cli 0.18.0 → 0.20.0

package/dist/compiler/emit/cpi.js

@@ -396,8 +396,6 @@ export class CpiEmitter extends CallEmitter {
         const fixedArgs = isMint ? (extArg ? 6 : 5) : 4;
         if (a.length !== fixedArgs && a.length !== fixedArgs + 1)
             this.fail(node, usage);
-        if (extArg && ifNeeded)
-            this.fail(extArg, "createIfNeeded does not take extensions yet: create the mint with create(…)");
         const payer = this.accountParam(a[0], "the payer");
         if (payer.kind.kind !== "signer" || !payer.kind.mut)
             this.fail(a[0], "the payer must be a Mut<Signer>");
@@ -438,6 +436,7 @@ export class CpiEmitter extends CallEmitter {
         };
         let mint;
         const extLines = [];
+        const extChecks = [];
         let mintSpace = "TS_MINT_LEN";
         if (isMint) {
             take(a[2], U8);
@@ -447,9 +446,10 @@ export class CpiEmitter extends CallEmitter {
             if (extArg) {
                 if (programs[0].kind.kind === "tokenProgram" && programs[0].kind.flavor === "token")
                     this.fail(extArg, "mint extensions are Token-2022's; use Token2022Program or TokenInterface");
-                const ext = this.mintExtensions(extArg, tp, acct);
+                const ext = this.mintExtensions(extArg, tp, acct, ifNeeded);
                 mintSpace = String(ext.space);
                 extLines.push(...ext.lines);
+                extChecks.push(...ext.checks);
             }
         }
         else {
@@ -474,6 +474,8 @@ export class CpiEmitter extends CallEmitter {
                 this.line(`  TS_TRY(ts_token_existing(params, ${acct}, ${tp}, ${seeds.name}, ${seeds.count}, &${b}));`);
                 this.line(`  TS_TRY(ts_check_mint(${acct}));`);
                 this.line(`  TS_TRY(ts_check_mint_is(${acct}, (uint8_t)(${decimals.c}), ${authority.c}, ${freeze ? freeze.c : "NULL"}));`);
+                for (const l of extChecks)
+                    this.line(`  ${l}`);
                 this.line(`}`);
             }
             else
@@ -510,7 +512,7 @@ export class CpiEmitter extends CallEmitter {
      * in source order; the returned lines (each extension's Token-2022 initializer, mint writable, before
      * InitializeMint2) run after the account is created, sized for exactly these extensions.
      */
-    mintExtensions(lit, tp, acct) {
+    mintExtensions(lit, tp, acct, ifNeeded = false) {
         const optKey = { kind: "option", inner: PUBKEY };
         this.model.options.set("pubkey", PUBKEY);
         // name: [extension type length, initializer tag, the fields an object value takes ([] for a plain value)]
@@ -676,8 +678,60 @@ export class CpiEmitter extends CallEmitter {
                 }
             }
         }
+        // An existing mint (createIfNeeded) is checked as Anchor's `extensions::…` constraints check it: the extension must
+        // be there (its Anchor code) and each key must match (the next codes). Anchor has constraints for these six only.
+        const CHECKS = {
+            groupPointer: {
+                type: 20,
+                code: 2024,
+                fields: [
+                    ["authority", 0],
+                    ["groupAddress", 32],
+                ],
+            },
+            groupMemberPointer: {
+                type: 21,
+                code: 2027,
+                fields: [
+                    ["authority", 0],
+                    ["memberAddress", 32],
+                ],
+            },
+            metadataPointer: {
+                type: 18,
+                code: 2030,
+                fields: [
+                    ["authority", 0],
+                    ["metadataAddress", 32],
+                ],
+            },
+            closeAuthority: { type: 3, code: 2033, fields: [["v", 0]] },
+            permanentDelegate: { type: 12, code: 2035, fields: [["v", 0]] },
+            transferHook: {
+                type: 14,
+                code: 2037,
+                fields: [
+                    ["authority", 0],
+                    ["programId", 32],
+                ],
+            },
+        };
+        const checks = [];
+        if (ifNeeded)
+            for (const [name, v] of held) {
+                const c = CHECKS[name];
+                if (!c)
+                    this.fail(lit, `${name} cannot be checked on an existing mint (Anchor has no constraint for it): create the mint with create(…)`);
+                checks.push(`{ uint64_t eo, el; if (!ts_t22_ext(${acct}, ${c.type}, &eo, &el)) TS_FAIL(${c.code}, "TypeSOL: the mint has no ${name} extension"); }`);
+                c.fields.forEach(([f, at], i) => {
+                    const held = v.get(f);
+                    // The value given: a nonzero-or-zero key, a COption (close authority) or a plain key (permanent delegate).
+                    const want = name === "closeAuthority" ? `(${held}.some ? ${held}.v : (SolPubkey){0})` : held;
+                    checks.push(`{ SolPubkey k, w = ${want}; if (!ts_t22_key(${acct}, ${c.type}, ${at}, &k)) ts_memzero(&k, 32); if (!ts_key_eq(&k, &w)) TS_FAIL(${c.code + 1 + i}, "TypeSOL: the mint's ${name} ${f === "v" ? "key" : f} differs"); }`);
+                });
+            }
         // Base account (165, the mint padded to an account's size), the account type byte, then each TLV entry.
-        return { space: 165 + 1 + space, lines };
+        return { space: 165 + 1 + space, lines, checks };
     }
     /**
      * `ata.create(payer)` / `ata.createIfNeeded(payer)` on `Ata<Init|InitIfNeeded<TokenAccount>, "owner", "mint">`
@@ -1847,6 +1901,58 @@ export class CpiEmitter extends CallEmitter {
                 this.cpi(p, metas, data.buf, data.len, seedsAt(13));
                 return undefined;
             }
+            case "mintToCollection": {
+                // MintToCollectionV1: MintV1's accounts plus the collection authority (signing), its record PDA (or null),
+                // the collection mint, metadata (writable) and master edition, Bubblegum's signer PDA and Token Metadata;
+                // MetadataArgs with Some({ verified: false, key: collection mint }) (Bubblegum verifies it).
+                if (a.length !== 17 && a.length !== 18)
+                    this.fail(node, "mintToCollection(treeConfig, leafOwner, leafDelegate, merkleTree, payer, treeDelegate, collectionAuthority, collectionAuthorityRecordPda | null, collectionMint, collectionMetadata, collectionEdition, bubblegumSigner, logWrapper, compressionProgram, tokenMetadataProgram, systemProgram, { name, symbol, uri, sellerFeeBasisPoints, creators?, isMutable?, editionNonce? }, signerSeeds?)");
+                const metas = [
+                    acct(0, "the tree config", true, false),
+                    acct(1, "the leaf owner", false, false),
+                    acct(2, "the leaf delegate", false, false),
+                    acct(3, "the merkle tree", true, false),
+                    acct(4, "the payer", false, true),
+                    acct(5, "the tree delegate", false, true),
+                    acct(6, "the collection authority", false, true),
+                    acct(7, "the collection authority record", false, false),
+                    acct(8, "the collection mint", false, false),
+                    acct(9, "the collection metadata", true, false),
+                    acct(10, "the collection edition", false, false),
+                    acct(11, "Bubblegum's signer", false, false),
+                    acct(12, "the log wrapper", false, false),
+                    acct(13, "the compression program", false, false),
+                    acct(14, "Token Metadata", false, false),
+                    acct(15, "the system program", false, false),
+                ];
+                const md = a[16];
+                if (!ts.isObjectLiteralExpression(md))
+                    this.fail(md, "the metadata is { name, symbol, uri, sellerFeeBasisPoints, creators?, isMutable?, editionNonce? }");
+                const props = this.literalProps(md, ["name", "symbol", "uri", "sellerFeeBasisPoints", "creators", "isMutable", "editionNonce"], "the metadata");
+                const need = (k) => props.get(k) ?? this.fail(md, `the metadata needs ${k}`);
+                // `collectionMint.key`, read where the call is.
+                const key = ts.factory.createPropertyAccessExpression(a[8], "key");
+                ts.setTextRange(key, a[8]);
+                key.parent = node;
+                const nonce = props.get("editionNonce");
+                const data = this.mplData(node, 1024, [
+                    { bytes: [153, 18, 178, 47, 197, 158, 86, 15] },
+                    { value: need("name"), type: STRING },
+                    { value: need("symbol"), type: STRING },
+                    { value: need("uri"), type: STRING },
+                    { value: need("sellerFeeBasisPoints"), type: { kind: "int", name: "u16" } },
+                    { bytes: [0] }, // primarySaleHappened
+                    props.get("isMutable") ? { value: props.get("isMutable"), type: BOOL } : { bytes: [1] },
+                    ...(nonce ? [{ bytes: [1] }, { value: nonce, type: U8 }] : [{ bytes: [0] }]),
+                    { bytes: [1, 0] }, // tokenStandard Some(NonFungible)
+                    { bytes: [1, 0] }, // collection Some({ verified: false, … })
+                    { value: key, type: PUBKEY },
+                    { bytes: [0, 0] }, // uses None, tokenProgramVersion Original
+                    ...this.bubblegumCreators(props.get("creators")),
+                ]);
+                this.cpi(p, metas, data.buf, data.len, seedsAt(17));
+                return undefined;
+            }
         }
         return this.bubblegumV2(node, bg, method);
     }
@@ -2128,7 +2234,7 @@ export class CpiEmitter extends CallEmitter {
             this.cpi(p, metas, data.buf, data.len, seedsAt(proofAt + 1), proofRange(a[proofAt]));
             return undefined;
         }
-        this.fail(node.expression, `Bubblegum supports createTree, mint, createTreeV2, mintV2, transferV2, burnV2, ${Object.keys(BUBBLEGUM_OPS).join(", ")}, not ${method}`);
+        this.fail(node.expression, `Bubblegum supports createTree, mint, mintToCollection, createTreeV2, mintV2, transferV2, burnV2, ${Object.keys(BUBBLEGUM_OPS).join(", ")}, not ${method}`);
     }
     /** Object literal properties by name, refusing others. */
     literalProps(o, allowed, what) {

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

@@ -23,6 +23,25 @@ export declare abstract class ExpressionEmitter extends StorageEmitter {
     /** Whether TypeScript sees this expression as a string (decides `+` between concatenation and arithmetic). */
     protected looksLikeString(node: ts.Expression): boolean;
     /** A string view of a string, integer or boolean (for concatenation and templates). */
+    /**
+     * A template literal's pieces in order, text known at compile time folded in: all text (`text`), or a C array of
+     * TS_Str (`arr`, `n` entries). When a later piece runs statements, earlier pieces that view account text are copied
+     * first, as JS reads them then.
+     */
+    protected templatePieces(node: ts.TemplateExpression): {
+        text: string;
+        arr?: undefined;
+        n?: undefined;
+    } | {
+        text?: undefined;
+        arr: string;
+        n: number;
+    };
+    /**
+     * The text of `${e}` when it is known at compile time: a string literal or constant, a non-negative integer
+     * literal, a boolean literal, or a Pubkey constant (its base58). Undefined otherwise.
+     */
+    protected constantText(e: ts.Expression): string | undefined;
     protected toText(node: ts.Expression): string;
     /** C statement writing the decimal text of an integer into the TS_Str `out`. */
     protected textOfInt(name: IntName, c: string, out: string): string;

package/dist/compiler/emit/expressions.js

@@ -1,4 +1,5 @@
 import ts from "typescript";
+import { base58 } from "../../keys.js";
 import { calleeName, resolveValueType } from "../analyze.js";
 import { INT_INFO, unsignedC, optionKey, sameType, typeName } from "../model.js";
 import { U64, U8, I64, BOOL, PUBKEY, STRING, HASH, cString, intLiteral, scalarStorageC, optC, valueC, vecCount } from "./shared.js";
@@ -151,22 +152,14 @@ export class ExpressionEmitter extends StorageEmitter {
             return { c: `ts_str((const uint8_t *)${cString(node.text)}, ${len})`, type: STRING, stringLiteral: node.text };
         }
         if (ts.isTemplateExpression(node)) {
-            // `a${x}b${y}c` -> concatenations on the heap
-            let acc = this.tmp("tpl");
-            const head = node.head.text;
-            this.line(`TS_Str ${acc} = ts_str((const uint8_t *)${cString(head)}, ${Buffer.byteLength(head, "utf8")});`);
-            for (const span of node.templateSpans) {
-                for (const piece of [
-                    this.toText(span.expression),
-                    `ts_str((const uint8_t *)${cString(span.literal.text)}, ${Buffer.byteLength(span.literal.text, "utf8")})`,
-                ]) {
-                    const next = this.tmp("tpl");
-                    this.line(`TS_Str ${next};`);
-                    this.line(`TS_TRY(ts_str_concat(${acc}, ${piece}, &${next}));`);
-                    acc = next;
-                }
-            }
-            return { c: acc, type: STRING };
+            // `a${x}b${y}c`: one join on the heap (or a literal when every piece is known at compile time).
+            const pieces = this.templatePieces(node);
+            if (pieces.text !== undefined)
+                return { c: `ts_str((const uint8_t *)${cString(pieces.text)}, ${Buffer.byteLength(pieces.text, "utf8")})`, type: STRING, stringLiteral: pieces.text };
+            const t = this.tmp("tpl");
+            this.line(`TS_Str ${t};`);
+            this.line(`TS_TRY(ts_str_join(${pieces.arr}, ${pieces.n}, &${t}));`);
+            return { c: t, type: STRING };
         }
         if (node.kind === ts.SyntaxKind.NullKeyword)
             return { c: "", type: BOOL, isNull: true };
@@ -430,6 +423,68 @@ export class ExpressionEmitter extends StorageEmitter {
         return isText(this.checker.getTypeAtLocation(node));
     }
     /** A string view of a string, integer or boolean (for concatenation and templates). */
+    /**
+     * A template literal's pieces in order, text known at compile time folded in: all text (`text`), or a C array of
+     * TS_Str (`arr`, `n` entries). When a later piece runs statements, earlier pieces that view account text are copied
+     * first, as JS reads them then.
+     */
+    templatePieces(node) {
+        const parts = [];
+        const lit = (text) => {
+            if (!text)
+                return;
+            const last = parts.at(-1);
+            if (last?.text !== undefined)
+                last.text += text;
+            else
+                parts.push({ text });
+        };
+        lit(node.head.text);
+        for (const span of node.templateSpans) {
+            const known = this.constantText(span.expression);
+            if (known !== undefined)
+                lit(known);
+            else {
+                const mark = this.lines.length;
+                const c = this.toText(span.expression);
+                for (const p of parts)
+                    if (p.c !== undefined)
+                        p.c = this.settle({ c: p.c, type: STRING }, mark).c;
+                parts.push({ c });
+            }
+            lit(span.literal.text);
+        }
+        if (parts.every((p) => p.text !== undefined))
+            return { text: parts.map((p) => p.text).join("") };
+        const strOf = (text) => `ts_str((const uint8_t *)${cString(text)}, ${Buffer.byteLength(text, "utf8")})`;
+        const arr = this.tmp("parts");
+        this.line(`TS_Str ${arr}[${parts.length}] = {${parts.map((p) => (p.text !== undefined ? strOf(p.text) : p.c)).join(", ")}};`);
+        return { arr, n: parts.length };
+    }
+    /**
+     * The text of `${e}` when it is known at compile time: a string literal or constant, a non-negative integer
+     * literal, a boolean literal, or a Pubkey constant (its base58). Undefined otherwise.
+     */
+    constantText(e) {
+        if (ts.isParenthesizedExpression(e))
+            return this.constantText(e.expression);
+        if (ts.isStringLiteral(e) || ts.isNoSubstitutionTemplateLiteral(e))
+            return e.text;
+        if (e.kind === ts.SyntaxKind.TrueKeyword)
+            return "true";
+        if (e.kind === ts.SyntaxKind.FalseKeyword)
+            return "false";
+        if (ts.isBigIntLiteral(e))
+            return BigInt(e.text.slice(0, -1).replace(/_/g, "")).toString();
+        if (ts.isIdentifier(e) && !this.lookup(e.text)) {
+            const k = this.model.constants.get(e.text);
+            if (k && typeof k.value === "string")
+                return k.value;
+            if (k && typeof k.value === "object")
+                return base58(Uint8Array.from(k.value.pubkey));
+        }
+        return undefined;
+    }
     toText(node) {
         const v = this.expr(node);
         if (v.type.kind === "string")

package/dist/compiler/emit/function.js

@@ -371,15 +371,17 @@ 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 f of c.hasOne) {
+            for (const entry of c.hasOne) {
+                // "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 (!ts_key_eq(ts_token_mint(a_${a.name}), &a_${f}->key)) TS_FAIL(TS_ERR_TOKEN_MINT, "TypeSOL: ${a.name} is not a token account of ${f}");`
-                        : `  if (!ts_key_eq(ts_token_owner(a_${a.name}), &a_${f}->key)) TS_FAIL(TS_ERR_TOKEN_OWNER, "TypeSOL: ${a.name} is not owned by ${f}");`);
+                        ? `  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_${f}->key)) TS_FAIL(${code}, "TypeSOL: ${f} is not the ${f} of ${a.name}");`);
+                    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}");`);
                 }
                 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");`);

package/dist/compiler/emit/statements.js

@@ -842,7 +842,24 @@ export class StatementEmitter extends CpiEmitter {
                     this.line(`TS_Str ${cur};`);
                     this.line(`TS_TRY(ts_str_copy(${current.c}, &${cur}));`);
                 }
+                // A local grows in place when it is the newest heap string (a loop of `s += …` copies each piece once); a
+                // template on the right is appended piece by piece.
+                const local = cur === current.c && place.write("X") === `${cur} = X`;
+                const bare = (e) => (ts.isParenthesizedExpression(e) ? bare(e.expression) : e);
+                const rhsNode = bare(valueNode);
+                if (local && ts.isTemplateExpression(rhsNode)) {
+                    const pieces = this.templatePieces(rhsNode);
+                    if (pieces.text !== undefined)
+                        this.line(`TS_TRY(ts_str_append(&${cur}, ts_str((const uint8_t *)${cString(pieces.text)}, ${Buffer.byteLength(pieces.text, "utf8")})));`);
+                    else
+                        this.line(`TS_TRY(ts_str_append_parts(&${cur}, ${pieces.arr}, ${pieces.n}));`);
+                    return;
+                }
                 const rhs = this.toText(valueNode);
+                if (local) {
+                    this.line(`TS_TRY(ts_str_append(&${cur}, ${rhs}));`);
+                    return;
+                }
                 const t = this.tmp("cat");
                 this.line(`TS_Str ${t};`);
                 this.line(`TS_TRY(ts_str_concat(${cur}, ${rhs}, &${t}));`);

package/docs/client.md

@@ -25,23 +25,45 @@ ledgerbook.errorCode(e); // 6002
 // Events written by `emit`, from a transaction's log messages
 for (const ev of ledgerbook.parseEvents(logs)) if (ev.name === "Filed") ev.data.amount;
 
-// Return data of an instruction that returns a value
+// Return data of an instruction that returns a value, or the value itself by simulation (Anchor's `.view()`)
 ledgerbook.returns.total(returnDataBytes); // bigint
+await ledgerbook.views.total(rpc, signer, { book }, { status: Status.Approved }); // bigint, nothing sent
+
+// Send and confirm (one transaction, signers in the accounts sign too), or simulate
+const signature = await ledgerbook.sendInstructions({ rpc, rpcSubscriptions }, signer, [create, file]);
+const { err, logs, unitsConsumed, returnData } = await ledgerbook.simulate(rpc, signer, [file]);
+
+// Every Book of the program, or those with given bytes at an offset (after the 8-byte discriminator)
+const books = await ledgerbook.accounts.Book.fetchAll(rpc); // [{ address, data }]
+const several = await ledgerbook.accounts.Book.fetchMultiple(rpc, [a, b]); // (Book | null)[]
+
+// Live updates, until the AbortSignal aborts
+for await (const book of ledgerbook.accounts.Book.watch(rpcSubscriptions, address, { abortSignal })) render(book);
+for await (const { signature, event } of ledgerbook.watchEvents(rpcSubscriptions, { abortSignal })) show(event);
+
+// Remaining accounts go after the instruction's own (Anchor's `.remainingAccounts([...])`)
+await ledgerbook.approveMany({ approver: signer, book }, { indices: [0n, 1n] }, [{ address: extra, role: AccountRole.WRITABLE }]);
+
+// Events of a fetched transaction (getTransaction, json): log events and emitCpi events from inner instructions
+ledgerbook.eventsOf(await rpc.getTransaction(signature, { maxSupportedTransactionVersion: 0 }).send());
 ```
 
-Send instructions the usual kit way (`createTransactionMessage` … `signTransactionMessageWithSigners`). Signer
-accounts take a `TransactionSigner`, which kit uses to sign; an `Address` works too when you sign separately.
+Signer accounts take a `TransactionSigner`, which kit uses to sign; an `Address` works too when you sign separately.
+Kit's own transaction functions work with the instructions as well; `sendInstructions` is that pipeline in one call.
 
 ## What the client contains
 
 | | |
 | --- | --- |
 | `<program>.<instruction>(accounts, args)` | Builds the `Instruction`. Accounts with a fixed address and PDAs whose seeds are constants, arguments or other accounts' keys are optional and filled in; pass one to override. An optional account passed as `null` is left out (sent as the program id, the convention TypeSOL and Anchor share); left undefined, it is filled in like any other. |
-| `<program>.accounts.<Name>` | `decode(bytes)`, `encode(value)`, `fetch(rpc, address)`, `fetchMaybe(rpc, address)`, `discriminator`. `decode` checks the discriminator. |
+| `<program>.<instruction>(accounts, args, remaining?)` | The same, with remaining accounts appended in order (kit `AccountMeta`s). |
+| `<program>.accounts.<Name>` | `decode(bytes)`, `encode(value)`, `fetch(rpc, address)`, `fetchMaybe(rpc, address)`, `fetchMultiple(rpc, addresses)`, `fetchAll(rpc, filters?)` (getProgramAccounts by discriminator, plus `{ offset, bytes }` filters), `watch(rpcSubscriptions, address, { abortSignal })`, `discriminator`. `decode` checks the discriminator. |
 | `<program>.pdas.<account>(seeds)` | The PDA (address and bump) for each account an instruction derives. |
 | `<program>.returns.<instruction>(bytes)` | Decodes return data. |
-| `<program>.errors`, `errorCode(e)`, `isError(e, name)` | The program's errors (6000+), and for TypeSOL programs also TypeSOL's runtime errors and the Anchor framework errors it uses (2001, 2006, 3007, …). |
-| `<program>.parseEvents(logs)` | Events from `Program data:` log lines. |
+| `<program>.views.<instruction>(rpc, feePayer, accounts, args)` | Simulates an instruction that returns a value and decodes it (throws with the logs if it fails). |
+| `<program>.sendInstructions(connection, feePayer, instructions)`, `simulate(rpc, feePayer, instructions)` | One transaction sent and confirmed (kit's sendAndConfirm), or simulated without signatures (error, logs, units, this program's return data). |
+| `<program>.errors`, `errorCode(e)`, `isError(e, name)` | The program's errors (6000+), and for TypeSOL programs also every Anchor framework error (`AnchorError` and the constraints raise them) and TypeSOL's runtime errors. |
+| `<program>.parseEvents(logs)`, `parseCpiEvents(data)`, `eventsOf(tx)`, `watchEvents(rpcSubscriptions, { abortSignal })` | Events from `Program data:` log lines, from `emitCpi` inner instructions (bytes or base58), from a fetched transaction (both), or live from log subscriptions. |
 | Types and codecs | Every defined type as a TypeScript type (`Book`, the decoded value) and an input type (`BookArgs`, which also accepts `number` for 64- and 128-bit integers), with a kit codec (`getBookCodec()`). |
 
 Types follow the program's TypeScript: `u64`/`i64`/`u128`/`i128` are `bigint` (inputs accept `number` too), smaller
@@ -65,5 +87,6 @@ Anchor IDLs are refused with a hint to convert them (`anchor idl convert`).
   for each.
 - **Left out of a client generated from an Anchor IDL**, with a note: generic types and anything using them, and
   zero-copy (`bytemuck`) accounts.
-- **Not done yet**: events sent with `emitCpi` (they travel in inner instructions, not logs), and a LiteSVM loader for
-  tests (use `svm.addProgramFromFile(ledgerbook.address, soPath)`).
+- **Not done yet**: a LiteSVM loader for tests (use `svm.addProgramFromFile(ledgerbook.address, soPath)`, or
+  `typesol/testing`). `watchEvents` reads log events; `emitCpi` events are in inner instructions, which log
+  subscriptions do not carry (use `eventsOf` on the fetched transaction).

package/docs/language.md

@@ -11,7 +11,7 @@ The full reference. For a tour, start with the [README](../README.md).
 | Integers | `u8` `u16` `u32` `u64` `u128` `i8` `i16` `i32` `i64` `i128` — bigint literals (`1n`), every `+ - * / % **` (and `+=` … `**=`) checked (`**` aborts on a negative exponent, as JS throws); `& \| ^` on equal types, `~` within the width, `<<` / `>>` checked (amount below the width, `<<` may not lose bits) |
 | Integer helpers | `mulDiv(a, b, c)` / `mulDivCeil` (u64 through a 128-bit product, u128 through a 256-bit one), `isqrt(x)` (up to u128), `min(a, b)`, `max(a, b)` |
 | Other scalars | `boolean`, `Pubkey` (compare with `===` or `.equals`) |
-| Errors | `export enum MyError { Name = "message" }` + `require(cond, MyError.Name)` → codes 6000+ |
+| Errors | `export enum MyError { Name = "message" }` + `require(cond, MyError.Name)` → codes 6000+; `require(cond, AnchorError.RequireKeysEqViolated)` fails with one of Anchor's own codes (2502 here; every anchor-lang `ErrorCode`) |
 | Casts | `u8(x)`, `u64(x)`, … abort if the value does not fit |
 | Logging | `log("text")`, `log(value)`, `log(pubkey)` |
 | Arrays | `scores: FixedArray<u64, 8>` in account data — `.get(i)`, `.set(i, v)`, `.length`, bounds-checked; elements can be structs or strings |
@@ -36,7 +36,7 @@ The full reference. For a tour, start with the [README](../README.md).
 | Constants | top-level `const SEED = "vault"`, `const FEE: u16 = 30n`, `const ON = true` — inlined, usable as seeds (and described in the IDL) |
 | Data enums | `export type Action = { kind: "Deposit"; amount: u64 } \| { kind: "Pause" }` — `a.kind === "Deposit"`, `switch (a.kind)`, TypeScript narrowing picks the variant (checked again at runtime, 5112); Borsh enums in arguments/events, fixed `{ tag, payload }` in account data. A variant may hold a `string` (`{ kind: "Say"; text: string }`): such an enum works in arguments, events and locals (Borsh, as Anchor encodes it) but not in account data |
 | 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) |
+| 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">`) |
@@ -67,7 +67,7 @@ The full reference. For a tour, start with the [README](../README.md).
 | `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 |
 | `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 |
+| `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) |
 | `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,7 +77,7 @@ 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 (exactly one token program parameter, 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. `createIfNeeded(…)` returns whether it created it; an existing one must be that PDA and have those decimals and authorities (2018 / 2016 / 2017) |
+| `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 (exactly one token program parameter, 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) |
 | `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` |
@@ -159,8 +159,7 @@ Growable `Vec`s anywhere but the last account field (use `FixedVec<T, N>`), Fixe
 the next instruction), `?.` on anything but optional accounts and Option<struct> fields, `!` on anything but an Option
 or an optional account, Core's external plugin adapters (oracles, app data, lifecycle hooks: use `invoke`), closures
 stored or returned (they are called or passed to list methods), arrow literals and closures as helper arguments (pass a
-named function), `map` / `filter` (they would build a new list), mint extensions on `InitIfNeeded<Mint>` (create the
-mint with `create(…, extensions)`), floating point (by design).
+named function), `map` / `filter` (they would build a new list), floating point (by design).
 They are rejected at compile time rather than half-supported.
 
 `Init.create` handles a PDA address someone pre-funded: it tops up rent, then allocates and assigns instead of

package/docs/migrate-from-anchor.md

@@ -49,7 +49,7 @@ and error codes. Its notes (on stderr) list what an existing Anchor client would
 | `Program<'info, System>` | `SystemProgram` |
 | `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` | `HasOne<TokenAccount, "mint" \| "owner">` against parameters with those names |
+| `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) |
 | `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`) |
@@ -91,6 +91,8 @@ Anchor instruction that takes or returns a struct with `String` / `Vec` / `Optio
 | `-> Result<u64>` / a struct | `: u64` / a struct: sent as return data, listed in the IDL |
 | `#[error_code] enum MyError { #[msg("…")] X }` | `export enum MyError { X = "…" }` (codes from 6000, in order) |
 | `require!(c, MyError::X)`, `err!(MyError::X)` | `require(c, MyError.X)`, `require(false, MyError.X)` |
+| `require_keys_eq!(a, b)`, `err!(ErrorCode::AccountDidNotDeserialize)` (Anchor's own codes) | `require(a === b, AnchorError.RequireKeysEqViolated)`, `require(false, AnchorError.AccountDidNotDeserialize)` |
+| `init_if_needed` + `extensions::…` on a mint | `mint.createIfNeeded(…, { metadataPointer: {…}, … })`: an existing mint is checked as Anchor checks it (2024–2039) |
 | `require_keys_eq!(a, b)` | `require(a === b, …)` |
 | `a.checked_add(b).ok_or(…)?` | `a + b` (every operation is checked; overflow aborts with 5100) |
 | `emit!(Ev { … })` / `emit_cpi!` | `emit<Ev>({ … })` / `emitCpi<Ev>({ … }, eventAuthority, self)` |