@typesol/cli 0.23.0 → 0.24.1

package/dist/compiler/emit/cpi.js

@@ -207,6 +207,7 @@ export class CpiEmitter extends CallEmitter {
             ts.isPostfixUnaryExpression(n) ||
             ts.forEachChild(n, mutates) === true;
         const inPlace = !node.elements.some(mutates);
+        const mark = this.lines.length;
         for (const el of node.elements) {
             const desc = this.describeSeed(el);
             if (!desc)
@@ -252,9 +253,19 @@ export class CpiEmitter extends CallEmitter {
             else
                 this.fail(el, "seeds can be strings, Pubkeys, integers or unit enum values");
         }
+        // The same list again (escrow: the vault transfer, then its close) reuses the array declared for the first, when
+        // nothing was copied into temporaries (every entry points at a literal or at the place itself, so the array reads
+        // what a new one would), it has no spare slot (callers never write into those arrays) and it is still in scope.
+        const key = parts.join(", ");
+        const reusable = extra === 0 && parts.length > 0 && this.lines.length === mark;
+        const known = reusable ? this.seedArrays.get(key) : undefined;
+        if (known && this.scopes.includes(known.scope) && this.lines[known.at]?.trim() === known.text)
+            return { name: known.name, count: parts.length, idl };
         const name = this.tmp("seeds");
         const slots = parts.length + extra;
         this.line(`SolSignerSeed ${name}[${Math.max(slots, 1)}] = {${parts.join(", ")}};`);
+        if (reusable)
+            this.seedArrays.set(key, { name, scope: this.scopes[this.scopes.length - 1], at: this.lines.length - 1, text: this.lines.at(-1).trim() });
         return { name, count: parts.length, idl };
     }
     describeSeed(el) {
@@ -1526,6 +1537,8 @@ export class CpiEmitter extends CallEmitter {
                 this.line(`static const uint8_t ${name}[${f.bytes.length}] = ${cBytes(f.bytes)};`);
                 put(name, String(f.bytes.length), f.bytes.length);
             }
+            else if ("c" in f)
+                put(f.c, f.n);
             else
                 this.serialize(this.expect(this.expr(f.value, f.type), f.type, f.value), f.value, put);
         }
@@ -1713,124 +1726,354 @@ export class CpiEmitter extends CallEmitter {
         });
         return [{ bytes: [1, els.length & 0xff, 0, 0, 0] }, ...els.flatMap((e) => this.corePlugin(e, true))];
     }
