@xgamesfun/solana 0.0.0-stage → 0.24.0

package/js/chain/base58.js

@@ -0,0 +1,73 @@
+// Base58 (Bitcoin alphabet): the text form of every Solana address and signature.
+
+const ALPHABET = '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz';
+const INDEX = new Map([...ALPHABET].map((c, i) => [c, i]));
+/** An address is 32 bytes: 32 to 44 base58 characters. */
+const ADDRESS_TEXT = /^[1-9A-HJ-NP-Za-km-z]{32,44}$/;
+const ADDRESS_BYTES = 32;
+/** A signature is 64 bytes: 64 to 88 base58 characters. */
+const SIGNATURE_TEXT = /^[1-9A-HJ-NP-Za-km-z]{64,88}$/;
+
+/** The address of 32 zero bytes: what an address field holds when it names no account (the System program's address too). */
+export const NO_ADDRESS = '11111111111111111111111111111111';
+
+export function encodeBase58(bytes) {
+  const digits = [];
+  for (const byte of bytes) {
+    let carry = byte;
+    for (let i = 0; i < digits.length; i++) {
+      carry += digits[i] << 8;
+      digits[i] = carry % 58;
+      carry = Math.floor(carry / 58);
+    }
+    while (carry > 0) {
+      digits.push(carry % 58);
+      carry = Math.floor(carry / 58);
+    }
+  }
+  let zeros = '';
+  for (const byte of bytes) {
+    if (byte !== 0) break;
+    zeros += '1';
+  }
+  return zeros + digits.reverse().map((d) => ALPHABET[d]).join('');
+}
+
+export function decodeBase58(text) {
+  const bytes = [];
+  for (const char of text) {
+    const value = INDEX.get(char);
+    if (value === undefined) throw new Error(`Not base58: ${JSON.stringify(char)}`);
+    let carry = value;
+    for (let i = 0; i < bytes.length; i++) {
+      carry += bytes[i] * 58;
+      bytes[i] = carry & 0xff;
+      carry >>= 8;
+    }
+    while (carry > 0) {
+      bytes.push(carry & 0xff);
+      carry >>= 8;
+    }
+  }
+  let zeros = 0;
+  while (text[zeros] === '1') zeros++;
+  return Uint8Array.from([...new Array(zeros).fill(0), ...bytes.reverse()]);
+}
+
+/** Whether the text is a Solana address: base58 that decodes to exactly 32 bytes. */
+export function isAddress(text) {
+  if (typeof text !== 'string' || !ADDRESS_TEXT.test(text)) return false;
+  return decodeBase58(text).length === ADDRESS_BYTES;
+}
+
+/** Whether the text is a transaction signature: base58 that decodes to exactly 64 bytes. */
+export function isSignature(text) {
+  if (typeof text !== 'string' || !SIGNATURE_TEXT.test(text)) return false;
+  return decodeBase58(text).length === 64;
+}
+
+/** The 32 bytes of an address; throws on anything else. */
+export function addressBytes(address) {
+  if (!isAddress(address)) throw new Error(`Not a Solana address: ${String(address).slice(0, 60)}`);
+  return decodeBase58(address);
+}

package/js/chain/borsh.js

