@typesol/cli 0.25.0 → 0.27.0

package/CHANGELOG.md

@@ -6,6 +6,45 @@ codes, and says so here.
 
 ## Unreleased
 
+## 0.27.0 — 2026-10-29
+
+Anchor 1.0 parity: instruction introspection, `Dup<…>` and account migration. Existing programs compile to the same
+binaries as in 0.26.0.
+
+- New: instruction introspection. `InstructionsSysvar` has `length`, `currentIndex()` and `get(i)`, a
+  `TransactionInstruction` with `programId`, its accounts (key, signer, writable), its data
+  (`readU8/U16/U32/U64/readPubkey`) and `is(program, "name")` (an instruction by its Anchor discriminator); every read
+  is bounds-checked (5104). `stackHeight()` is 1 at the top level, more under a CPI.
+- New: `Dup<…>`, Anchor's `dup`: a writable parameter that may be the same account as another, for accounts read and
+  written in place (not created, closed, a close destination or `@layout borsh`, which are refused at compile time).
+- New: `Migrate<From, To>`, Anchor 1.0's `Migration`: an existing account rewritten from one struct to another with
+  `acct.migrate(payer, value)`, the old data readable through `acct.from` until then (the new value is built before
+  the bytes are rewritten), the new through `acct.to` after; resized with the payer topping up rent. For now:
+  fixed-layout structs without growable Vecs, no constraints on the account, and it cannot be passed to a helper.
+- New: `/** @discriminator … */` on an account struct (a sha256 preimage such as `account:Counter`, or 0x and 8
+  bytes), Anchor's `#[account(discriminator = …)]`: keeps an old type's on-chain discriminator under a new name.
+
+## 0.26.0 — 2026-10-29
+
+A first-run experience pass, the security model and audit package, and more fuzzing. The compiler's output is the
+same as 0.25.0 for every program.
+
+- New: `typesol doctor` checks Node.js, the platform-tools, the Solana CLI, its keypair, the RPC and the keypair's
+  balance there, and the project, and prints the command that fixes each problem (exit 1 when building is impossible).
+- `typesol init` prints the files it creates relative to where it runs, warns with the install commands when the
+  platform-tools are missing, and lists the next steps.
+- `typesol deploy` checks, before sending anything, that the RPC answers (else: start `solana-test-validator`, or
+  `--url devnet`) and that the payer can pay the rent (else: how much, and the `solana airdrop` command on devnet or a
+  local validator). RPC URLs in these messages show only the host.
+- Docs: [security model](docs/security-model.md) (the guarantees a compiled program can rely on, trust boundaries,
+  what is left to the author) and [audit package](docs/audit.md) (scope, priorities, earlier reviews, evidence);
+  README: deploying on devnet and on a local validator.
+- Tests: `test/verification/fuzz-layout.test.ts`, model-based fuzzing of an account with two growable Vecs and of
+  `loadAccountMut` aliasing through remaining accounts (also in `pnpm fuzz`).
+- Repository: tests grouped by subject under `test/`, the Anchor twins in `test/anchor-twins` (`pnpm build:twins`),
+  the generators and chain tooling in `src/tools/` (the package's import paths are unchanged); Dependabot for npm and
+  GitHub Actions.
+
 ## 0.25.0 — 2026-10-29
 
 Security review (October 2026) fixes, and error codes aligned with Anchor. Some refused transactions now report a

package/README.md

@@ -149,9 +149,20 @@ npx @typesol/cli init my-app --name counter   # typesol.json, programs/counter.t
 cd my-app && npm install
 npm test                                      # builds the program and runs it in LiteSVM, an in-process Solana runtime
 npx typesol build                             # target/counter/{counter.so, counter.json (IDL), counter.client.ts, counter.build.json}
-npx typesol deploy --url http://127.0.0.1:8899 --keypair ~/.config/solana/id.json
 ```
 
+`npx typesol doctor` checks all of this (Node.js, platform-tools, Solana CLI, keypair, RPC) and prints the command
+that fixes anything missing. To deploy, on devnet:
+
+```sh
+solana-keygen new                             # once, if you have no keypair (~/.config/solana/id.json)
+solana airdrop 2 --url devnet                 # test SOL for the rent (rate-limited: https://faucet.solana.com also works)
+npx typesol deploy --url devnet
+```
+
+or on a local validator: `solana-test-validator` in another terminal, `solana airdrop 5 --url localhost`, then
+`npx typesol deploy --url localhost`. `deploy` checks the RPC and the payer's balance before sending anything.
+
 `--template vault` or `--template escrow` starts from a SOL vault or an SPL token escrow instead of the counter, each
 with a passing LiteSVM test.
 
@@ -262,23 +273,28 @@ units are not a safety claim. The differential tests also run the escrow against
 ### On mainnet
 
 The official escrow ([tokens/escrow](https://github.com/solana-developers/program-examples/tree/de090195e4de698e150572c4f886c333323a64a5/tokens/escrow)),
-deployed to Solana mainnet-beta in all four versions on 2026-10-27 and called with the same mints, amounts and accounts,
-one instruction per transaction. Each figure is the compute units of that transaction, linked to Solscan; the lowest per row is in bold. The deployed
-programs match these builds byte for byte (`typesol verify` for TypeSOL), and the TypeSOL program's IDL is published
-on chain with `typesol idl publish`.
+deployed to Solana mainnet-beta in all four versions and called with the same mints, amounts and accounts, one
+instruction per transaction. The TypeSOL program was upgraded in place to 0.25.0 on 2026-10-29; the others are as first
+deployed on 2026-10-27. Each figure is the compute units of that transaction, linked to Solscan; the lowest per row is
+in bold. The deployed programs match these builds byte for byte (`typesol verify` for TypeSOL), and the TypeSOL
+program's IDL is published on chain with `typesol idl publish`.
 
 | Transaction | TypeSOL | Pinocchio | Native Rust | Anchor |
 | --- | ---: | ---: | ---: | ---: |
-| make_offer (offer 1) | [20,304](https://solscan.io/tx/32PVva77dT1rSWrMWX2sHTMPZiwztdEZYtpANaxrsuJxPcd3hnV6pDgJJaV4LkL3bX6ALDoHMNF8fjngtodYHBS1) | [**19,645**](https://solscan.io/tx/528BdMTrnLWauSXVh2vaFfy4XwKFpbyt95hQ6w3fwjtpkT85RPkRhGydunAizNDRqTTLPxcEVMrdcDvRer4H9LRE) | [30,698](https://solscan.io/tx/4MQgt75MvojaAkfxnvrE2yJWabGpE8bsZhNq2CeGJxHZg6uD6A64Kv71JmrsgiGnaEovvv8K34DYL49owLjhs4QJ) | [38,648](https://solscan.io/tx/9T1ZY9JaSMb1GMqv1i22AuZuJQN6B5XcgqeDv5tGqEm5Uox3MBTdXsECt59GwcXkFG9QKgXJyqndTEzpSXhbAVM) |
-| take_offer (offer 1) | [**7,998**](https://solscan.io/tx/49EQwgnKShFdsAs37AEzYmv6tLY8DipcCjmRgqwj4fVTFEgVVWdEXw5AvuEufL5ymJYs4T4hVFdkENW9XK9een5m) | [25,206](https://solscan.io/tx/21MGkXpKRe4c7EeA1hC6JHevsk78xUdbcWmyqG47EbLeCNKSMTzTjkJQqtydnQmV8uHPmr6bJHnvQmmQTSZB7Am2) | [28,612](https://solscan.io/tx/B1hu1EL4Y5vWhBVWdyZEpzRNJb8kd6G9CgN7KtyNNGpQ84o9dfn1sdy9Z1UCHECNtp24Mw8bEH2iYz2YADdEUjx) | [32,835](https://solscan.io/tx/3ZLuQQz7Bx5YdgmFXpVQWHn5kyc8v39jr2BnfofH6sqenzfJpAdVm4h38uYcHwYygnfso92kJe7HRHeASsABoKPQ) |
-| make_offer (offer 2) | [21,804](https://solscan.io/tx/xuu9KXbZvzGDpTEEcDE9LYvBqmPen81y6ty92e6crRxT8m4Mc4XyxhjWHbjVNsr9RE3QY4M1j1Sw9cH7PRMKKuc) | [**19,645**](https://solscan.io/tx/LLzS13AJrqACGoT1VHZN278ij39pNkttb1Z4Wh2AYXknWxwjaiaiMeD7WZomjP6TBv18RHfQHUfogQzApvXr2mC) | [35,198](https://solscan.io/tx/4xiKfzyccVatef1T52tZ3VAJwcx5R7iWgHWezBzZ3p2WpvoLzMp1PSUgr7x3sspE53mDE5JaghaNPKuUohVgPuwc) | [47,648](https://solscan.io/tx/4mxW8D5zpY8t4fL8JRbvhp6ejU6CUvB3iWmFjACipzexW6tZfFeatfnEnDTX3Y97BxsvAftoX9eQauiVu84xrLxh) |
-| refund_offer (offer 2) | [**5,961**](https://solscan.io/tx/4kY7s3y95Lrd2WGCWGPWW3zFBVtEKH6EskdscuYmRCRRgPt2rJTZ1CmZMGUUkHs7aai9AygEiTSUG23EMUrFr7rg) | [13,387](https://solscan.io/tx/QUXWwdbKRcT6WhZvSe4U8nxr4GAMaPNV6pZ1fwrC28kRxdJm7HKXVr2DFRuKD9bEzoS6hFdiA2rLr1mQWyrN3oz) | [17,731](https://solscan.io/tx/5zj7E4c61j1JzUsUPC1fNs9ECFLVmCug9rsdYsVLn7YD1RSxdbAJUQDam1BX3epTzW6ed2uFGwTiNhwaYo7vqdwm) | [23,576](https://solscan.io/tx/5Kjwnq5tN8mzj5s67VGxSry4kRzZk6HLdgXW65FyTvpUeC1D7aQoDGTwzrA7kqyYEvV9y9znnZmLaqU98zFrJJo4) |
+| make_offer (offer 1) | [29,205](https://solscan.io/tx/4AaenpnDGYmT2JXAm8HuN5D9GkEWLYeqyMNxJq6D9aYk6ssunSwNTigFmZoCJtY7MZ3FFBXLsig8jo1YmjUFVTpX) | [**21,145**](https://solscan.io/tx/3tWjcMQxTja6QjEmAvi1MRF9qCsnPBsAmQNPnd5RcNTwnkkJYmk9JFFnZoJbTAc6MEr2QYQd7KtgPGtaNr3inrCG) | [45,698](https://solscan.io/tx/4AgQzePrXL4f4qYrFQBzE65d8cszpmqSiQVt9yVsAotbrYTnartXuM2g2PFg7VhUGaZpbhfH9jzXgwXdRLXwB7tk) | [38,648](https://solscan.io/tx/4Hm62foYd5hoNqmEfLk51HhVVb5VHa5oTr81rjAKNNXyKFYwSrpXZhzFVwbk3WxRzEsiqGxHbn7B4eBop6RC1Sgx) |
+| take_offer (offer 1) | [**9,951**](https://solscan.io/tx/52ej6M3zFt5kgMGKUef9VGZdmZWqJdSoHCvCEB9P3btg7DSbvHkM24uk95W7HXjSX12XHmEmXATC7GLcQQ1U22kK) | [26,706](https://solscan.io/tx/4KLfVqTM2KmwgqF4xECWmNuZWYufsWcocdT5saamWdZQfRYhY7aTsyEyk5pVTxug6LJnngJhWDU7NMiPnZxu9sH2) | [31,628](https://solscan.io/tx/5f2VxEcPUfZbCVHpbYbUntVwfUN4k6ieetxSjdpJVwfck2tDuv2QTGbFFtNcy34Nn8d6bKSp5efzKDSbg7xj5TbJ) | [32,835](https://solscan.io/tx/3sJVTUvGRRtvYisFyqthvYQUZpeLmNN2UtXJq9TsQHW2TLP8YwtiuFGoPvu51w5YoZyJjKc3dM3zF6JXTFRFjc6H) |
+| make_offer (offer 2) | [20,205](https://solscan.io/tx/36mSJoMESxSLoxL5apVkoPzptAgFmUM9z2ZVuKpCadQajxbTF3T6BT93bw2ugHfLX7qSXvcBQ96kd8m22y3DsbTH) | [**19,645**](https://solscan.io/tx/PXPGNGCN3RN15L812K9Ho99Xz5YmUgMDaDy8aXuSg1kFgtdX42Z6foLLJkn8X9XB68xgeQsTBQhoDdUfRPKks2f) | [29,198](https://solscan.io/tx/2n38Urd1FsijNB2kbQy1b2cNHrvU7sXwYe5zH9SeyZUJRhUaD8TXSJGkvjEGYCTy3bdmAvEqqE27Ufgcxg3S3uFe) | [38,648](https://solscan.io/tx/185ZpYg3H1Ku4upHPBoBavrTczwzwxQiz7wjqqYWXd8MmxbimbLz7VvjuQdnqAGaAMy11G8M1QqPzXbrPof8gQb) |
+| refund_offer (offer 2) | [**5,478**](https://solscan.io/tx/55Q7pTfsew4F4N9DPB21BEqeHPANhkgQmUGAYVerFP73D7qMTp4eeo5CPMpYQqU7SLS4e49fuKtLkZ9XowbyoKET) | [13,387](https://solscan.io/tx/2cNkvA4xuFJBQzFcFTnLrxRzDU1q5617T8TCF5sBS7JeNzCPUxCPfzS37uv1RUg7xs9Mqyya6KDV9GSZxGiToevT) | [17,731](https://solscan.io/tx/Nj8RGLqEgbj8SEhd9hLcB2JQJY7YwkP1CnMdeJFBdsFhftntFqm1j1wAD1Mc715wrkPv2pFCWu93AF29oHQUDYr) | [20,576](https://solscan.io/tx/5on9Fxe6mADcbWwVn43yQ5wYtdWyx2u3Ry2hSniLJjRqoj2J55Hbgv4AbZoVZ5CDp2VrrghEkKRBvmXxjv1TynmY) |
+| escrow program's own part, 4 transactions | **28,118** | 36,956 | 93,273 | 102,926 |
 | program | [65ybkcg6…](https://solscan.io/account/65ybkcg6mQa9t5EuHtirRdvf2qAu12qRiK6wYBbGk16P) | [FrQwq3iU…](https://solscan.io/account/FrQwq3iUa8ZkWEne1y27webXTAyLgH4Hj6t986t6VS2G) | [5pnmi1Md…](https://solscan.io/account/5pnmi1MdxzXKmgX7ooRSE212rzZK8rb7nNpRTSMqP8V1) | [EG7M3sLL…](https://solscan.io/account/EG7M3sLLwB7MhmtzwYsaxbhZaFDbshL9hmVK79bQVyVq) |
 
-Most of make_offer is the Associated Token Account program creating the vault (about 13,500 CU in every version); it
-searches for the vault address's bump itself at 1,500 CU a try, which is why TypeSOL's offer 2 cost 1,500 more than
-offer 1 (its own part was 6,719 CU both times). The Pinocchio version takes the offer PDA's bump from the client instead
-of searching for it (its own part: 6,051 CU). Mainnet figures differ from the LiteSVM means above.
+Most of make_offer is the Associated Token Account program creating the vault. It searches for the vault address's
+bump itself at 1,500 CU a try, and every offer has its own vault, so that part varies from offer to offer in every
+version (13,585 to 22,585 CU of the make_offers above); programs that check the vault's address re-derive it, so
+take_offer and refund_offer vary with it too. The escrow program's own part is steadier: TypeSOL's make_offer spent
+6,620 CU of its own on both offers. The Pinocchio version takes the offer PDA's bump from the client instead of
+searching for it. Mainnet figures differ from the LiteSVM means above. Every run, including the one before the
+upgrade, is in [typesol/benchmarks](https://github.com/typesol/benchmarks) (`results/`).
 
 ## How it is tested
 
@@ -316,7 +332,9 @@ change.
 - The compiler, runtime and tooling have been through internal security reviews and are covered by the tests above.
 - They have **not been audited by an independent firm**. Do not put significant value behind programs built with
   TypeSOL until such an audit is published.
-- Audit your own programs as you would any Solana program.
+- Audit your own programs as you would any Solana program. What a compiled program can rely on, and what is left to
+  you, is in [docs/security-model.md](docs/security-model.md); [docs/audit.md](docs/audit.md) is the package for an
+  external audit.
 - Report vulnerabilities as described in [SECURITY.md](SECURITY.md).
 
 Not supported yet: see the end of [docs/language.md](docs/language.md#not-supported-yet).

package/SECURITY.md

@@ -9,6 +9,8 @@ TypeSOL generates programs that hold funds. Treat it accordingly.
   firm.** Do not put significant value behind programs built with it until an external audit of the compiler and
   runtime is published, and audit your own programs as you would any Solana program.
 - Only the latest 0.x release receives security fixes.
+- What a compiled program can rely on is specified in [docs/security-model.md](docs/security-model.md); the package
+  for an external audit is [docs/audit.md](docs/audit.md).
 
 ## Reporting a vulnerability
 

package/dist/cli.js

@@ -7,14 +7,15 @@ import { fileURLToPath } from "node:url";
 import { parseArgs } from "node:util";
 import ts from "typescript";
 import { build, CompileError, COMPILER_VERSION, generate, SBPF_VERSIONS, verifyBinary } from "./compiler/index.js";
-import { generateCpi } from "./cpigen.js";
-import { generatePort } from "./portgen.js";
-import { generateClient, writeClient } from "./clientgen.js";
+import { generateCpi } from "./tools/cpigen.js";
+import { generatePort } from "./tools/portgen.js";
+import { generateClient, writeClient } from "./tools/clientgen.js";
 import { buildIdl } from "./compiler/idl.js";
 import { decodeAddress, loadOrCreateKeypair, readKeypair } from "./keys.js";
-import { formatProfile, profileLogs } from "./profile.js";
+import { formatProfile, profileLogs } from "./tools/profile.js";
 import { TEMPLATE_NAMES } from "./templates.js";
 import { buildWorkspace, CONFIG, deployArgs, findWorkspace, programAddress, programForEntry, programPaths, scaffold } from "./workspace.js";
+import { clusterUrl, deployPreflight, doctorChecks, formatChecks, INSTALL_AGAVE, solanaConfig as readSolanaConfig, toolchainCheck } from "./tools/doctor.js";
 const ASSETS = fileURLToPath(new URL("../assets/", import.meta.url));
 /** A usage problem: printed with the command's help, exit code 2. */
 class UsageError extends Error {
@@ -65,9 +66,18 @@ const COMMANDS = {
                 .replace(/^_+|_+$/g, "")
                 .toLowerCase();
             const name = v.name ?? (/^[a-z]/.test(derived) ? derived : `p_${derived || "program"}`);
+            const rel = path.relative(process.cwd(), root) || ".";
             for (const f of scaffold(root, name, template))
-                log(`  created ${path.join(root, f)}`);
-            log(`\n  next: cd ${path.relative(process.cwd(), root) || "."} && npm install && npm test`);
+                log(`  created ${path.join(rel, f)}`);
+            const tools = toolchainCheck();
+            if (!tools.ok)
+                log(`\n  ! The Solana platform-tools are not installed yet; npm test compiles with them. Install once:\n` +
+                    (tools.fix ?? []).map((f) => `      ${f}`).join("\n"));
+            log(`\n  next:\n` +
+                (rel === "." ? "" : `    cd ${rel}\n`) +
+                `    npm install\n` +
+                `    npm test             # builds ${name} and runs its test in LiteSVM, a Solana runtime in-process\n` +
+                `    npx typesol doctor   # checks the toolchain, keypair and RPC before a deploy`);
             return 0;
         },
     },
