@typesol/cli 0.23.0 → 0.24.0

package/docs/troubleshooting.md

@@ -27,8 +27,9 @@ or declare `const HEAP_SIZE_KIB = 64n` and add a ComputeBudget `requestHeapFrame
 `solana-test-validator` (Agave 3.1 included) rejects a System instruction that the current Program Metadata program
 uses. Publishing works on mainnet-beta. The error shows the failing transaction's last log lines.
 
-**"instruction X needs N bytes of stack; SBF gives each function 4096"** — every function on Solana gets a 4 KiB
-stack frame, and going past it corrupts memory, so the build refuses it. Large structs and arrays copied into typed
+**"instruction X (with the helpers inlined into it) needs N bytes of stack; SBPF v0 gives each function 4096"** — under
+SBPF v0 (the default) every function gets a fixed 4 KiB stack frame, and going past it corrupts memory, so the build
+refuses it. SBPF v1 and v2 (`--sbpf v1` / `v2`) grow frames dynamically, so this limit does not apply there. Large structs and arrays copied into typed
 locals (`const q: Big = acct.big`) are the usual cause: bind them without a type (`const q = acct.big`, a reference
 into the account data) or move the work into helpers. Helpers are often inlined into their instruction, so their
 locals count toward its frame.

package/lib/typesol.d.ts

@@ -8,6 +8,10 @@
  * Integer types are all `bigint` to TypeScript. The compiler tracks the declared
  * width itself, rejects `number`, and checks every arithmetic operation for
  * overflow at runtime.
+ *
+ * Integer operators: + - * / % are checked (overflow and division by zero abort). & | ^ work on equal types;
+ * << aborts when bits would be lost or the amount is not below the width; >> is arithmetic on signed types;
+ * ~ flips the bits within the type's width.
  */
 
 export type u8 = bigint;
@@ -27,10 +31,6 @@ export interface Pubkey {
   equals(other: Pubkey): boolean;
 }
 
-/**
- * A fixed-length array stored inline in account data, e.g. `scores: FixedArray<u64, 8>`.
- * Indexes are bounds-checked; out of range aborts the instruction.
- */
 /**
  * Callback methods of Vec, FixedArray and FixedVec. Each expands into a loop over the elements (as `list.get(i)` gives
  * them: structs by reference) with the arrow written at the call; it may read and write the function's variables.
@@ -53,13 +53,19 @@ export interface ListMethods<T> {
   /**
    * The elements `fn` maps them to (integers, booleans, Pubkeys or enums). Use it right away (another list method,
    * `.length`, `for … of`: one loop, nothing stored) or store it (`const ys = xs.map(…)`: a FixedVec on the stack, as
-   * big as `xs`; from a `Vec`, annotate it: `const ys: FixedVec<u64, 16> = …`).
+   * big as `xs`; from a `Vec`, annotate it: `const ys: FixedVec<u64, 16> = …`). Stored with a `FixedVec<Struct, N>` or
+   * `FixedVec<FixedString<N>, M>` annotation it gives structs (`(o) => ({ qty: o.qty })`) or text. A stored list holds
+   * at most 2 KiB; one element more than it holds aborts (5104).
    */
   map<U>(fn: (x: T, index: u64) => U): FixedVec<U, never>;
   /** The elements `fn` holds for, used or stored like `map`'s; callbacks after it get the index among those. */
   filter(fn: (x: T, index: u64) => boolean): FixedVec<T, never>;
 }
 
+/**
+ * A fixed-length array stored inline in account data, e.g. `scores: FixedArray<u64, 8>`.
+ * Indexes are bounds-checked; out of range aborts the instruction.
+ */
 export interface FixedArray<T, N extends number> extends ListMethods<T> {
   readonly length: u64;
   get(index: bigint): T;
@@ -82,15 +88,17 @@ export type FixedString<N extends number> = string & { readonly __capacity?: N }
 export declare function byteLength(value: string): u64;
 
 /**
- * An optional scalar: `best: Option<u64>` (same as `u64 | null`). Compare with `=== null` / `!== null`;
+ * An optional value: `best: Option<u64>` (same as `u64 | null`), also of a struct (`home: Option<Point>`). Compare with `=== null` / `!== null`;
  * TypeScript narrows it, and using an empty option where a value is needed aborts (5108).
  * In account data it takes a fixed 1 + size(T) bytes.
  */
 export type Option<T> = T | null;
 
 /**
- * A growable list. As the last field of an account struct it is stored Borsh-style (u32 length + elements)
- * and the account is resized as it grows. As an instruction argument it is a read-only view.
+ * A growable list. As an account struct field it is stored Borsh-style (u32 length + elements) and the account is
+ * resized as it grows. An account may have any number of them, declared anywhere: they are stored after the
+ * fixed-size fields, in the order declared (in a `@layout borsh` struct, a Vec must be the last field). As an
+ * instruction argument it is a read-only view.
  */
 export interface Vec<T> extends ListMethods<T> {
   readonly length: u64;
@@ -108,8 +116,8 @@ export interface Vec<T> extends ListMethods<T> {
 
 /**
  * A list stored inline with room for N elements: a u32 length, then N slots (Anchor `Vec<T>` with `#[max_len(N)]`, but