@@ -0,0 +1,270 @@
+// A small Borsh codec driven by an Anchor IDL, so neither side needs Anchor. It covers what the loot program and the
+// accounts this kit reads use: bool, u8–u128, i32, i64, pubkey, string, fixed arrays, vec, option, defined structs and
+// enums, with or without data. Plain Uint8Array, never Node's Buffer, so it runs in browser apps and Node alike.
+//
+// Values: addresses are base58 strings, u64/u128/i64 bigints (u8–u32 numbers), byte arrays Uint8Arrays. An enum is
+// its variant's name ('Nothing'), or for a variant with data { Name: [values] } (tuple fields) or
+// { Name: { field: value } } (named fields). Account and event discriminators are whatever length the IDL gives (loot
+// tags its accounts with one byte).
+import { addressBytes, encodeBase58 } from './base58.js';
+import { concat, equalBytes, fromBase64, fromUtf8, intLE, readUintLE, uintLE, utf8 } from './bytes.js';
+
+const UINT = { u8: 1, u16: 2, u32: 4, u64: 8, u128: 16 };
+const INT = { i32: 4, i64: 8 };
+const ADDRESS_BYTES = 32;
+
+function typeDef(idl, name) {
+  const def = idl.types.find((t) => t.name === name);
+  if (!def) throw new Error(`Unknown IDL type ${name}`);
+  return def;
+}
+
+function readIntLE(data, at, size) {
+  const v = BigInt(readUintLE(data, at, size));
+  const bits = BigInt(size * 8);
+  const signed = v >= 1n << (bits - 1n) ? v - (1n << bits) : v;
+  // An i32 is a number, as u8 to u32 are; an i64 a bigint.
+  return size <= 4 ? Number(signed) : signed;
+}
+
+function encodeScalar(type, value, out) {
+  if (UINT[type]) out.push(uintLE(value, UINT[type]));
+  else if (INT[type]) out.push(intLE(value, INT[type]));
+  else if (type === 'bool') out.push(Uint8Array.of(value ? 1 : 0));
+  else if (type === 'pubkey') out.push(addressBytes(String(value)));
+  else if (type === 'string') {
+    const bytes = utf8(String(value));
+    out.push(uintLE(bytes.length, 4), bytes);
+  } else if (type === 'bytes') {
+    // A list of bytes (`Vec<u8>`): its length, then the bytes.
+    const bytes = Uint8Array.from(value);
+    out.push(uintLE(bytes.length, 4), bytes);
+  } else throw new Error(`Unsupported IDL type ${type}`);
+}
+
+/** A variant's field list: named ({ name, type }) or tuple (bare types). */
+const isNamed = (fields) => typeof fields[0] === 'object' && fields[0] !== null && 'name' in fields[0];
+
+function encodeDefined(idl, name, value, out) {
+  const def = typeDef(idl, name).type;
+  if (def.kind === 'enum') {
+    const variantName = typeof value === 'string' ? value : Object.keys(value ?? {})[0];
+    const index = def.variants.findIndex((v) => v.name === variantName);
+    if (index < 0) throw new Error(`${name} has no variant ${String(variantName)}`);
+    out.push(Uint8Array.of(index));
+    const fields = def.variants[index].fields ?? [];
+    if (!fields.length) return;
+    const payload = typeof value === 'string' ? null : value[variantName];
+    if (payload == null) throw new Error(`${name}.${variantName} needs its data`);
+    if (isNamed(fields)) for (const f of fields) encodeInto(idl, f.type, payload[f.name], out);
+    else fields.forEach((f, i) => encodeInto(idl, f, payload[i], out));
+    return;
+  }
+  for (const field of def.fields) {
+    if (!(field.name in value)) throw new Error(`${name}.${field.name} is required`);
+    encodeInto(idl, field.type, value[field.name], out);
+  }
+}
+
+/**
+ * A `[u8; N]`: a Uint8Array, or an array of integers from 0 to 255, of exactly `length` bytes. Anything else (a string,
+ * a number past a byte) is refused rather than written as other bytes.
+ */
+function byteArray(value, length) {
+  const bytes = value instanceof Uint8Array || (Array.isArray(value) && value.every((b) => Number.isInteger(b) && b >= 0 && b <= 255));
+  if (!bytes) throw new TypeError(`Expected ${length} bytes: a Uint8Array or an array of integers from 0 to 255`);
+  if (value.length !== length) throw new Error(`Expected ${length} bytes, got ${value.length}`);
+  return Uint8Array.from(value);
+}
+
+function encodeInto(idl, type, value, out) {
+  if (typeof type === 'string') return encodeScalar(type, value, out);
+  if ('array' in type) {
+    const [inner, length] = type.array;
+    if (inner === 'u8') {
+      out.push(byteArray(value, length));
+      return;
+    }
+    if (value.length !== length) throw new Error(`Expected ${length} items, got ${value.length}`);
+    for (const item of Array.from(value)) encodeInto(idl, inner, item, out);
+    return;
+  }
+  if ('vec' in type) {
+    out.push(uintLE(value.length, 4));
+    for (const item of value) encodeInto(idl, type.vec, item, out);
+    return;
+  }
+  if ('option' in type) {
+    if (value === null || value === undefined) out.push(Uint8Array.of(0));
+    else {
+      out.push(Uint8Array.of(1));
+      encodeInto(idl, type.option, value, out);
+    }
+    return;
+  }
+  encodeDefined(idl, type.defined.name, value, out);
+}
+
+/** The Borsh bytes of one value of `type`. */
+export function encodeBorsh(idl, type, value) {
+  const out = [];
+  encodeInto(idl, type, value, out);
+  return concat(...out);
+}
+
+/** An instruction's data: its discriminator, then each argument in IDL order. */
+export function encodeInstruction(idl, name, args) {
+  const ix = idl.instructions.find((i) => i.name === name);
+  if (!ix) throw new Error(`Unknown instruction ${name}`);
+  const out = [Uint8Array.from(ix.discriminator)];
+  for (const arg of ix.args) {
+    if (!(arg.name in args)) throw new Error(`${name}: missing argument ${arg.name}`);
+    encodeInto(idl, arg.type, args[arg.name], out);
+  }
+  return concat(...out);
+}
+
+/** An account's bytes as the program writes them: its discriminator, then its fields. */
+export function encodeAccount(idl, name, value) {
+  const account = idl.accounts.find((a) => a.name === name);
+  if (!account) throw new Error(`Unknown account type ${name}`);
+  return concat(Uint8Array.from(account.discriminator), encodeBorsh(idl, { defined: { name } }, value));
+}
+
+function decodeScalar(type, data, at) {
+  const size = UINT[type] ?? INT[type];
+  if (size && at + size > data.length) throw new RangeError('read past the end of the data');
+  if (INT[type]) return [readIntLE(data, at, size), at + size];
+  if (size >= 8) return [readUintLE(data, at, size), at + size];
+  if (size) return [Number(readUintLE(data, at, size)), at + size];
+  if (type === 'bool') {
+    if (at >= data.length) throw new RangeError('read past the end of the data');
+    return [data[at] !== 0, at + 1];
+  }
+  if (type === 'pubkey') {
+    if (at + ADDRESS_BYTES > data.length) throw new RangeError('read past the end of the data');
+    return [encodeBase58(data.subarray(at, at + ADDRESS_BYTES)), at + ADDRESS_BYTES];
+  }
+  if (type === 'string') {
+    const length = Number(readUintLE(data, at, 4));
+    if (at + 4 + length > data.length) throw new RangeError('string runs past the end of the data');
+    return [fromUtf8(data.subarray(at + 4, at + 4 + length)), at + 4 + length];
+  }
+  if (type === 'bytes') {
+    const length = Number(readUintLE(data, at, 4));
+    if (at + 4 + length > data.length) throw new RangeError('bytes run past the end of the data');
+    return [data.slice(at + 4, at + 4 + length), at + 4 + length];
+  }
+  throw new Error(`Unsupported IDL type ${type}`);
+}
+
+function decodeList(idl, inner, length, data, at) {
+  const items = [];
+  let offset = at;
+  for (let i = 0; i < length; i++) {
+    const [item, next] = decodeAt(idl, inner, data, offset);
+    items.push(item);
+    offset = next;
+  }
+  return [items, offset];
+}
+
+function decodeDefined(idl, name, data, at) {
+  const def = typeDef(idl, name).type;
+  if (def.kind === 'enum') {
+    const variant = def.variants[data[at]];
+    if (!variant) throw new Error(`${name}: unknown variant ${data[at]}`);
+    const fields = variant.fields ?? [];
+    if (!fields.length) return [variant.name, at + 1];
+    let offset = at + 1;
+    const named = isNamed(fields);
+    const payload = named ? {} : [];
+    fields.forEach((f, i) => {
+      let value;
+      [value, offset] = decodeAt(idl, named ? f.type : f, data, offset);
+      if (named) payload[f.name] = value;
+      else payload[i] = value;
+    });
+    return [{ [variant.name]: payload }, offset];
+  }
+  const record = {};
+  let offset = at;
+  for (const field of def.fields) [record[field.name], offset] = decodeAt(idl, field.type, data, offset);
+  return [record, offset];
+}
+
+function decodeAt(idl, type, data, at) {
+  if (typeof type === 'string') return decodeScalar(type, data, at);
+  if ('array' in type) {
+    const [inner, length] = type.array;
+    if (inner === 'u8') {
+      if (at + length > data.length) throw new RangeError('read past the end of the data');
+      return [data.slice(at, at + length), at + length];
+    }
+    return decodeList(idl, inner, length, data, at);
+  }
+  if ('vec' in type) {
+    const length = Number(readUintLE(data, at, 4));
+    if (length > data.length) throw new RangeError('vec longer than the data');
+    return decodeList(idl, type.vec, length, data, at + 4);
+  }
+  if ('option' in type) {
+    if (at >= data.length) throw new RangeError('read past the end of the data');
+    return data[at] === 0 ? [null, at + 1] : decodeAt(idl, type.option, data, at + 1);
+  }
+  return decodeDefined(idl, type.defined.name, data, at);
+}
+
+/** One value of `type` at `offset`: [value, next offset]. */
+export const decodeBorsh = (idl, type, data, offset = 0) => decodeAt(idl, type, data, offset);
+
+const startsWith = (data, prefix) => data.length >= prefix.length && equalBytes(data.subarray(0, prefix.length), Uint8Array.from(prefix));
+
+/** An account of the named type, after checking its discriminator. Bytes after the fields are left alone. */
+export function decodeAccount(idl, name, data) {
+  const account = idl.accounts.find((a) => a.name === name);
+  if (!account) throw new Error(`Unknown account type ${name}`);
+  if (!startsWith(data, account.discriminator)) throw new Error(`Not a ${name} account`);
+  return decodeDefined(idl, name, data, account.discriminator.length)[0];
+}
+
+/** Whether the data starts with the named account's discriminator. */
+export function isAccount(idl, name, data) {
+  const account = idl.accounts.find((a) => a.name === name);
+  return Boolean(account) && startsWith(data, account.discriminator);
+}
+
+/**
+ * The program's Anchor events in a transaction's logs (`Program data: <base64 of discriminator + Borsh>`):
+ * [{ name, data }]. Only lines the program itself printed count: the log names which program each line comes from
+ * (`Program <id> invoke [n]` … `success`), and any program can print a line that looks like an event. Logs alone
+ * cannot say whether the transaction succeeded (the runtime can fail it after every instruction logged success), so
+ * the caller decides that from the transaction's `meta.err` and reads events only when it is null.
+ */
+export function decodeEvents(idl, logs) {
+  const out = [];
+  const stack = [];
+  for (const line of logs ?? []) {
+    const invoke = /^Program (\w+) invoke \[\d+\]$/.exec(line);
+    if (invoke) {
+      stack.push(invoke[1]);
+      continue;
+    }
+    if (/^Program \w+ failed/.test(line)) return [];
+    if (/^Program \w+ success$/.test(line)) {
+      stack.pop();
+      continue;
+    }
+    const m = /^Program data: (.+)$/.exec(line);
+    if (!m || stack[stack.length - 1] !== idl.address) continue;
+    let bytes;
+    try {
+      bytes = fromBase64(m[1]);
+    } catch {
+      continue;
+    }
+    const event = (idl.events ?? []).find((e) => startsWith(bytes, e.discriminator));
+    if (event) out.push({ name: event.name, data: decodeDefined(idl, event.name, bytes, event.discriminator.length)[0] });
+  }
+  return out;
+}