@@ -166,6 +176,20 @@ const COMMANDS = {
             return 0;
         },
     },
+    doctor: {
+        usage: "typesol doctor [--url <rpc>] [--config <solana cli config>]",
+        help: [
+            "Check what building, testing and deploying need: Node.js, the platform-tools, the Solana CLI, its keypair, the RPC",
+            "(and the keypair's balance there) and the project. Each problem comes with the command that fixes it. Exit code 1",
+            "when building is impossible (Node.js or the platform-tools); a missing deploy piece is a warning.",
+        ].join("\n  "),
+        options: { url: { type: "string" }, config: { type: "string" } },
+        async run(v) {
+            const checks = await doctorChecks({ cwd: process.cwd(), url: v.url, config: v.config });
+            log(formatChecks(checks));
+            return checks.some((c) => !c.ok && !c.optional) ? 1 : 0;
+        },
+    },
     deploy: {
         usage: "typesol deploy [<program>…] [--url <rpc>] [--keypair <payer.json>] [--config <solana cli config>] [--sbpf v0|v1|v2] [--dry-run]",
         help: [
@@ -174,9 +198,20 @@ const COMMANDS = {
             "Needs the Agave CLI (`solana`) on PATH.",
         ].join("\n  "),
         options: { url: { type: "string" }, keypair: { type: "string" }, config: { type: "string" }, "dry-run": { type: "boolean" }, sbpf: { type: "string" } },
-        run(v, args) {
+        async run(v, args) {
             const ws = needWorkspace("deploy");
             const built = buildWorkspace(ws, names(ws, args), { sbpf: sbpfOf(v) });
+            if (!v["dry-run"]) {
+                // Before any transaction: the RPC answers and the payer can afford it, with what to do if not.
+                const cfg = solanaConfig(v.config);
+                const url = v.url ?? cfg.url;
+                if (url)
+                    await deployPreflight({
+                        url: clusterUrl(url),
+                        payer: v.keypair ?? cfg.keypair ?? path.join(os.homedir(), ".config/solana/id.json"),
+                        programs: built.map((b) => ({ soPath: b.result.soPath, address: b.address, name: b.paths.name })),
+                    });
+            }
             for (const b of built) {
                 const cliArgs = deployArgs(b.result.soPath, b.paths.keypair, { url: v.url, payer: v.keypair, config: v.config });
                 if (v["dry-run"]) {
@@ -189,7 +224,7 @@ const COMMANDS = {
                 }
                 catch (e) {
                     if (e.code === "ENOENT")
-                        throw new Error("`solana` was not found on PATH. Install the Agave CLI: https://docs.anza.xyz/cli/install");
+                        throw new Error(`\`solana\` was not found on PATH. Install the Agave CLI: ${INSTALL_AGAVE}`);
                     throw new Error(`solana program deploy failed for ${b.paths.name} (see its output above)`);
                 }
             }
@@ -217,7 +252,7 @@ const COMMANDS = {
                 throw new Error(`no signer keypair${keyFile ? ` at ${keyFile}` : ""}: pass --keypair, or set keypair_path in the Solana CLI config`);
             // Loaded only here: the other commands do not need an RPC client.
             const kit = await import("@solana/kit");
-            const { publishIdl, rpcChain } = await import("./idlpublish.js");
+            const { publishIdl, rpcChain } = await import("./tools/idlpublish.js");
             const signer = await kit.createKeyPairSignerFromBytes(readKeypair(keyFile));
             const chain = rpcChain(kit.createSolanaRpc(clusterUrl(rpcUrl)));
             for (const name of names(ws, args)) {
@@ -297,7 +332,7 @@ const COMMANDS = {
                     throw new Error("no RPC: pass --url, or set json_rpc_url in the Solana CLI config");
                 // Loaded only here: the other commands do not need an RPC client.
                 const kit = await import("@solana/kit");
-                const { fetchProgramIdl } = await import("./idlpublish.js");
+                const { fetchProgramIdl } = await import("./tools/idlpublish.js");
                 const found = await fetchProgramIdl(kit.createSolanaRpc(clusterUrl(rpcUrl)), kit.address(v.address));
                 console.error(`  IDL from ${found.source === "anchor" ? "Anchor's IDL account" : "the Program Metadata program"}`);
                 idl = found.idl;
@@ -360,7 +395,7 @@ const COMMANDS = {
                     throw new Error("no RPC: pass --url, or set json_rpc_url in the Solana CLI config");
                 // Loaded only here: the other commands do not need an RPC client.
                 const kit = await import("@solana/kit");
-                const { fetchDeployed } = await import("./onchain.js");
+                const { fetchDeployed } = await import("./tools/onchain.js");
                 const rpc = kit.createSolanaRpc(clusterUrl(rpcUrl));
                 const info = await fetchDeployed(rpc, address);
                 onChain = { address, info, rpc };
@@ -387,8 +422,8 @@ const COMMANDS = {
                 return same ? 0 : 3;
             const { info } = onChain;
             log(`  authority ${info.authority ?? "none: the program is immutable"}${info.slot !== undefined ? `; last deployed in slot ${info.slot}` : ""}`);
-            const { fetchIdl, metadataAddress } = await import("./idlpublish.js");
-            const { canonicalJson } = await import("./onchain.js");
+            const { fetchIdl, metadataAddress } = await import("./tools/idlpublish.js");
+            const { canonicalJson } = await import("./tools/onchain.js");
             // No canonical metadata account means nothing was published; one that cannot be read is an error, not "none".
             const at = await metadataAddress(onChain.address, null);
             const exists = (await onChain.rpc.getAccountInfo(at, { encoding: "base64" }).send()).value !== null;
@@ -492,32 +527,12 @@ function overrideFile(file, text) {
         sys.fileExists = fileExists;
     };
 }
-/** The Solana CLI's cluster monikers, as `solana --url` accepts them; anything else is used as given. */
-function clusterUrl(url) {
-    const monikers = {
-        "mainnet-beta": "https://api.mainnet-beta.solana.com",
-        m: "https://api.mainnet-beta.solana.com",
-        devnet: "https://api.devnet.solana.com",
-        d: "https://api.devnet.solana.com",
-        testnet: "https://api.testnet.solana.com",
-        t: "https://api.testnet.solana.com",
-        localhost: "http://127.0.0.1:8899",
-        l: "http://127.0.0.1:8899",
-    };
-    return monikers[url] ?? url;
-}
 /** json_rpc_url / keypair_path from a Solana CLI config (the given file, or the CLI's default one). */
 function solanaConfig(file) {
-    const configPath = file ?? path.join(os.homedir(), ".config/solana/cli/config.yml");
-    if (!existsSync(configPath)) {
-        if (file)
-            throw new UsageError(`${file} does not exist`);
-        return {};
-    }
-    const text = readFileSync(configPath, "utf8");
-    const get = (k) => new RegExp(`^${k}:\\s*["']?([^"'\\n]+?)["']?\\s*$`, "m").exec(text)?.[1];
-    const expand = (p) => (p?.startsWith("~/") ? path.join(os.homedir(), p.slice(2)) : p);
-    return { url: get("json_rpc_url"), keypair: expand(get("keypair_path")) };
+    const cfg = readSolanaConfig(file);
+    if (file && !cfg.exists)
+        throw new UsageError(`${file} does not exist`);
+    return { url: cfg.url, keypair: cfg.keypair };
 }
 export async function main(argv) {
     const [cmd, ...rest] = argv;

package/dist/compiler/analyze.js

@@ -85,6 +85,8 @@ const TYPE_EXPORTS = new Set([
     "Ata",
     "Owner",
     "Executable",
+    "Dup",
+    "Migrate",
     "Optional",
     "EventAuthority",
     "MplCoreProgram",
@@ -114,6 +116,22 @@ export function snakeCase(name) {
         .replace(/([A-Z])([A-Z][a-z])/g, "$1_$2")
         .toLowerCase();
 }
+/**
+ * An account struct's discriminator: Anchor's sha256("account:<Name>")[..8], or the one a `/** @discriminator … *\/` tag
+ * gives (a sha256 preimage such as `account:Counter`, or 0x and 8 bytes), e.g. for an old version of a struct kept under
+ * a new name for Migrate<From, To>.
+ */
+function accountDiscriminator(decl, name, reporter) {
+    const tag = ts.getJSDocTags(decl).find((t) => t.tagName.text === "discriminator");
+    if (!tag)
+        return discriminator(`account:${name}`);
+    const text = (typeof tag.comment === "string" ? tag.comment : (ts.getTextOfJSDocComment(tag.comment) ?? "")).trim();
+    if (/^0x([0-9a-fA-F]{2}){8}$/.test(text))
+        return [...Buffer.from(text.slice(2), "hex")];
+    if (text && !text.startsWith("0x"))
+        return discriminator(text);
+    reporter.fail(decl, "@discriminator on an account struct needs a sha256 preimage (account:<Name>) or 0x and 8 bytes");
+}
 export function discriminator(preimage) {
     return [...createHash("sha256").update(preimage).digest().subarray(0, 8)];
 }
@@ -601,12 +619,17 @@ export function analyze(entry) {
         // A returned struct goes out in its fixed layout, like an argument comes in: it cannot also be a Borsh event.
         if (ix.returns?.kind === "struct")
             collectStructs(ix.returns, structs, dataEnums, argStructs);
-        for (const a of ix.accounts)
+        for (const a of ix.accounts) {
+            if (a.kind.kind === "migrate") {
+                accountStructs.add(a.kind.from.name);
+                accountStructs.add(a.kind.to.name);
+            }
             if (a.kind.kind === "account" || a.kind.kind === "init" || a.kind.kind === "zeroed" || a.kind.kind === "initIfNeeded") {
                 accountStructs.add(a.kind.struct.name);
                 if (a.kind.struct.viewsOnly)
                     reporter.error(a.node, `${a.kind.struct.name} holds a string (or an enum carrying one), so it is an argument, return value or event; account data uses FixedString<N>`);
             }
+        }
     }
     // Arguments are Borsh, where a FixedVec is a Vec (only what it holds). A struct passed as a whole argument and used
     // nowhere else (not account data, not nested, not returned) is read as Anchor sends it: @layout borsh, implied.
@@ -966,7 +989,7 @@ function analyzeStructs(items, aliases, dataEnums, reporter, scopeFor, fstrings,
                 name,
                 fields: stored,
                 size: undefined,
-                accountDiscriminator: discriminator(`account:${name}`),
+                accountDiscriminator: accountDiscriminator(decl, name, reporter),
                 eventDiscriminator: discriminator(`event:${name}`),
                 node: decl,
                 layout: layoutText === "borsh" ? "borsh" : "fixed",
@@ -1321,7 +1344,7 @@ function analyzeHelper(fn, name, display, reporter, scope, structs, skip = new S
             wrapped === "Ata")
             reporter.fail(p.type, "constraints belong on instruction parameters; helpers take the plain account type");
         const account = resolveAccountKind(p.type, reporter, scope.imports, structs);
-        if (account.kind === "init" || account.kind === "initIfNeeded" || account.kind === "zeroed")
+        if (account.kind === "init" || account.kind === "initIfNeeded" || account.kind === "zeroed" || account.kind === "migrate")
             reporter.fail(p.type, "helpers take accounts that exist: create Init/InitIfNeeded/Zeroed accounts in the instruction, then pass them as Mut<T>");
         return { name: p.name.text, type: { kind: "account" }, account, node: p };
     });
@@ -1445,7 +1468,7 @@ function analyzeInstruction(fn, reporter, scope, structs) {
             const inner = unwrapConstraints(typeNode, reporter, imports, constraints);
             const kind = resolveAccountKind(inner, reporter, imports, structs);
             if (optional &&
-                (["init", "initIfNeeded", "zeroed", "pyth", "eventAuthority", "selfProgram", "programData"].includes(kind.kind) ||
+                (["init", "initIfNeeded", "zeroed", "migrate", "pyth", "eventAuthority", "selfProgram", "programData"].includes(kind.kind) ||
                     ((kind.kind === "token" || kind.kind === "mint") && kind.init)))
                 reporter.fail(p, "Init, InitIfNeeded, Zeroed, PythPriceUpdate, EventAuthority, SelfProgram and ProgramData accounts cannot be optional");
             accounts.push({ name: p.name.text, index: accounts.length, kind, node: p, constraints, ...(optional ? { optional } : {}) });
@@ -1566,6 +1589,18 @@ function analyzeInstruction(fn, reporter, scope, structs) {
         reporter.error(fn.name, "instructions that grow a Vec (push) need a SystemProgram parameter to top up rent");
     if (needs("init") && !needs("system"))
         reporter.error(fn.name, "instructions with Init<...> accounts need a SystemProgram parameter");
+    if (accounts.some((a) => a.kind.kind === "migrate" && a.kind.to.size > a.kind.from.size) && !needs("system"))
+        reporter.error(fn.name, "a Migrate<From, To> that grows the account needs a SystemProgram parameter (the payer tops up its rent)");
+    for (const a of accounts)
+        if (a.kind.kind === "migrate" &&
+            (a.constraints.hasOne.length ||
+                a.constraints.seeds ||
+                a.constraints.closeTo ||
+                a.constraints.ata ||
+                a.constraints.address ||
+                a.constraints.owner ||
+                a.constraints.dup))
+            reporter.error(a.node, "Migrate<From, To> takes no constraints yet: check the old fields with require(…, …) on acct.from");
     const name = snakeCase(fn.name.text);
     // `/** @discriminator spl-transfer-hook-interface:execute */` (sha256 preimage) or `@discriminator 0x...` (raw bytes)
     // lets an instruction implement another program's interface.
@@ -1596,7 +1631,7 @@ function analyzeInstruction(fn, reporter, scope, structs) {
 /** Peel HasOne / Seeds / CloseTo wrappers off a parameter type, recording what they ask for. */
 function unwrapConstraints(node, reporter, imports, out) {
     const name = typesolName(node, imports);
-    if (!["HasOne", "TokenOf", "MintOf", "Seeds", "CloseTo", "Address", "Ata", "Owner", "Executable"].includes(name ?? ""))
+    if (!["HasOne", "TokenOf", "MintOf", "Seeds", "CloseTo", "Address", "Ata", "Owner", "Executable", "Dup"].includes(name ?? ""))
         return node;
     const args = node.typeArguments ?? [];
     const lit = (t) => {
@@ -1638,6 +1673,8 @@ function unwrapConstraints(node, reporter, imports, out) {
     }
     if (name === "Executable")
         out.executable = true;
+    if (name === "Dup")
+        out.dup = true;
     if (name === "Address") {
         const text = lit(args[1])[0];
         const bytes = text === undefined ? undefined : decodeAddress(text);
@@ -1668,6 +1705,8 @@ function unwrapConstraints(node, reporter, imports, out) {
         reporter.fail(node, `${name}<…> wraps an account type`);
     return unwrapConstraints(args[0], reporter, imports, out);
 }
+/** Solana: an account grows at most this many bytes per instruction. */
+const MAX_PERMITTED_DATA_INCREASE = 10_240;
 function resolveAccountKind(node, reporter, imports, structs) {
     const outer = typesolName(node, imports);
     const ref = node;
@@ -1769,6 +1808,24 @@ function resolveAccountKind(node, reporter, imports, structs) {
                 reporter.fail(node, `${s.name} is too large to create in a program; use Zeroed<${s.name}>`);
             return { kind: "initIfNeeded", struct: s };
         }
+        case "Migrate": {
+            const [fromNode, toNode] = ref.typeArguments ?? [];
+            const from = fromNode && structOf(fromNode);
+            const to = toNode && structOf(toNode);
+            if (!from || !to || ref.typeArguments.length !== 2)
+                reporter.fail(node, "Migrate<From, To> takes two account structs declared in this program");
+            for (const s of [from, to]) {
+                if (s.vec)
+                    reporter.fail(node, `${s.name} has a growable Vec; Migrate<From, To> takes fixed-size structs`);
+                if (s.layout === "borsh")
+                    reporter.fail(node, `${s.name} is @layout borsh; Migrate<From, To> takes fixed layouts`);
+            }
+            if (from.accountDiscriminator.join() === to.accountDiscriminator.join())
+                reporter.fail(node, `${from.name} and ${to.name} have the same discriminator: give the new struct another name (or the old one /** @discriminator account:<OldName> */)`);
+            if (to.size - from.size > MAX_PERMITTED_DATA_INCREASE)
+                reporter.fail(node, `${to.name} is more than 10 KiB larger than ${from.name}; an account grows at most 10 KiB per instruction`);
+            return { kind: "migrate", from, to };
+        }
         case "Zeroed": {
             const s = structOf(inner());
             if (!s)

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

@@ -112,6 +112,8 @@ export declare abstract class EmitterBase {
     protected abstract call(node: ts.CallExpression, topLevel: boolean): Value | undefined;
     protected abstract isRemaining(node: ts.Expression): boolean;
     protected abstract handle(node: ts.Expression): string | undefined;
+    protected abstract instructionsParam(node: ts.Expression): AccountParam | undefined;
+    protected abstract isTxIx(node: ts.Expression): boolean;
     protected abstract seeds(node: ts.Expression, extra: number): {
         name: string;
         count: number;

package/dist/compiler/emit/base.js

@@ -65,7 +65,10 @@ export class EmitterBase {
             this.ix = target;
             for (const a of target.accounts) {
                 this.accounts.set(a.name, a);
-                if (a.kind.kind === "init" || a.kind.kind === "initIfNeeded" || ((a.kind.kind === "token" || a.kind.kind === "mint") && a.kind.init))
+                if (a.kind.kind === "init" ||
+                    a.kind.kind === "initIfNeeded" ||
+                    a.kind.kind === "migrate" ||
+                    ((a.kind.kind === "token" || a.kind.kind === "mint") && a.kind.init))
                     this.pendingInit.add(a.name);
             }
             for (const a of target.args)

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

@@ -1,5 +1,5 @@
 import ts from "typescript";
-import { type ErrorDef, type FieldType, type Helper } from "../model.js";
+import { type AccountParam, type ErrorDef, type FieldType, type Helper } from "../model.js";
 import { type Value, type Ref, type Closure } from "./shared.js";
 import { ExpressionEmitter } from "./expressions.js";
 export declare abstract class CallEmitter extends ExpressionEmitter {
@@ -20,6 +20,15 @@ export declare abstract class CallEmitter extends ExpressionEmitter {
     /** `remainingAccounts()` or a const bound to it. */
     protected isRemaining(node: ts.Expression): boolean;
     /** C pointer (`TsAccount *`) for an expression naming a remaining account, or undefined. */
+    /** Whether `node` is an InstructionsSysvar parameter. */
+    protected instructionsParam(node: ts.Expression): AccountParam | undefined;
+    /** Whether `node` is a TransactionInstruction: a local holding one, or `ixs.get(i)`. */
+    protected isTxIx(node: ts.Expression): boolean;
+    /**
+     * InstructionsSysvar.currentIndex() / .get(i) and the methods of a TransactionInstruction: bounds-checked reads of the
+     * sysvar (ts_ix_* in the runtime). Undefined when the call is something else.
+     */
+    protected instructionsCall(node: ts.CallExpression, callee: ts.PropertyAccessExpression, method: string): Value | undefined;
     protected handle(node: ts.Expression): string | undefined;
     /** A declared account parameter or a remaining account, as a `TsAccount *` C expression. */
     protected anyAccount(node: ts.Expression, what: string): string;
@@ -29,6 +38,12 @@ export declare abstract class CallEmitter extends ExpressionEmitter {
     protected loadForeign(node: ts.CallExpression): Value;
     /** `loadAccount<T>(acct)` / `loadAccountMut<T>(acct)`: checked view of a program account. */
     protected loadAccount(node: ts.CallExpression, mut: boolean): Value;
+    /**
+     * `acct.migrate(payer, value)` on a Migrate<From, To> account: the new value is built in full first (it may read
+     * acct.from, whose bytes the rewrite overwrites), then the account is resized (the payer tops up the rent when it
+     * grows; shrinking keeps the lamports) and rewritten with To's discriminator and the value.
+     */
+    protected migrate(node: ts.CallExpression, a: AccountParam, topLevel: boolean): Value | undefined;
     /** Whether a helper (or one it calls) grows a Vec, which needs the instruction's SystemProgram for rent. */
     private helperGrows;
     /**