- * always 4 + N × size(T) bytes). Unlike `Vec<T>` it can be any field, any number of times, and in nested structs;
- * `push` fails (5104) when it is full. Write a whole one with `fixedVec([a, b])`.
+ * always 4 + N × size(T) bytes). Unlike `Vec<T>` its size is fixed: it keeps its place among the fields, can be in
+ * nested structs, and `push` takes no payer; `push` fails (5104) when it is full. Write a whole one with `fixedVec([a, b])`.
  */
 export interface FixedVec<T, N extends number> extends ListMethods<T> {
   readonly length: u64;
@@ -611,11 +619,6 @@ export interface SelfProgram extends AccountMeta {
  */
 export declare function emitCpi<T>(event: T, eventAuthority: EventAuthority, self: SelfProgram): void;
 
-/**
- * Metaplex Core (CoREEN…), address checked. Assets and collections without plugins; `null` leaves an optional
- * account out. Accounts that sign (the new asset/collection, authorities) are keypair Signers, or PDAs of this
- * program covered by `signerSeeds`.
- */
 /**
  * Who manages a Metaplex Core plugin: `"owner"`, `"updateAuthority"`, `"none"` (nobody: fixed), or an address. Left out,
  * the plugin type's default (the owner for owner-managed plugins, the update authority for the others).
@@ -650,7 +653,49 @@ export type CorePlugin = (
   | { kind: "PermanentFreezeExecute"; frozen: boolean }
 ) & { authority?: CorePluginAuthority };
 export type CorePluginKind = CorePlugin["kind"] | "Groups";
+/** When a Core lifecycle event reaches an external plugin, and what the plugin may do about it. */
+export interface CoreLifecycleCheck {
+  event: "create" | "transfer" | "burn" | "update" | "execute";
+  canListen?: boolean;
+  canApprove?: boolean;
+  canReject?: boolean;
+}
+/** An account Core passes to an external plugin: one it already has, or an address. */
+export type CoreExtraAccount =
+  | { kind: "program" | "collection" | "owner" | "recipient" | "asset"; isSigner?: boolean; isWritable?: boolean }
+  | { kind: "address"; address: Pubkey; isSigner?: boolean; isWritable?: boolean };
+/**
+ * A Metaplex Core external plugin adapter, written as an object literal: data a third party writes (`AppData`), an
+ * account that approves or rejects lifecycle events (`Oracle`), or a program called on them (`LifecycleHook`); the
+ * `Linked` forms go on a collection, for each of its assets. `authority` manages the adapter itself.
+ */
+export type CoreExternalPlugin = (
+  | { kind: "AppData" | "LinkedAppData"; dataAuthority: CorePluginAuthority; schema?: "binary" | "json" | "msgpack" }
+  | {
+      kind: "Oracle";
+      baseAddress: Pubkey;
+      checks: CoreLifecycleCheck[];
+      baseAddressConfig?: CoreExtraAccount;
+      resultsOffset?: "none" | "anchor" | u64;
+    }
+  | {
+      kind: "LifecycleHook" | "LinkedLifecycleHook";
+      hookedProgram: Pubkey;
+      checks: CoreLifecycleCheck[];
+      extraAccounts?: CoreExtraAccount[];
+      dataAuthority?: CorePluginAuthority;
+      schema?: "binary" | "json" | "msgpack";
+    }
+) & { authority?: CorePluginAuthority };
+/** Which external plugin: an AppData by its data authority, an Oracle by its base address, a LifecycleHook by its program. */
+export type CoreExternalPluginKey =
+  { kind: "AppData" | "LinkedAppData"; dataAuthority: CorePluginAuthority } | { kind: "Oracle" | "LifecycleHook" | "LinkedLifecycleHook"; address: Pubkey };
 
+/**
+ * Metaplex Core (CoREEN…), address checked. Assets and collections, with plugins and external plugin adapters; `null`
+ * leaves an optional account out. Accounts that sign (the new asset/collection, authorities) are keypair Signers, or
+ * PDAs of this program covered by `signerSeeds`.
+ */
 export interface MplCoreProgram extends AccountMeta {
   readonly __mpl_core: void;
   /**
@@ -753,6 +798,61 @@ export interface MplCoreProgram extends AccountMeta {
     kind: CorePluginKind,
     signerSeeds?: Seed[] | SignerSeeds,
   ): void;
+  /** AddExternalPluginAdapterV1, signed by the update authority as `authority` (`null`: the payer). */
+  addExternalPlugin(
+    asset: AccountMeta,
+    collection: AccountMeta | null,
+    payer: Mut<Signer>,
+    authority: AccountMeta | null,
+    systemProgram: SystemProgram,
+    plugin: CoreExternalPlugin,
+    signerSeeds?: Seed[] | SignerSeeds,
+  ): void;
+  removeExternalPlugin(
+    asset: AccountMeta,
+    collection: AccountMeta | null,
+    payer: Mut<Signer>,
+    authority: AccountMeta | null,
+    systemProgram: SystemProgram,
+    key: CoreExternalPluginKey,
+    signerSeeds?: Seed[] | SignerSeeds,
+  ): void;
+  /** WriteExternalPluginAdapterDataV1, signed by the plugin's data authority: `data` replaces what it holds (`null` clears it). */
+  writeExternalPluginData(
+    asset: AccountMeta,
+    collection: AccountMeta | null,
+    payer: Mut<Signer>,
+    authority: AccountMeta | null,
+    systemProgram: SystemProgram,
+    key: CoreExternalPluginKey,
+    data: string | Vec<u8> | null,
+    signerSeeds?: Seed[] | SignerSeeds,
+  ): void;
+  addCollectionExternalPlugin(
+    collection: AccountMeta,
+    payer: Mut<Signer>,
+    authority: AccountMeta | null,
+    systemProgram: SystemProgram,
+    plugin: CoreExternalPlugin,
+    signerSeeds?: Seed[] | SignerSeeds,
+  ): void;
+  removeCollectionExternalPlugin(
+    collection: AccountMeta,
+    payer: Mut<Signer>,
+    authority: AccountMeta | null,
+    systemProgram: SystemProgram,
+    key: CoreExternalPluginKey,
+    signerSeeds?: Seed[] | SignerSeeds,
+  ): void;
+  writeCollectionExternalPluginData(
+    collection: AccountMeta,
+    payer: Mut<Signer>,
+    authority: AccountMeta | null,
+    systemProgram: SystemProgram,
+    key: CoreExternalPluginKey,
+    data: string | Vec<u8> | null,
+    signerSeeds?: Seed[] | SignerSeeds,
+  ): void;
   /** TransferV1, signed by the owner (or a delegate) as `authority` (`null`: the payer). */
   transferAsset(
     asset: AccountMeta,
@@ -1437,7 +1537,6 @@ export declare function invoke(
   signerSeeds?: Seed[] | SignerSeeds,
 ): void;
 
-/** Abort with the given error unless `condition` holds. Use a string enum member or a string literal. */
 /**
  * Anchor's own error codes (anchor-lang `ErrorCode`): `require(condition, AnchorError.AccountDidNotDeserialize)` fails
  * with that code, as `require!(condition, ErrorCode::AccountDidNotDeserialize)` does. Not listed in the IDL's errors.
@@ -1521,6 +1620,11 @@ export declare enum AnchorError {
   InvalidNumericConversion = 4102,
   Deprecated = 5000,
 }
+/**
+ * Abort with the given error unless `condition` holds. The error is a member of an exported string enum, any
+ * `AnchorError` member, or a string literal: each distinct literal becomes an error named `RequireFailed<N>` with code
+ * 6000 + N, numbered after the program's error enums and listed in the IDL.
+ */
 export declare function require(condition: boolean, error: string | AnchorError): asserts condition;
 
 /** Write a string, integer or pubkey to the program log. */
@@ -1562,11 +1666,6 @@ export declare function i16(value: bigint): i16;
 export declare function i32(value: bigint): i32;
 export declare function i128(value: bigint): i128;
 
-/**
- * Integer operators: + - * / % are checked (overflow and division by zero abort). & | ^ work on equal types;
- * << aborts when bits would be lost or the amount is not below the width; >> is arithmetic on signed types;
- * ~ flips the bits within the type's width.
- */
 /** floor(a * b / c) with a double-width intermediate (all u64, or all u128); aborts if c is 0 or the result does not fit. */
 export declare function mulDiv(a: u64, b: u64, c: u64): u64;
 /** ceil(a * b / c), like mulDiv. */

package/package.json

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

package/runtime/typesol_rt.h

@@ -369,9 +369,19 @@ static inline uint64_t ts_create_pda_address(const SolSignerSeed *seeds, int n,
 /* sol_try_find_program_address: the canonical (highest) bump. */
 static inline uint64_t ts_find_pda(const SolSignerSeed *seeds, int n, const SolPubkey *program, SolPubkey *out, uint8_t *bump_out) {
   if (!ts_pda_seeds_ok(seeds, n, TS_MAX_PDA_SEEDS - 1)) return 1; /* not SUCCESS: the PDA syscalls fail the same inputs */
+  /* The seed list is built once; each attempt only changes the bump byte it points at. */
+  SolBytes parts[TS_MAX_PDA_SEEDS + 2];
+  int k = 0;
+  for (int i = 0; i < n; i++) parts[k++] = (SolBytes){seeds[i].addr, seeds[i].len};
+  uint8_t bump = 255;
+  parts[k++] = (SolBytes){&bump, 1};
+  parts[k++] = (SolBytes){program->x, 32};
+  parts[k++] = (SolBytes){(const uint8_t *)"ProgramDerivedAddress", 21};
   for (int b = 255; b >= 0; b--) {
-    uint8_t bump = (uint8_t)b;
-    if (ts_pda_hash(seeds, n, &bump, program, out)) {
+    bump = (uint8_t)b;
+    sol_sha256(parts, k, out->x);
+    uint8_t ignored;
+    if (sol_curve_validate_point(0 /* CURVE25519_EDWARDS */, out->x, &ignored) != 0) {
       *bump_out = bump;
       return SUCCESS;
     }
@@ -493,10 +503,9 @@ static inline void ts_write_le(uint8_t *p, uint64_t v, int n) { ts_memcpy(p, &v,
 uint64_t sol_get_rent_sysvar(void *ret);
 uint64_t sol_get_clock_sysvar(void *ret);
 
-static inline uint64_t ts_minimum_balance(uint64_t data_len, uint64_t *out) {
-  /* Rent { lamports_per_byte_year: u64, exemption_threshold: f64, burn_percent: u8 } */
-  uint64_t rent[3] = {0};
-  if (sol_get_rent_sysvar(rent) != SUCCESS) TS_FAIL(TS_ERR_SYSVAR, "TypeSOL: rent sysvar unavailable");
+/* The minimum balance of `data_len` bytes under `rent`, the Rent sysvar
+   { lamports_per_byte_year: u64, exemption_threshold: f64, burn_percent: u8 }. */
+static inline uint64_t ts_minimum_balance_of(const uint64_t rent[3], uint64_t data_len, uint64_t *out) {
   uint64_t bytes, per_year;
   if (ts_add_overflow_u64(data_len, 128, &bytes) || ts_mul_overflow_u64(bytes, rent[0], &per_year))
     TS_FAIL(TS_ERR_OVERFLOW, "TypeSOL: arithmetic overflow");
@@ -519,6 +528,18 @@ static inline uint64_t ts_minimum_balance(uint64_t data_len, uint64_t *out) {
   return SUCCESS;
 }
 
+static inline uint64_t ts_rent(uint64_t rent[3]) {
+  rent[0] = rent[1] = rent[2] = 0;
+  if (sol_get_rent_sysvar(rent) != SUCCESS) TS_FAIL(TS_ERR_SYSVAR, "TypeSOL: rent sysvar unavailable");
+  return SUCCESS;
+}
+
+static inline uint64_t ts_minimum_balance(uint64_t data_len, uint64_t *out) {
+  uint64_t rent[3];
+  TS_TRY(ts_rent(rent));
+  return ts_minimum_balance_of(rent, data_len, out);
+}
+
 /* Clock sysvar word `i`: 0 slot, 2 epoch (u64). */
 static inline uint64_t ts_clock_u64(int i, uint64_t *out) {
   uint64_t clock[5] = {0};
@@ -791,9 +812,10 @@ static inline uint64_t ts_resize(TsParams *params, TsAccount *payer, TsAccount *
   if (new_len > old_len) {
     /* The payer always funds the extra rent, even when the account already holds enough lamports: those may be
        deposits, which must not become rent (and shrinking never pays anything back, see ts_realloc). */
-    uint64_t old_rent, new_rent;
-    TS_TRY(ts_minimum_balance(old_len, &old_rent));
-    TS_TRY(ts_minimum_balance(new_len, &new_rent));
+    uint64_t rent[3], old_rent, new_rent;
+    TS_TRY(ts_rent(rent)); /* read once: the sysvar cannot change within the instruction */
+    TS_TRY(ts_minimum_balance_of(rent, old_len, &old_rent));
+    TS_TRY(ts_minimum_balance_of(rent, new_len, &new_rent));
     if (new_rent > old_rent) {
       if (payer == NULL) TS_FAIL(TS_ERR_REALLOC, "TypeSOL: growing an account needs a payer");
       TS_TRY(ts_system_transfer(params, payer, acct, new_rent - old_rent));
@@ -1340,18 +1362,32 @@ static inline uint64_t ts_str_i128(__int128 v, TS_Str *out) {
   return ts_str_u128(mag, v < 0, out);
 }
 
+/* "00" … "99": two digits per division. */
+static const char TS_DIGIT_PAIRS[201] =
+    "00010203040506070809101112131415161718192021222324252627282930313233343536373839"
+    "40414243444546474849505152535455565758596061626364656667686970717273747576777879"
+    "8081828384858687888990919293949596979899";
 static inline uint64_t ts_str_u64(uint64_t v, bool negative, TS_Str *out) {
+  /* Written from the end, two digits at a time, then copied out in one go. */
   uint8_t tmp[21];
-  int n = 0;
-  do {
-    tmp[n++] = (uint8_t)('0' + v % 10);
-    v /= 10;
-  } while (v);
-  if (negative) tmp[n++] = '-';
+  int i = 21;
+  while (v >= 100) {
+    uint64_t q = v / 100, r = v - q * 100;
+    tmp[--i] = (uint8_t)TS_DIGIT_PAIRS[2 * r + 1];
+    tmp[--i] = (uint8_t)TS_DIGIT_PAIRS[2 * r];
+    v = q;
+  }
+  if (v >= 10) {
+    tmp[--i] = (uint8_t)TS_DIGIT_PAIRS[2 * v + 1];
+    tmp[--i] = (uint8_t)TS_DIGIT_PAIRS[2 * v];
+  } else
+    tmp[--i] = (uint8_t)('0' + v);
+  if (negative) tmp[--i] = '-';
+  uint64_t n = (uint64_t)(21 - i);
   uint8_t *p;
-  TS_TRY(ts_alloc((uint64_t)n, &p));
-  for (int i = 0; i < n; i++) p[i] = tmp[n - 1 - i];
-  *out = ts_str(p, (uint64_t)n);
+  TS_TRY(ts_alloc(n, &p));
+  ts_memcpy(p, tmp + i, n);
+  *out = ts_str(p, n);
   return SUCCESS;
 }
 static inline uint64_t ts_str_i64(int64_t v, TS_Str *out) {