package/js/chain/bytes.js

@@ -0,0 +1,141 @@
+// Byte helpers shared by browser apps and Node. Plain Uint8Array, never Node's Buffer, so they run in a browser page
+// too.
+
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+/** btoa/atob take strings of at most this many code units comfortably. */
+const BASE64_CHUNK = 0x8000;
+
+/** UTF-8 bytes of a string. */
+export const utf8 = (text) => encoder.encode(text);
+
+/** A string from UTF-8 bytes. */
+export const fromUtf8 = (bytes) => decoder.decode(bytes);
+
+/** The parts, one after another. */
+export function concat(...parts) {
+  const out = new Uint8Array(parts.reduce((n, p) => n + p.length, 0));
+  let at = 0;
+  for (const part of parts) {
+    out.set(part, at);
+    at += part.length;
+  }
+  return out;
+}
+
+/** Lexicographic order of two byte strings (like Buffer.compare): -1, 0 or 1. */
+export function compareBytes(a, b) {
+  const n = Math.min(a.length, b.length);
+  for (let i = 0; i < n; i++) if (a[i] !== b[i]) return a[i] < b[i] ? -1 : 1;
+  return a.length === b.length ? 0 : a.length < b.length ? -1 : 1;
+}
+
+/** Whether two byte strings are equal. */
+export function equalBytes(a, b) {
+  if (!a || !b || a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i++) if (a[i] !== b[i]) return false;
+  return true;
+}
+
+export function toBase64(bytes) {
+  let text = '';
+  for (let i = 0; i < bytes.length; i += BASE64_CHUNK) text += String.fromCharCode(...bytes.subarray(i, i + BASE64_CHUNK));
+  return btoa(text);
+}
+
+/** Standard base64 to bytes; throws on anything that is not base64. */
+export function fromBase64(text) {
+  if (typeof text !== 'string' || !/^[A-Za-z0-9+/]*={0,2}$/.test(text)) throw new Error('Not base64');
+  return Uint8Array.from(atob(text), (c) => c.charCodeAt(0));
+}
+
+export const toHex = (bytes) => Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('');
+
+export function fromHex(text) {
+  if (typeof text !== 'string' || text.length % 2 || /[^0-9a-f]/i.test(text)) throw new Error('Not hex');
+  const out = new Uint8Array(text.length / 2);
+  for (let i = 0; i < out.length; i++) out[i] = parseInt(text.slice(i * 2, i * 2 + 2), 16);
+  return out;
+}
+
+/**
+ * Little-endian unsigned integer of `size` bytes, as Borsh and the Solana wire format write them. `value` is a bigint,
+ * or a number that is a safe integer: a larger number has already lost its low digits, so it is refused rather than
+ * written as some other value.
+ */
+export function uintLE(value, size) {
+  const out = new Uint8Array(size);
+  let rest = toBigInt(value);
+  if (rest < 0n || rest >= 1n << BigInt(size * 8)) throw new RangeError(`${value} does not fit in ${size} bytes`);
+  for (let i = 0; i < size; i++) {
+    out[i] = Number(rest & 0xffn);
+    rest >>= 8n;
+  }
+  return out;
+}
+
+/**
+ * Little-endian signed (two's complement) integer of `size` bytes, as Borsh writes an i32 or an i64. `value` as
+ * `uintLE` takes it; one outside the signed range is refused rather than wrapped.
+ */
+export function intLE(value, size) {
+  const v = toBigInt(value);
+  const bits = BigInt(size * 8);
+  if (v < -(1n << (bits - 1n)) || v >= 1n << (bits - 1n)) throw new RangeError(`${value} does not fit in a signed ${size}-byte integer`);
+  return uintLE(v < 0n ? v + (1n << bits) : v, size);
+}
+
+/**
+ * `value` as a bigint: a bigint, a number that is a safe integer, or a string of digits. A number past 2^53 has already
+ * lost its low digits, so it is refused rather than turned into some other value.
+ */
+export function toBigInt(value) {
+  if (typeof value === 'number' && !Number.isSafeInteger(value)) throw new RangeError(`${value} is not a safe integer: pass it as a bigint`);
+  return BigInt(value);
+}
+
+/** A little-endian unsigned integer of `size` bytes at `offset`, as a bigint. */
+export function readUintLE(bytes, offset, size) {
+  if (offset < 0 || offset + size > bytes.length) throw new RangeError('read past the end of the data');
+  let value = 0n;
+  for (let i = size - 1; i >= 0; i--) value = (value << 8n) | BigInt(bytes[offset + i]);
+  return value;
+}
+
+/** Solana's compact-u16 length prefix. */
+export function compactU16(value) {
+  if (!Number.isInteger(value) || value < 0 || value > 0xffff) throw new RangeError('compact-u16 out of range');
+  const out = [];
+  let rest = value;
+  for (;;) {
+    const low = rest & 0x7f;
+    rest >>= 7;
+    if (rest === 0) {
+      out.push(low);
+      return Uint8Array.from(out);
+    }
+    out.push(low | 0x80);
+  }
+}
+
+/**
+ * A compact-u16 at `offset`: its value and how many bytes it took. Like Solana, it refuses a value past 0xffff and a
+ * longer form of a value that has a shorter one.
+ */
+export function readCompactU16(bytes, offset) {
+  let value = 0;
+  for (let size = 0; size < 3; size++) {
+    const byte = bytes[offset + size];
+    if (byte === undefined) throw new RangeError('truncated length prefix');
+    if (size > 0 && byte === 0) throw new RangeError('length prefix is longer than it needs to be');
+    value |= (byte & 0x7f) << (7 * size);
+    if ((byte & 0x80) === 0) {
+      if (value > 0xffff) throw new RangeError('length prefix past 0xffff');
+      return { value, size: size + 1 };
+    }
+  }
+  throw new RangeError('length prefix too long');
+}
+
+/** Random bytes from the platform's CSPRNG (WebCrypto in browsers and Node 24). */
+export const randomBytes = (n) => globalThis.crypto.getRandomValues(new Uint8Array(n));