-    /** Metaplex Core: assets and collections (with plugins), plugins added, updated and removed, transfer and burn. */
+    /**
+     * Metaplex Core: assets and collections (with plugins), plugins and external plugin adapters added, updated, written
+     * and removed, transfer and burn. Each method is a row of CORE_OPS below: its accounts in order, its data.
+     */
     coreOp(node, core, method) {
         const a = node.arguments;
         const p = `a_${core.name}`;
-        const seedsAt = (i) => (a[i] ? this.signingSeeds(a[i]) : { name: "NULL", count: 0 });
-        const str = (n) => ({ value: n, type: STRING });
-        // An array literal of object literals after the uri is the plugin list; the signer seeds come after it.
+        const op = this.coreOps()[method];
+        if (!op)
+            this.fail(node.expression, `Metaplex Core supports createAsset, createCollection, addPlugin, updatePlugin, removePlugin, addExternalPlugin, removeExternalPlugin, writeExternalPluginData (and the Collection forms), transferAsset and burnAsset, not ${method}`);
+        // An array literal of object literals right after the fixed arguments is the plugin list; the signer seeds follow.
         const isPlugins = (n) => !!n && ts.isArrayLiteralExpression(n) && (n.elements.length === 0 || n.elements.every((e) => ts.isObjectLiteralExpression(e)));
-        const self = [p, false, false];
-        switch (method) {
-            case "createAsset": {
-                // CreateV1: asset, collection, authority, payer, owner, updateAuthority, systemProgram, logWrapper.
-                const plugins = isPlugins(a[8]) ? a[8] : undefined;
-                if (a.length < 8 || a.length > (plugins ? 10 : 9))
-                    this.fail(node, "createAsset(asset, collection | null, authority | null, payer, owner | null, systemProgram, name, uri, plugins?, signerSeeds?)");
-                const metas = [
-                    this.mplMeta(a[0], core, "the asset", true, true),
-                    this.mplMeta(a[1], core, "the collection", true, false),
-                    this.mplMeta(a[2], core, "the collection authority", false, true),
-                    this.mplMeta(a[3], core, "the payer", true, true),
-                    this.mplMeta(a[4], core, "the owner", false, false),
-                    [p, false, false], // update authority: the collection's, or the payer by default
-                    this.mplMeta(a[5], core, "the system program", false, false),
-                    [p, false, false],
-                ];
-                const data = this.mplData(node, 2048, [{ bytes: [0, 0] }, str(a[6]), str(a[7]), ...this.corePluginList(plugins)]);
-                this.cpi(p, metas, data.buf, data.len, seedsAt(plugins ? 9 : 8));
-                return undefined;
-            }
-            case "createCollection": {
+        const list = op.plugins && isPlugins(a[op.args]) ? a[op.args] : undefined;
+        const seedsAt = op.args + (list ? 1 : 0);
+        if (op.plugins ? a.length < op.args || a.length > seedsAt + 1 : a.length !== op.args && a.length !== op.args + 1)
+            this.fail(node, op.usage(method));
+        const metas = op.metas.map((m) => (m === "self" ? [p, false, false] : this.mplMeta(a[m[0]], core, m[1], m[2], m[3])));
+        const data = this.mplData(node, op.max, op.data(a, list));
+        this.cpi(p, metas, data.buf, data.len, a[seedsAt] ? this.signingSeeds(a[seedsAt]) : { name: "NULL", count: 0 });
+        return undefined;
+    }
+    /**
+     * Core instructions: `args` fixed arguments (then an optional plugin list when `plugins`, then optional signer
+     * seeds), accounts in order (`[argument, label, writable, signer]`, or "self": the Core program, Core's "none" for an
+     * optional account), at most `max` bytes of data.
+     */
+    coreOps() {
+        const str = (n) => ({ value: n, type: STRING });
+        const asset = [0, "the asset", true, false];
+        const assetPlugin = {
+            usage: (m) => `${m}(asset, collection | null, payer, authority | null, systemProgram, ${m === "removePlugin" ? "kind" : "plugin"}, signerSeeds?)`,
+            args: 6,
+            // Add/Remove/UpdatePluginV1: asset, collection, payer, authority, systemProgram, logWrapper.
+            metas: [
+                asset,
+                [1, "the collection", true, false],
+                [2, "the payer", true, true],
+                [3, "the authority", false, true],
+                [4, "the system program", false, false],
+                "self",
+            ],
+            max: 2048,
+        };
+        const collectionPlugin = {
+            usage: (m) => `${m}(collection, payer, authority | null, systemProgram, ${m === "removeCollectionPlugin" ? "kind" : "plugin"}, signerSeeds?)`,
+            args: 5,
+            // Add/Remove/UpdateCollectionPluginV1: collection, payer, authority, systemProgram, logWrapper.
+            metas: [
+                [0, "the collection", true, false],
+                [1, "the payer", true, true],
+                [2, "the authority", false, true],
+                [3, "the system program", false, false],
+                "self",
+            ],
+            max: 2048,
+        };
+        const assetPluginOp = (method, disc) => ({
+            ...assetPlugin,
+            data: (a) => [
+                { bytes: [disc] },
+                ...(method === "removePlugin" ? [this.corePluginType(a[5])] : this.corePlugin(a[5], method === "addPlugin")),
+            ],
+        });
+        const collectionPluginOp = (method, disc) => ({
+            ...collectionPlugin,
+            data: (a) => [
+                { bytes: [disc] },
+                ...(method === "removeCollectionPlugin" ? [this.corePluginType(a[4])] : this.corePlugin(a[4], method === "addCollectionPlugin")),
+            ],
+        });
+        // Add/RemoveExternalPluginAdapterV1: asset, collection, payer, authority, systemProgram, logWrapper; the write has a
+        // buffer account (left out: the data is in the instruction) before systemProgram. The Collection forms drop the asset.
+        const external = (method, disc, collection) => {
+            const write = method.startsWith("write");
+            const add = method.startsWith("add");
+            const n = (collection ? 5 : 6) + (write ? 1 : 0);
+            const at = collection ? 4 : 5;
+            const head = collection ? "collection, payer, authority | null, systemProgram" : "asset, collection | null, payer, authority | null, systemProgram";
+            const metas = collection
+                ? [
+                    [0, "the collection", true, false],
+                    [1, "the payer", true, true],
+                    [2, "the authority", false, true],
+                ]
+                : [asset, [1, "the collection", true, false], [2, "the payer", true, true], [3, "the authority", false, true]];
+            if (write)
+                metas.push("self");
+            metas.push([collection ? 3 : 4, "the system program", false, false], "self");
+            return {
+                usage: (m) => `${m}(${head}, ${add ? "plugin" : write ? "key, data" : "key"}, signerSeeds?)`,
+                args: n,
+                metas,
+                max: 1024,
+                data: (a) => [
+                    { bytes: [disc] },
+                    ...(add
+                        ? this.coreExternalPlugin(a[at])
+                        : write
+                            ? [...this.coreExternalKey(a[at]), ...this.coreExternalData(a[at + 1])]
+                            : this.coreExternalKey(a[at])),
+                ],
+            };
+        };
+        return {
+            createAsset: {
+                usage: () => "createAsset(asset, collection | null, authority | null, payer, owner | null, systemProgram, name, uri, plugins?, signerSeeds?)",
+                args: 8,
+                plugins: true,
+                // CreateV1: asset, collection, authority, payer, owner, updateAuthority (the collection's, or the payer by
+                // default), systemProgram, logWrapper.
+                metas: [
+                    [0, "the asset", true, true],
+                    [1, "the collection", true, false],
+                    [2, "the collection authority", false, true],
+                    [3, "the payer", true, true],
+                    [4, "the owner", false, false],
+                    "self",
+                    [5, "the system program", false, false],
+                    "self",
+                ],
+                max: 2048,
+                data: (a, plugins) => [{ bytes: [0, 0] }, str(a[6]), str(a[7]), ...this.corePluginList(plugins)],
+            },
+            createCollection: {
+                usage: () => "createCollection(collection, updateAuthority | null, payer, systemProgram, name, uri, plugins?, signerSeeds?)",
+                args: 6,
+                plugins: true,
                 // CreateCollectionV1: collection, updateAuthority, payer, systemProgram.
-                const plugins = isPlugins(a[6]) ? a[6] : undefined;
-                if (a.length < 6 || a.length > (plugins ? 8 : 7))
-                    this.fail(node, "createCollection(collection, updateAuthority | null, payer, systemProgram, name, uri, plugins?, signerSeeds?)");
-                const metas = [
-                    this.mplMeta(a[0], core, "the collection", true, true),
-                    this.mplMeta(a[1], core, "the update authority", false, false),
-                    this.mplMeta(a[2], core, "the payer", true, true),
-                    this.mplMeta(a[3], core, "the system program", false, false),
-                ];
-                const data = this.mplData(node, 2048, [{ bytes: [1] }, str(a[4]), str(a[5]), ...this.corePluginList(plugins)]);
-                this.cpi(p, metas, data.buf, data.len, seedsAt(plugins ? 7 : 6));
-                return undefined;
-            }
-            case "addPlugin":
-            case "updatePlugin":
-            case "removePlugin": {
-                // Add/Remove/UpdatePluginV1: asset, collection, payer, authority, systemProgram, logWrapper.
-                const last = method === "removePlugin" ? "kind" : "plugin";
-                if (a.length !== 6 && a.length !== 7)
-                    this.fail(node, `${method}(asset, collection | null, payer, authority | null, systemProgram, ${last}, signerSeeds?)`);
-                const metas = [
-                    this.mplMeta(a[0], core, "the asset", true, false),
-                    this.mplMeta(a[1], core, "the collection", true, false),
-                    this.mplMeta(a[2], core, "the payer", true, true),
-                    this.mplMeta(a[3], core, "the authority", false, true),
-                    this.mplMeta(a[4], core, "the system program", false, false),
-                    self,
-                ];
-                const body = method === "removePlugin" ? [this.corePluginType(a[5])] : this.corePlugin(a[5], method === "addPlugin");
-                const data = this.mplData(node, 2048, [{ bytes: [{ addPlugin: 2, removePlugin: 4, updatePlugin: 6 }[method]] }, ...body]);
-                this.cpi(p, metas, data.buf, data.len, seedsAt(6));
-                return undefined;
-            }
-            case "addCollectionPlugin":
-            case "updateCollectionPlugin":
-            case "removeCollectionPlugin": {
-                // Add/Remove/UpdateCollectionPluginV1: collection, payer, authority, systemProgram, logWrapper.
-                const last = method === "removeCollectionPlugin" ? "kind" : "plugin";
-                if (a.length !== 5 && a.length !== 6)
-                    this.fail(node, `${method}(collection, payer, authority | null, systemProgram, ${last}, signerSeeds?)`);
-                const metas = [
-                    this.mplMeta(a[0], core, "the collection", true, false),
-                    this.mplMeta(a[1], core, "the payer", true, true),
-                    this.mplMeta(a[2], core, "the authority", false, true),
-                    this.mplMeta(a[3], core, "the system program", false, false),
-                    self,
-                ];
-                const body = method === "removeCollectionPlugin" ? [this.corePluginType(a[4])] : this.corePlugin(a[4], method === "addCollectionPlugin");
-                const data = this.mplData(node, 2048, [{ bytes: [{ addCollectionPlugin: 3, removeCollectionPlugin: 5, updateCollectionPlugin: 7 }[method]] }, ...body]);
-                this.cpi(p, metas, data.buf, data.len, seedsAt(5));
-                return undefined;
-            }
-            case "transferAsset": {
+                metas: [
+                    [0, "the collection", true, true],
+                    [1, "the update authority", false, false],
+                    [2, "the payer", true, true],
+                    [3, "the system program", false, false],
+                ],
+                max: 2048,
+                data: (a, plugins) => [{ bytes: [1] }, str(a[4]), str(a[5]), ...this.corePluginList(plugins)],
+            },
+            addPlugin: assetPluginOp("addPlugin", 2),
+            removePlugin: assetPluginOp("removePlugin", 4),
+            updatePlugin: assetPluginOp("updatePlugin", 6),
+            addCollectionPlugin: collectionPluginOp("addCollectionPlugin", 3),
+            removeCollectionPlugin: collectionPluginOp("removeCollectionPlugin", 5),
+            updateCollectionPlugin: collectionPluginOp("updateCollectionPlugin", 7),
+            transferAsset: {
+                usage: () => "transferAsset(asset, collection | null, payer, authority | null, newOwner, signerSeeds?)",
+                args: 5,
                 // TransferV1: asset, collection, payer, authority, newOwner, systemProgram, logWrapper.
-                if (a.length !== 5 && a.length !== 6)
-                    this.fail(node, "transferAsset(asset, collection | null, payer, authority | null, newOwner, signerSeeds?)");
-                const metas = [
-                    this.mplMeta(a[0], core, "the asset", true, false),
-                    this.mplMeta(a[1], core, "the collection", false, false),
-                    this.mplMeta(a[2], core, "the payer", true, true),
-                    this.mplMeta(a[3], core, "the authority", false, true),
-                    this.mplMeta(a[4], core, "the new owner", false, false),
-                    [p, false, false],
-                    [p, false, false],
-                ];
-                const data = this.mplData(node, 8, [{ bytes: [14, 0] }]);
-                this.cpi(p, metas, data.buf, data.len, seedsAt(5));
-                return undefined;
-            }
-            case "burnAsset": {
+                metas: [
+                    asset,
+                    [1, "the collection", false, false],
+                    [2, "the payer", true, true],
+                    [3, "the authority", false, true],
+                    [4, "the new owner", false, false],
+                    "self",
+                    "self",
+                ],
+                max: 8,
+                data: () => [{ bytes: [14, 0] }],
+            },
+            burnAsset: {
+                usage: () => "burnAsset(asset, collection | null, payer, authority | null, signerSeeds?)",
+                args: 4,
                 // BurnV1: asset, collection, payer, authority, systemProgram, logWrapper.
-                if (a.length !== 4 && a.length !== 5)
-                    this.fail(node, "burnAsset(asset, collection | null, payer, authority | null, signerSeeds?)");
-                const metas = [
-                    this.mplMeta(a[0], core, "the asset", true, false),
-                    this.mplMeta(a[1], core, "the collection", true, false),
-                    this.mplMeta(a[2], core, "the payer", true, true),
-                    this.mplMeta(a[3], core, "the authority", false, true),
-                    [p, false, false],
-                    [p, false, false],
-                ];
-                const data = this.mplData(node, 8, [{ bytes: [12, 0] }]);
-                this.cpi(p, metas, data.buf, data.len, seedsAt(4));
-                return undefined;
-            }
+                metas: [asset, [1, "the collection", true, false], [2, "the payer", true, true], [3, "the authority", false, true], "self", "self"],
+                max: 8,
+                data: () => [{ bytes: [12, 0] }],
+            },
+            addExternalPlugin: external("addExternalPlugin", 22, false),
+            removeExternalPlugin: external("removeExternalPlugin", 24, false),
+            writeExternalPluginData: external("writeExternalPluginData", 28, false),
+            addCollectionExternalPlugin: external("addCollectionExternalPlugin", 23, true),
+            removeCollectionExternalPlugin: external("removeCollectionExternalPlugin", 25, true),
+            writeCollectionExternalPluginData: external("writeCollectionExternalPluginData", 29, true),
+        };
+    }
+    /** The fields of a Core object literal (`{ kind: "AppData", … }`) by name. */
+    coreProps(node, what) {
+        let n = node;
+        while (ts.isParenthesizedExpression(n) || ts.isAsExpression(n) || ts.isSatisfiesExpression(n))
+            n = n.expression;
+        if (!ts.isObjectLiteralExpression(n))
+            this.fail(n, `${what} is an object literal: { kind: "…", … }`);
+        const props = new Map();
+        for (const q of n.properties) {
+            if (ts.isPropertyAssignment(q) && ts.isIdentifier(q.name))
+                props.set(q.name.text, q.initializer);
+            else if (ts.isShorthandPropertyAssignment(q))
+                props.set(q.name.text, q.name);
+            else
+                this.fail(q, "write the fields as name: value");
+        }
+        return props;
+    }
+    /** PluginAuthority: "none" | "owner" | "updateAuthority" (literals), or an address. */
+    coreAuthority(n) {
+        if (ts.isStringLiteral(n)) {
+            const i = ["none", "owner", "updateAuthority"].indexOf(n.text);
+            if (i < 0)
+                this.fail(n, 'an authority is "none", "owner", "updateAuthority" or a Pubkey');
+            return [{ bytes: [i] }];
+        }
+        return [{ bytes: [3] }, { value: n, type: PUBKEY }];
+    }
+    coreOption(n, inner) {
+        return n ? [{ bytes: [1] }, ...inner(n)] : [{ bytes: [0] }];
+    }
+    coreSchema(n) {
+        const i = ts.isStringLiteral(n) ? ["binary", "json", "msgpack"].indexOf(n.text) : -1;
+        if (i < 0)
+            this.fail(n, 'schema is "binary", "json" or "msgpack"');
+        return [{ bytes: [i] }];
+    }
+    /** Vec<(HookableLifecycleEvent, ExternalCheckResult)>: `[{ event: "transfer", canReject: true }, …]`. */
+    coreChecks(n, at) {
+        if (!n || !ts.isArrayLiteralExpression(n))
+            this.fail(n ?? at, 'checks is a list: [{ event: "transfer", canApprove: true, canReject: true }]');
+        const out = [{ bytes: [n.elements.length & 0xff, 0, 0, 0] }];
+        for (const e of n.elements) {
+            const p = this.coreProps(e, "a lifecycle check");
+            const ev = p.get("event");
+            const i = ev && ts.isStringLiteral(ev) ? ["create", "transfer", "burn", "update", "execute"].indexOf(ev.text) : -1;
+            if (i < 0)
+                this.fail(ev ?? e, 'event is "create", "transfer", "burn", "update" or "execute"');
+            let flags = 0;
+            for (const [k, bit] of [
+                ["canListen", 1],
+                ["canApprove", 2],
+                ["canReject", 4],
+            ]) {
+                const v = p.get(k);
+                if (v && v.kind !== ts.SyntaxKind.TrueKeyword && v.kind !== ts.SyntaxKind.FalseKeyword)
+                    this.fail(v, `${k} is true or false`);
+                if (v?.kind === ts.SyntaxKind.TrueKeyword)
+                    flags |= bit;
+            }
+            for (const k of p.keys())
+                if (!["event", "canListen", "canApprove", "canReject"].includes(k))
+                    this.fail(e, `a lifecycle check has event, canListen, canApprove and canReject, not ${k}`);
+            out.push({ bytes: [i, flags, 0, 0, 0] });
+        }
+        return out;
+    }
+    /** ExtraAccount: `{ kind: "address", address, isSigner?, isWritable? }` or a preconfigured one (`{ kind: "owner" }`, …). */
+    coreExtraAccount(n) {
+        const p = this.coreProps(n, "an extra account");
+        const kind = p.get("kind");
+        const kinds = ["program", "collection", "owner", "recipient", "asset", "customPda", "address"];
+        const i = kind && ts.isStringLiteral(kind) ? kinds.indexOf(kind.text) : -1;
+        if (i < 0 || i === 5)
+            this.fail(kind ?? n, 'an extra account is { kind: "address", address } or "program", "collection", "owner", "recipient", "asset"');
+        const flag = (k) => {
+            const v = p.get(k);
+            if (v && v.kind !== ts.SyntaxKind.TrueKeyword && v.kind !== ts.SyntaxKind.FalseKeyword)
+                this.fail(v, `${k} is true or false`);
+            return v?.kind === ts.SyntaxKind.TrueKeyword ? 1 : 0;
+        };
+        if (i === 6) {
+            const addr = p.get("address");
+            if (!addr)
+                this.fail(n, "an address extra account needs address");
+            return [{ bytes: [6] }, { value: addr, type: PUBKEY }, { bytes: [flag("isSigner"), flag("isWritable")] }];
+        }
+        return [{ bytes: [i, flag("isSigner"), flag("isWritable")] }];
+    }
+    /**
+     * ExternalPluginAdapterInitInfo from a literal: `{ kind: "AppData", dataAuthority, schema? }`, `{ kind: "Oracle",
+     * baseAddress, checks, resultsOffset?, baseAddressConfig? }`, `{ kind: "LifecycleHook", hookedProgram, checks,
+     * extraAccounts?, dataAuthority?, schema? }` and the Linked forms (collections); `authority?` is the plugin's own.
+     */
+    coreExternalPlugin(n) {
+        const p = this.coreProps(n, "a Core external plugin");
+        const kind = p.get("kind");
+        const kinds = ["LifecycleHook", "Oracle", "AppData", "LinkedLifecycleHook", "LinkedAppData"];
+        const i = kind && ts.isStringLiteral(kind) ? kinds.indexOf(kind.text) : -1;
+        if (i < 0)
+            this.fail(kind ?? n, `a Core external plugin is ${kinds.join(", ")}`);
+        const allowed = {
+            0: ["hookedProgram", "checks", "extraAccounts", "dataAuthority", "schema"],
+            1: ["baseAddress", "checks", "baseAddressConfig", "resultsOffset"],
+            2: ["dataAuthority", "schema"],
+            3: ["hookedProgram", "checks", "extraAccounts", "dataAuthority", "schema"],
+            4: ["dataAuthority", "schema"],
+        };
+        for (const k of p.keys())
+            if (k !== "kind" && k !== "authority" && !allowed[i].includes(k))
+                this.fail(n, `${kinds[i]} takes ${allowed[i].join(", ")} and authority, not ${k}`);
+        const need = (k) => p.get(k) ?? this.fail(n, `${kinds[i]} needs ${k}`);
+        const auth = this.coreOption(p.get("authority"), (x) => this.coreAuthority(x));
+        const schema = this.coreOption(p.get("schema"), (x) => this.coreSchema(x));
+        if (i === 2 || i === 4)
+            return [{ bytes: [i] }, ...this.coreAuthority(need("dataAuthority")), ...auth, ...schema];
+        if (i === 1) {
+            const offset = p.get("resultsOffset");
+            const off = !offset
+                ? [{ bytes: [0] }]
+                : ts.isStringLiteral(offset) && (offset.text === "none" || offset.text === "anchor")
+                    ? [{ bytes: [1, offset.text === "none" ? 0 : 1] }]
+                    : [{ bytes: [1, 2] }, { value: offset, type: U64 }];
+            return [
+                { bytes: [1] },
+                { value: need("baseAddress"), type: PUBKEY },
+                ...auth,
+                ...this.coreChecks(need("checks"), n),
+                ...this.coreOption(p.get("baseAddressConfig"), (x) => this.coreExtraAccount(x)),
+                ...off,
+            ];
+        }
+        const extras = p.get("extraAccounts");
+        if (extras && !ts.isArrayLiteralExpression(extras))
+            this.fail(extras, "extraAccounts is a list of extra accounts");
+        return [
+            { bytes: [i] },
+            { value: need("hookedProgram"), type: PUBKEY },
+            ...auth,
+            ...this.coreChecks(need("checks"), n),
+            ...(extras ? [{ bytes: [1, extras.elements.length & 0xff, 0, 0, 0] }, ...extras.elements.flatMap((e) => this.coreExtraAccount(e))] : [{ bytes: [0] }]),
+            ...this.coreOption(p.get("dataAuthority"), (x) => this.coreAuthority(x)),
+            ...schema,
+        ];
+    }
+    /** ExternalPluginAdapterKey: `{ kind: "AppData", dataAuthority }`, `{ kind: "Oracle", address }`, `{ kind: "LifecycleHook", address }`, … */
+    coreExternalKey(n) {
+        const p = this.coreProps(n, "a Core external plugin key");
+        const kind = p.get("kind");
+        const kinds = ["LifecycleHook", "Oracle", "AppData", "LinkedLifecycleHook", "LinkedAppData"];
+        const i = kind && ts.isStringLiteral(kind) ? kinds.indexOf(kind.text) : -1;
+        if (i < 0)
+            this.fail(kind ?? n, `a Core external plugin key is ${kinds.join(", ")}`);
+        if (i === 2 || i === 4)
+            return [{ bytes: [i] }, ...this.coreAuthority(p.get("dataAuthority") ?? this.fail(n, `${kinds[i]}'s key is its dataAuthority`))];
+        return [
+            { bytes: [i] },
+            { value: p.get("address") ?? this.fail(n, `${kinds[i]}'s key is its address (the oracle's base address or the hooked program)`), type: PUBKEY },
+        ];
+    }
+    /** The data written: Option<Vec<u8>> from a string, a Vec<u8> argument, or null (clears it). */
+    coreExternalData(n) {
+        if (n.kind === ts.SyntaxKind.NullKeyword)
+            return [{ bytes: [0] }];
+        const l = ts.isIdentifier(n) ? this.lookup(n.text) : undefined;
+        if (l?.type.kind === "vecArg") {
+            if (l.type.elem.kind !== "int" || l.type.elem.name !== "u8")
+                this.fail(n, "data is a string, a Vec<u8> argument or null");
+            const t = this.tmp("dl");
+            this.line(`uint32_t ${t} = (uint32_t)${l.c}.len;`);
+            return [{ bytes: [1] }, { c: `&${t}`, n: "4" }, { c: `${l.c}.ptr`, n: `(uint64_t)${t}` }];
         }
-        this.fail(node.expression, `Metaplex Core supports createAsset, createCollection, addPlugin, updatePlugin, removePlugin (and the Collection forms), transferAsset and burnAsset, not ${method}`);
+        return [{ bytes: [1] }, { value: n, type: STRING }];
     }
     /** PluginType (u8) from a kind string literal: removePlugin(…, "FreezeDelegate"). */
     corePluginType(n) {

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

@@ -32,17 +32,25 @@ export declare abstract class ExpressionEmitter extends StorageEmitter {
         text: string;
         arr?: undefined;
         n?: undefined;
+        only?: undefined;
     } | {
         text?: undefined;
         arr: string;
         n: number;
+        only?: undefined;
+    } | {
+        only: string;
+        text?: undefined;
     };
     /**
      * 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;
+    /** `${node}`'s text; `converted.yes` when it was made from a non-string value (new text, not a view of other text). */
+    protected toText(node: ts.Expression, converted?: {
+        yes: boolean;
+    }): string;
     /** C statement writing the decimal text of an integer into the TS_Str `out`. */
     protected textOfInt(name: IntName, c: string, out: string): string;
     /** `c ? a : b` on values: only the chosen branch runs (its checks and side effects included). */

package/dist/compiler/emit/expressions.js

@@ -128,7 +128,7 @@ export class ExpressionEmitter extends StorageEmitter {
         if (ts.isNonNullExpression(node)) {
             const v = this.expr(node.expression, hint && hint.kind !== "option" ? { kind: "option", inner: hint } : hint);
             if (v.type.kind !== "option")
-                this.fail(node, "! works on Option values; check optional accounts with `x !== null`");
+                this.fail(node, "! works on Option values and optional accounts (acct!.field); check other values with `x !== null`");
             return this.unwrap(v, node);
         }
         if (ts.isPropertyAccessExpression(node) && node.questionDotToken)
@@ -154,6 +154,8 @@ export class ExpressionEmitter extends StorageEmitter {
         if (ts.isTemplateExpression(node)) {
             // `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.only !== undefined)
+                return { c: pieces.only, type: STRING };
             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");
@@ -171,7 +173,7 @@ export class ExpressionEmitter extends StorageEmitter {
             const l = this.lookup(node.text);
             if (l) {
                 if (l.closure)
-                    this.fail(node, `"${node.text}" is a function: TypeSOL functions are called (${node.text}(…)), not passed around or stored`);
+                    this.fail(node, `"${node.text}" is a function: call it (${node.text}(…)), bind it with const, or pass it to a helper or list method; it cannot be stored or returned as a value`);
                 if (l.type.kind === "array")
                     this.fail(node, `"${node.text}" is an array; use .get(i)`);
                 if (l.type.kind === "vec")
@@ -204,7 +206,7 @@ export class ExpressionEmitter extends StorageEmitter {
             if (this.accounts.has(node.text))
                 this.fail(node, `"${node.text}" is an account; use ${node.text}.key for its address`);
             if (calleeName(node, this.model.helperDecls, this.checker) || this.model.helpers.has(node.text))
-                this.fail(node, `"${node.text}" is a function: TypeSOL functions are called (${node.text}(…)), not passed around or stored`);
+                this.fail(node, `"${node.text}" is a function: call it (${node.text}(…)), bind it with const, or pass it to a helper or list method; it cannot be stored or returned as a value`);
             this.fail(node, `unknown name "${node.text}"`);
         }
         if (ts.isPropertyAccessExpression(node))
@@ -455,16 +457,20 @@ export class ExpressionEmitter extends StorageEmitter {
                 lit(known);
             else {
                 const mark = this.lines.length;
-                const c = this.toText(span.expression);
+                const converted = { yes: false };
+                const c = this.toText(span.expression, converted);
                 for (const p of parts)
                     if (p.c !== undefined)
                         p.c = this.settle({ c: p.c, type: STRING }, mark).c;
-                parts.push({ c });
+                parts.push({ c, converted: converted.yes });
             }
             lit(span.literal.text);
         }
         if (parts.every((p) => p.text !== undefined))
             return { text: parts.map((p) => p.text).join("") };
+        // `${n}` alone: the text a conversion just made (or a constant one) is already a string of its own; no join.
+        if (parts.length === 1 && parts[0].converted)
+            return { only: parts[0].c };
         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(", ")}};`);
@@ -494,10 +500,13 @@ export class ExpressionEmitter extends StorageEmitter {
         }
         return undefined;
     }
-    toText(node) {
+    /** `${node}`'s text; `converted.yes` when it was made from a non-string value (new text, not a view of other text). */
+    toText(node, converted) {
         const v = this.expr(node);
         if (v.type.kind === "string")
             return v.c;
+        if (converted)
+            converted.yes = true;
         if (v.type.kind === "option" && (v.type.inner.kind === "int" || v.type.inner.kind === "bool")) {
             // `${opt}`: the value, or "null" like JS.
             const inner = v.type.inner;
@@ -557,12 +566,7 @@ export class ExpressionEmitter extends StorageEmitter {
             (ts.isBigIntLiteral(node.whenFalse) || ts.isPrefixUnaryExpression(node.whenFalse));
         if (!type && !bothLiteral && (ts.isBigIntLiteral(node.whenTrue) || node.whenTrue.kind === ts.SyntaxKind.NullKeyword)) {
             // Type the non-literal branch first, without emitting it, to give the literal its type.
-            const saved = { lines: this.lines.length, hoisted: this.hoisted.length, temp: this.temp, diagnostics: this.reporter.diagnostics.length };
-            const probe = this.reporter.guard(() => this.expr(node.whenFalse));
-            this.lines.length = saved.lines;
-            this.hoisted.length = saved.hoisted; // a probed helper call may hoist declarations
-            this.temp = saved.temp;
-            this.reporter.diagnostics.length = saved.diagnostics;
+            const probe = this.probe(() => this.expr(node.whenFalse));
             if (probe && probe.literal === undefined && !probe.isNull)
                 type = probe.type;
         }