package/js/chain/core.js

@@ -0,0 +1,181 @@
+// Metaplex Core: a project's collection (created by its owner's wallet, with the loot project as update delegate) and
+// reading a Core asset (owner, collection, name, uri, attributes, freeze state). The layouts are Core's own, checked
+// against the real Core program in the tests.
+import { addressBytes, encodeBase58 } from './base58.js';
+import { concat, fromUtf8, readUintLE, uintLE, utf8 } from './bytes.js';
+import { MPL_CORE_PROGRAM, SYSTEM_PROGRAM } from './pda.js';
+import { meta } from './programs.js';
+
+export { MPL_CORE_PROGRAM };
+/** MPL Core `CreateCollectionV2`. */
+const CREATE_COLLECTION_V2 = 21;
+const PLUGIN = { Royalties: 0, FreezeDelegate: 1, UpdateDelegate: 4, PermanentFreezeDelegate: 5, Attributes: 6, BubblegumV2: 15 };
+const ASSET_V1 = 1;
+const COLLECTION_V1 = 5;
+const PLUGIN_HEADER = 3;
+const UPDATE_AUTHORITY_COLLECTION = 2;
+
+/** A Borsh string as Core writes it. */
+const coreString = (text) => {
+  const bytes = utf8(text);
+  return concat(uintLE(bytes.length, 4), bytes);
+};
+
+/**
+ * A project's Core collection. The creator is its update authority and royalty receiver; the loot project's address
+ * (`project`, for example `pda.project(creator, 0)` from the client) is an update delegate so the program can mint into it. `compressed`:
+ * it also carries Bubblegum's plugin, so compressed NFTs can be minted into it. The collection address signs too (a
+ * fresh key).
+ */
+export function createCollectionInstruction({ collection, creator, name, uri, royaltyBps = 500, project, compressed = false }) {
+  if (!project) throw new Error('createCollectionInstruction needs the loot project that mints into the collection (`project`).');
+  const data = concat(
+    Uint8Array.of(CREATE_COLLECTION_V2),
+    coreString(name),
+    coreString(uri),
+    Uint8Array.of(1), // plugins: Some
+    uintLE(compressed ? 3 : 2, 4),
+    // Royalties { basis_points, creators: [creator 100%], rule_set: None }, authority: default.
+    Uint8Array.of(PLUGIN.Royalties),
+    uintLE(royaltyBps, 2),
+    uintLE(1, 4),
+    addressBytes(creator),
+    Uint8Array.of(100, 0, 0),
+    // UpdateDelegate { additional_delegates: [the project] }, authority: default.
+    Uint8Array.of(PLUGIN.UpdateDelegate),
+    uintLE(1, 4),
+    addressBytes(project),
+    Uint8Array.of(0),
+    // BubblegumV2 {}, authority: default.
+    compressed ? Uint8Array.of(PLUGIN.BubblegumV2, 0) : new Uint8Array(0),
+    Uint8Array.of(0), // external plugin adapters: None
+  );
+  return {
+    programId: MPL_CORE_PROGRAM,
+    keys: [
+      meta(collection, true, true),
+      meta(creator, false, false),
+      meta(creator, true, true),
+      meta(SYSTEM_PROGRAM, false, false),
+    ],
+    data,
+  };
+}
+
+function reader(data, start) {
+  let at = start;
+  const need = (n) => {
+    if (at + n > data.length) throw new RangeError('read past the end of the account');
+  };
+  return {
+    get at() {
+      return at;
+    },
+    skip(n) {
+      at += n;
+    },
+    byte() {
+      need(1);
+      return data[at++];
+    },
+    u32() {
+      need(4);
+      const v = Number(readUintLE(data, at, 4));
+      at += 4;
+      return v;
+    },
+    u64() {
+      need(8);
+      const v = readUintLE(data, at, 8);
+      at += 8;
+      return v;
+    },
+    address() {
+      need(32);
+      const v = encodeBase58(data.subarray(at, at + 32));
+      at += 32;
+      return v;
+    },
+    text() {
+      const n = this.u32();
+      need(n);
+      const v = fromUtf8(data.subarray(at, at + n));
+      at += n;
+      return v;
+    },
+  };
+}
+
+function readAttributes(data, offset) {
+  const r = reader(data, offset + 1);
+  const out = {};
+  const count = r.u32();
+  for (let i = 0; i < count; i++) {
+    const key = r.text();
+    out[key] = r.text();
+  }
+  return out;
+}
+
+/** Decode a Core AssetV1: { owner, collection, name, uri, attributes, frozen, soulbound }. */
+export function parseCoreAsset(data) {
+  if (data[0] !== ASSET_V1) throw new Error('Not a Core asset');
+  const r = reader(data, 1);
+  const owner = r.address();
+  const authorityKind = r.byte();
+  const authority = authorityKind === 0 ? null : r.address();
+  const asset = {
+    owner,
+    collection: authorityKind === UPDATE_AUTHORITY_COLLECTION ? authority : null,
+    name: r.text(),
+    uri: r.text(),
+    attributes: {},
+    frozen: false,
+    soulbound: false,
+  };
+  r.skip(data[r.at] === 1 ? 9 : 1); // seq: Option<u64>
+  if (r.at >= data.length || data[r.at] !== PLUGIN_HEADER) return asset;
+  r.skip(1);
+  const registry = reader(data, Number(r.u64()) + 1);
+  const plugins = registry.u32();
+  for (let i = 0; i < plugins; i++) {
+    const type = registry.byte();
+    if (registry.byte() === 3) registry.skip(32);
+    const offset = Number(registry.u64());
+    if (type === PLUGIN.Attributes) asset.attributes = readAttributes(data, offset);
+    if (type === PLUGIN.PermanentFreezeDelegate) asset.soulbound = data[offset + 1] === 1;
+    if (type === PLUGIN.FreezeDelegate) asset.frozen ||= data[offset + 1] === 1;
+  }
+  asset.frozen ||= asset.soulbound;
+  return asset;
+}
+
+/** Decode the start of a Core CollectionV1: { updateAuthority, name, uri, numMinted, currentSize, bubblegum (whether it
+ * carries Bubblegum's plugin, BubblegumV2: compressed NFTs can be minted into it) }. */
+export function parseCoreCollection(data) {
+  if (data[0] !== COLLECTION_V1) throw new Error('Not a Core collection');
+  const r = reader(data, 1);
+  const updateAuthority = r.address();
+  const name = r.text();
+  const uri = r.text();
+  const out = { updateAuthority, name, uri, numMinted: r.u32(), currentSize: r.u32(), bubblegum: false };
+  if (r.at >= data.length || data[r.at] !== PLUGIN_HEADER) return out;
+  r.skip(1);
+  const registry = reader(data, Number(r.u64()) + 1);
+  const plugins = registry.u32();
+  for (let i = 0; i < plugins; i++) {
+    const type = registry.byte();
+    if (registry.byte() === 3) registry.skip(32);
+    registry.u64();
+    if (type === PLUGIN.BubblegumV2) out.bubblegum = true;
+  }
+  return out;
+}
+
+/** getProgramAccounts filters for Core assets owned by `owner` in `collection` (no indexer needed). */
+export const ownedAssetFilters = (owner, collection) => [
+  { memcmp: { offset: 0, bytes: encodeBase58(Uint8Array.of(ASSET_V1)) } },
+  { memcmp: { offset: 1, bytes: owner } },
+  { memcmp: { offset: 33, bytes: encodeBase58(Uint8Array.of(UPDATE_AUTHORITY_COLLECTION)) } },
+  { memcmp: { offset: 34, bytes: collection } },
+];