sememe 0.0.0-stage → 0.4.22

package/src/ata-interface.mjs

@@ -0,0 +1,276 @@
+// Derive the SPL Associated Token Account wire table from the VENDORED
+// UPSTREAM RUST.
+//
+// Same contract as src/native-interface.mjs / src/token-interface.mjs /
+// src/raydium-interface.mjs: this program publishes NO IDL account to pull
+// (measured 2026-11-11 over 6 finalized mainnet blocks: 1,410 payloads, the
+// single largest acquisition gap in research/ecosystem-coverage-2026-11-11.json,
+// acquirable=false at both pullable addresses). Its interface is the upstream
+// Rust sources, and its wire rule is small enough to be pinned exactly:
+//
+//   - interface/src/instruction.rs declares `AssociatedTokenAccountInstruction`
+//     as a borsh UNIT enum: Create, CreateIdempotent, RecoverNested. The
+//     instruction payload is borsh's own enum encoding — the variant index,
+//     ONE byte, and no args — and the borsh serialise arms are the ground
+//     truth for the tag: an index pushed with `push(idx)` in serialise is
+//     the wire byte, and a declaration that no arm pushes is an upstream
+//     addition nobody re-reviewed (it fails loudly instead of decoding as
+//     "unknown").
+//   - program/src/processor.rs is the RUNTIME verdict: `input.is_empty()` is
+//     executed as `Create` (the empty payload the measurement saw 4 times is
+//     a real instruction the chain runs, not a refusal), everything else is
+//     judged by `try_from_slice`, and an unjudged input is
+//     ProgramError::InvalidInstructionData — a named refusal, never a guess.
+//
+// Why derive instead of transcribe: the System/ComputeBudget table was once
+// hand-typed, and the transcription carried a defect that survived review.
+// Three variants is small, but the rule that held is the same: the table is
+// derived from upstream's own text, both directions are cross-checked, and
+// every vendored file is hashed so a swapped source refuses the load.
+//
+// Dependency-free on purpose: it is imported by the decode path.
+
+import { readFileSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+export const REPO_ROOT = path.resolve(HERE, '..');
+
+export const ATA_PINS = {
+  interface: {
+    repo: 'solana-program/associated-token-account',
+    dir: 'spl-associated-token-account',
+    pin: 'fbf5379e7398ac8b231c73ee8a9ff677b43dd0ec',
+    license: 'Apache-2.0 (LICENSE vendored beside the sources)',
+    files: [
+      { file: 'interface/src/instruction.rs', role: 'AssociatedTokenAccountInstruction: borsh unit enum, serialise arms carry the wire byte' },
+      { file: 'program/src/processor.rs', role: 'runtime verdict: empty input falls back to Create, borsh try_from_slice judges the rest, InvalidInstructionData refuses' },
+      { file: 'interface/src/lib.rs', role: 'the program id (declare_id), read from upstream, not re-typed' },
+    ],
+  },
+};
+
+export const ATA_PROGRAM = 'ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL';
+
+const stripComments = (src) => src.replace(/\/\*[\s\S]*?\*\//g, '').replace(/\/\/[^\n]*/g, '');
+
+/** The body of a `fn ...` / `impl ...` block from comment-stripped source. */
+function blockBody(src, signature) {
+  const at = src.indexOf(signature);
+  if (at < 0) throw Error(`block not found: ${signature}`);
+  const open = src.indexOf('{', at);
+  let depth = 0;
+  for (let i = open; i < src.length; i++) {
+    if (src[i] === '{') depth++;
+    else if (src[i] === '}') {
+      depth--;
+      if (depth === 0) return src.slice(open + 1, i);
+    }
+  }
+  throw Error(`${signature}: body never closes`);
+}
+
+/**
+ * The declared variants of `pub enum AssociatedTokenAccountInstruction`, in
+ * declaration order, with the declared field list (a unit variant has none).
+ * A tuple or struct variant is an upstream shape this module does not pin:
+ * it throws instead of inventing an encoding for it.
+ */
+export function parseAtaVariants(src) {
+  // Upstream annotates variants with multi-line `#[cfg_attr(...)]` and doc
+  // attributes; they are not declarations and must go before the split.
+  src = src.replace(/#\[[\s\S]*?\]\s*/g, '');
+  const at = src.indexOf('pub enum AssociatedTokenAccountInstruction');
+  if (at < 0) throw Error('AssociatedTokenAccountInstruction enum not found');
+  const open = src.indexOf('{', at);
+  let depth = 0, end = -1;
+  for (let i = open; i < src.length; i++) {
+    if (src[i] === '{') depth++;
+    else if (src[i] === '}') {
+      depth--;
+      if (depth === 0) { end = i; break; }
+    }
+  }
+  const body = src.slice(open + 1, end);
+  const variants = [];
+  for (const part of body.split(',')) {
+    const trimmed = part.trim();
+    if (!trimmed) continue;
+    const unit = trimmed.match(/^([A-Z][A-Za-z0-9_]*)$/);
+    if (unit) { variants.push({ name: unit[1], fields: [] }); continue; }
+    if (/^[A-Z][A-Za-z0-9_]*\s*[({]/.test(trimmed)) {
+      throw Error(`AssociatedTokenAccountInstruction: variant "${trimmed}" is not a unit variant — this module pins unit enums only; re-review the pin`);
+    }
+    throw Error(`AssociatedTokenAccountInstruction: unreadable variant "${trimmed}"`);
+  }
+  if (!variants.length) throw Error('AssociatedTokenAccountInstruction yielded no variants');
+  return variants;
+}
+
+/**
+ * The wire byte of each variant, read from upstream's OWN builders.
+ *
+ * The borsh `serialise` is macro-generated, so it is not in the source text —
+ * but upstream's instruction builders are, and each one writes the payload
+ * byte it means to send together with the variant it means:
+ *
+ *   data: vec![2], // AssociatedTokenAccountInstruction::RecoverNested
+ *   ... build_associated_token_account_instruction(..., 0, // ...::Create
+ *
+ * So the wire byte is upstream's own literal, cross-checked against the
+ * declaration index upstream's borsh derive would use (the index in the
+ * enum's declaration order). Both must agree: a builder that writes a byte
+ * the declaration index does not carry is an upstream shape this module does
+ * not pin, and it fails loudly instead of decoding as "unknown".
+ */
+function deriveWireTags(rawSrc, variantNames) {
+  const src = rawSrc;
+  const wires = new Map();
+  // (a) the literal payload bytes of the builders, with the named variant
+  const push = (byte, name, how) => {
+    if (wires.has(name)) {
+      if (wires.get(name).tag !== byte) {
+        throw Error(`upstream writes ${name} with two different bytes (${wires.get(name).tag} and ${byte})`);
+      }
+      return;
+    }
+    wires.set(name, { tag: byte, how });
+  };
+  for (const m of src.matchAll(
+    /data:\s*vec!\[(\d+)\]\s*,?\s*\/\/\s*AssociatedTokenAccountInstruction::([A-Za-z0-9_]+)/g,
+  )) {
+    push(Number(m[1]), m[2], 'data: vec![byte] in the instruction builder');
+  }
+  for (const m of src.matchAll(
+    /(\d+)\s*,\s*\/\/\s*AssociatedTokenAccountInstruction::([A-Za-z0-9_]+)/g,
+  )) {
+    push(Number(m[1]), m[2], 'the instruction byte passed to the builder');
+  }
+
+  // Every declared variant must be written by upstream somewhere, and every
+  // written name must be a declared variant.
+  for (const [index, name] of variantNames.entries()) {
+    if (!wires.has(name)) {
+      throw Error(`variant ${name} (index ${index}) is declared upstream but no builder writes it — upstream added a variant this table does not pin`);
+    }
+    if (wires.get(name).tag !== index) {
+      throw Error(`upstream writes ${name} with byte ${wires.get(name).tag}, but its declaration index is ${index} — this module pins the borsh index encoding only`);
+    }
+  }
+  for (const name of wires.keys()) {
+    if (!variantNames.includes(name)) {
+      throw Error(`upstream writes ${name}, which the enum does not declare`);
+    }
+  }
+  return wires;
+}
+
+/** The processor's own runtime verdict, read out of the vendored text. */
+function deriveRuntime(src, variantNames) {
+  const processBody = blockBody(src, 'pub fn process_instruction');
+
+  // `let instruction = if input.is_empty() { <Fallback> } else { ... }`
+  const fallback = processBody.match(
+    /if input\.is_empty\(\)\s*\{\s*AssociatedTokenAccountInstruction::([A-Za-z0-9_]+)\s*\}/,
+  );
+  if (!fallback) throw Error('processor: the empty-input branch is not the shape this module pins');
+  const emptyInputFallback = fallback[1];
+  if (!variantNames.includes(emptyInputFallback)) {
+    throw Error(`processor: empty-input fallback ${emptyInputFallback} is not a declared variant`);
+  }
+
+  // The judge: borsh `try_from_slice`, refusal mapped to InvalidInstructionData.
+  if (!/try_from_slice\(input\)/.test(processBody)) {
+    throw Error('processor: borsh try_from_slice is not the judge this module pins');
+  }
+  if (!/InvalidInstructionData/.test(processBody)) {
+    throw Error('processor: the unjudged-input refusal (InvalidInstructionData) is missing');
+  }
+
+  return {
+    judge: 'borsh AssociatedTokenAccountInstruction::try_from_slice(input)',
+    emptyInputFallback,
+    unknownInputRefusal: 'ProgramError::InvalidInstructionData',
+    source: 'program/src/processor.rs at the pin',
+  };
+}
+
+/** The program id, read from the vendored `declare_id!`, not re-typed. */
+function deriveProgramId(src) {
+  const m = src.match(/declare_id!\("([1-9A-HJ-NP-Za-km-z]{32,44})"\)/);
+  if (!m) throw Error('interface/src/lib.rs: no declare_id! found');
+  return m[1];
+}
+
+/** Derive the ATA interface document from the vendored upstream sources. */
+export function deriveAtaInterface(spec, { root = REPO_ROOT } = {}) {
+  const base = path.join(root, 'vendor', ATA_PINS.interface.dir, ATA_PINS.interface.pin);
+  const files = ATA_PINS.interface.files.map((entry) => {
+    const raw = readFileSync(path.join(base, entry.file));
+    return { ...entry, sha256: `sha256:${createHash('sha256').update(raw).digest('hex')}` };
+  });
+
+  const instructionRaw = readFileSync(path.join(base, 'interface/src/instruction.rs'), 'utf8');
+  const instructionSrc = stripComments(instructionRaw);
+  const processorSrc = stripComments(
+    readFileSync(path.join(base, 'program/src/processor.rs'), 'utf8'),
+  );
+  const libSrc = readFileSync(path.join(base, 'interface/src/lib.rs'), 'utf8');
+
+  const program = deriveProgramId(libSrc);
+  if (program !== spec.expectedProgram) {
+    throw Error(`upstream declares program ${program}, this table pins ${spec.expectedProgram}`);
+  }
+
+  const variants = parseAtaVariants(instructionSrc);
+  const wires = deriveWireTags(instructionRaw, variants.map((v) => v.name));
+  const runtime = deriveRuntime(processorSrc, variants.map((v) => v.name));
+
+  const instructions = variants.map((variant) => ({
+    tag: wires.get(variant.name).tag,
+    name: variant.name,
+    wire: 'borsh-unit-enum',
+    args: [],
+  }));
+
+  return {
+    program,
+    label: spec.label,
+    scheme: 'native-ata',
+    source: {
+      repo: ATA_PINS.interface.repo,
+      pin: ATA_PINS.interface.pin,
+      license: ATA_PINS.interface.license,
+      enum: 'AssociatedTokenAccountInstruction (borsh unit enum: the variant index is the one-byte payload)',
+      programSource: 'vendored interface/src/lib.rs declare_id',
+      files,
+      vendoredAt: `vendor/${ATA_PINS.interface.dir}/${ATA_PINS.interface.pin}`,
+      derivation: 'src/ata-interface.mjs: tag = the declaration index upstream\'s borsh serialise arm pushes; args = none (unit enum); runtime verdicts read from the processor (empty input falls back to Create, borsh try_from_slice judges, InvalidInstructionData refuses)',
+    },
+    runtime,
+    selector: {
+      width: 1,
+      encoding: 'borsh enum index, u8; empty input is the processor\'s own Create fallback, not an unknown selector',
+    },
+    argEncoding: 'unit enum: payload is exactly the one index byte; no argument bytes',
+    instructions,
+  };
+}
+
+/** The pinned ATA spec. The expected program is the opinion layer; the
+ * derivation checks it against upstream's own declare_id. */
+export const ATA_SPEC = {
+  program: ATA_PROGRAM,
+  expectedProgram: ATA_PROGRAM,
+  label: 'SPL Associated Token Account',
+};
+
+/** sha256 of a vendored upstream file, as `sha256:<hex>`. */
+export function vendoredAtaHash(file, { root = REPO_ROOT } = {}) {
+  const raw = readFileSync(
+    path.join(root, 'vendor', ATA_PINS.interface.dir, ATA_PINS.interface.pin, file),
+  );
+  return `sha256:${createHash('sha256').update(raw).digest('hex')}`;
+}

package/src/ata.mjs

@@ -0,0 +1,223 @@
+// The SPL Associated Token Account decoder: the vendored-upstream path for
+// the program with the LARGEST measured acquisition gap.
+//
+// Why this file exists: measured 2026-11-11 across 6 finalized mainnet
+// blocks, ATokenGPvbd... carried 1,410 watched payloads and answered at
+// NEITHER pullable IDL address — research/ecosystem-coverage-2026-11-11.json
+// lists it first in its acquisition queue: "no on-chain IDL at either
+// address; needs a first-party published copy or a vendored upstream source".
+// Its interface is the upstream Rust, so the wire table is derived from the
+// vendored sources by src/ata-interface.mjs and committed as a reviewable
+// artifact (`interface/ata-<program>.json`).
+//
+// Ground truth chain, every row derived and then VERIFIED, not typed:
+//   1. INTERFACE  solana-program/associated-token-account@fbf5379
+//                 interface/src/instruction.rs (AssociatedTokenAccountInstruction)
+//                 program/src/processor.rs       (the runtime verdict)
+//                 interface/src/lib.rs           (declare_id -> program id)
+//                 DERIVED by tools/ata-interface.mjs into
+//                 interface/ata-<program>.json. This module reads the
+//                 artifact at load and re-hashes every vendored file against
+//                 the sha256 the artifact claims; a mismatch REFUSES the load
+//                 instead of decoding from it — the two-check contract
+//                 src/native.mjs, src/token.mjs and src/raydium.mjs proved.
+//   2. WIRE       borsh's enum encoding of a UNIT enum: the payload is the
+//                 one-byte variant index, and no argument bytes follow. The
+//                 index upstream's builders write (data: vec![2], // ...::RecoverNested)
+//                 is cross-checked against the declaration index at
+//                 derivation time.
+//   3. RUNTIME    the pin's processor: `input.is_empty()` is executed as
+//                 `Create` — so an EMPTY payload is a named Create, exactly
+//                 what upstream runs, not an "unknown-selector" refusal;
+//                 everything else is judged by `try_from_slice`, and an
+//                 unjudged input is ProgramError::InvalidInstructionData —
+//                 this module refuses it under the same name.
+//
+// What is deliberately NOT claimed: no account list, no address derivation
+// (see upstream address.rs), no state layout — only instruction data. The
+// table describes the program AT THE PIN.
+//
+// Strictness mirrors src/token.mjs: an unknown selector, a truncated payload
+// or a payload with trailing bytes is a refusal with a named reason — never
+// a confident wrong label.
+
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { deriveAtaInterface, ATA_SPEC, ATA_PINS, ATA_PROGRAM, vendoredAtaHash } from './ata-interface.mjs';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const ROOT = path.resolve(HERE, '..');
+
+export { ATA_PROGRAM };
+
+/**
+ * Load the ATA interface: DERIVE it from the vendored upstream Rust, then
+ * require the committed artifact to agree with the derivation byte for byte.
+ *
+ * Two checks, deliberately (the contract the three sibling modules proved):
+ *   - the derivation runs against the vendored bytes themselves, so a swapped
+ *     or edited source file cannot silently change the table it describes;
+ *   - the committed artifact must equal that derivation, so a tampered or
+ *     stale artifact refuses the load instead of decoding from it.
+ */
+function loadInterface(spec) {
+  const artifactPath = path.join(ROOT, 'interface', `ata-${spec.program}.json`);
+  const derived = deriveAtaInterface(spec);
+  let current;
+  try {
+    current = readFileSync(artifactPath, 'utf8');
+  } catch (error) {
+    throw new Error(`ata interface artifact for ${spec.label} is missing: ${error.message}`);
+  }
+  const expected = `${JSON.stringify(derived, null, 2)}\n`;
+  if (current !== expected) {
+    const claimed = derived.source.files.map((entry) => entry.sha256).join(', ');
+    throw new Error(
+      `ata interface for ${spec.label} refuses to load: interface/ata-${spec.program}.json does not equal ` +
+      `a fresh derivation of ${derived.source.file ?? 'the vendored sources'} (${claimed}, hashed now: ` +
+      `${derived.source.files.map((entry) => vendoredAtaHash(entry.file)).join(', ')})`,
+    );
+  }
+  if (!derived.instructions.length || !derived.selector?.width) {
+    throw new Error(`ata interface artifact for ${spec.label} is malformed`);
+  }
+  return derived;
+}
+
+const ARTIFACT = loadInterface(ATA_SPEC);
+const BY_TAG = new Map(ARTIFACT.instructions.map((entry) => [entry.tag, entry]));
+const EMPTY_TAG = ARTIFACT.instructions.find(
+  (entry) => entry.name === ARTIFACT.runtime.emptyInputFallback,
+)?.tag;
+
+export class AtaCodecError extends Error {
+  constructor(reason, detail) {
+    super(detail ? `${reason}: ${detail}` : reason);
+    this.name = 'AtaCodecError';
+    this.reason = reason;
+  }
+}
+
+/** Whether `program` is the ATA program this module owns. */
+export function isAtaProgram(program) {
+  return program === ARTIFACT.program;
+}
+
+/** Program ids this module can decode, for callers that enumerate. */
+export function ataPrograms() {
+  return [ARTIFACT.program];
+}
+
+/** Provenance for the ATA table. */
+export function ataProvenance(program = ATA_PROGRAM) {
+  if (!isAtaProgram(program)) return null;
+  return {
+    label: ARTIFACT.label,
+    interface: `${ARTIFACT.source.repo}@${ARTIFACT.source.pin.slice(0, 8)} ${ARTIFACT.source.files[0].file} ${ARTIFACT.source.enum}`,
+    encoding: ARTIFACT.argEncoding,
+    runtime: `${ARTIFACT.runtime.judge}; ${ARTIFACT.runtime.emptyInputFallback} = the empty-input fallback; unjudged input is ${ARTIFACT.runtime.unknownInputRefusal}`,
+    license: ARTIFACT.source.license,
+    variants: ARTIFACT.instructions.length,
+  };
+}
+
+/**
+ * Decode one ATA instruction payload.
+ *
+ * Returns `{ refused: 'not-ata' }` when the caller was never supposed to ask,
+ * a named result when the bytes are upstream's own, and throws AtaCodecError
+ * with a named reason when the bytes cannot honestly be named — the same
+ * tri-state contract as src/token.mjs.
+ */
+export function decodeAtaInstruction(program, bytes, { trailing = 'report' } = {}) {
+  if (!isAtaProgram(program)) return { refused: 'not-ata' };
+  if (!(bytes instanceof Uint8Array)) {
+    throw new AtaCodecError('empty-payload', `${program}: no instruction data`);
+  }
+
+  // Upstream's own runtime rule, read from the pin's processor: an empty
+  // input IS a Create. Refusing it as "unknown-selector" would be a true
+  // statement about a table and a false one about the program.
+  if (bytes.length === 0) {
+    if (EMPTY_TAG === undefined) {
+      throw new AtaCodecError('empty-payload', `${program}: no instruction data and no empty-input fallback is pinned`);
+    }
+    return {
+      name: ARTIFACT.runtime.emptyInputFallback,
+      tag: EMPTY_TAG,
+      selectorWidth: 0,
+      args: {},
+      consumed: 0,
+      bytes: 0,
+      trailing: { count: 0 },
+      roundTripByteExact: EMPTY_TAG !== undefined && encodeAtaInstruction(program, ARTIFACT.runtime.emptyInputFallback).equals(Buffer.from(bytes)),
+      scheme: 'native-ata',
+      source: 'pinned-vendored-upstream',
+      note: 'empty input is upstream\'s own Create fallback (processor at the pin)',
+    };
+  }
+
+  const tag = bytes[0];
+  const entry = BY_TAG.get(tag);
+  if (!entry) {
+    // The pin's judge: borsh try_from_slice rejects an index it does not
+    // declare, and the processor maps that to InvalidInstructionData. The
+    // name below is upstream's own refusal, not a guess.
+    throw new AtaCodecError(
+      'unknown-selector',
+      `${program}: tag ${tag} is not in the pinned ${ARTIFACT.label} interface (upstream refuses it as ${ARTIFACT.runtime.unknownInputRefusal})`,
+    );
+  }
+
+  const trailingBytes = bytes.length - 1;
+  if (trailingBytes > 0 && trailing === 'error') {
+    throw new AtaCodecError('trailing-bytes', `${program}: ${entry.name} explains 1 of ${bytes.length} byte(s)`);
+  }
+
+  return {
+    name: entry.name,
+    tag,
+    selectorWidth: 1,
+    args: {},
+    consumed: 1,
+    bytes: bytes.length,
+    trailing: { count: trailingBytes },
+    roundTripByteExact: encodeAtaInstruction(program, entry.name).equals(Buffer.from(bytes)),
+    scheme: 'native-ata',
+    source: 'pinned-vendored-upstream',
+  };
+}
+
+/** Why the last `decodeAtaInstruction` refused, or null if it did not. */
+export function ataRefusal(program, bytes) {
+  try {
+    const result = decodeAtaInstruction(program, bytes);
+    return result.refused ? result.refused : null;
+  } catch (error) {
+    return error instanceof AtaCodecError ? error.reason : `thrown: ${error.message}`;
+  }
+}
+
+/** Re-encode one ATA instruction from a name (a unit enum carries no args). */
+export function encodeAtaInstruction(program, name) {
+  if (!isAtaProgram(program)) throw new AtaCodecError('not-ata', program);
+  const entry = ARTIFACT.instructions.find((ix) => ix.name === name);
+  if (!entry) throw new AtaCodecError('unknown-variant', `${program}: ${name}`);
+  return Buffer.from([entry.tag]);
+}
+
+/** Names the table can claim for `program` (coverage callers). */
+export function ataNames(program) {
+  if (!isAtaProgram(program)) return [];
+  return ARTIFACT.instructions.map((entry) => entry.name);
+}
+
+/** Whether `name` belongs to `program`'s ATA table. */
+export function isAtaName(program, name) {
+  if (!isAtaProgram(program)) return false;
+  return ARTIFACT.instructions.some((entry) => entry.name === name);
+}
+
+/** The vendored pins, for callers that want to show the source. */
+export { ATA_PINS };

package/src/base58.mjs

@@ -0,0 +1,96 @@
+// Base58 (Bitcoin alphabet) — encode and decode, no dependencies.
+//
+// The decode core of sememe has to run inside repositories that have no
+// npm dependencies at all (a Solana repo that wants to decode instructions
+// without installing a toolkit). `@solana/web3.js` was the only third-party
+// import in the decode path, and it was used for exactly two things:
+// turning 32 raw bytes into a base58 string and back.
+//
+// This module is that part, on its own. It is deliberately small and
+// deliberately boring: the same arithmetic as every other base58
+// implementation, with the edge cases (leading zero bytes, invalid
+// characters, oversized input) handled explicitly rather than silently.
+//
+// `decodeBase58` here is also what `src/decode.mjs` uses for payloads; the
+// public export there is kept for compatibility.
+
+const ALPHABET = '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz';
+const ALPHABET_MAP = new Map([...ALPHABET].map((character, index) => [character, index]));
+
+/** Encode bytes as base58. Leading zero bytes become leading '1' characters. */
+export function encodeBase58(bytes) {
+  if (!(bytes instanceof Uint8Array)) throw new Error('base58 input must be a Uint8Array/Buffer');
+  let zeros = 0;
+  while (zeros < bytes.length && bytes[zeros] === 0) zeros++;
+  // `digits` holds base58 digits least-significant first. It starts EMPTY on
+  // purpose: seeding it with a zero digit would add a spurious leading '1'
+  // for an all-zero input (32 zero bytes must encode to 32 '1' characters,
+  // not 33).
+  const digits = [];
+  for (let index = zeros; index < bytes.length; index++) {
+    let carry = bytes[index];
+    for (let position = 0; position < digits.length; position++) {
+      carry += digits[position] << 8;
+      digits[position] = carry % 58;
+      carry = (carry / 58) | 0;
+    }
+    while (carry > 0) {
+      digits.push(carry % 58);
+      carry = (carry / 58) | 0;
+    }
+  }
+  let out = '1'.repeat(zeros);
+  for (let index = digits.length - 1; index >= 0; index--) out += ALPHABET[digits[index]];
+  return out;
+}
+
+/**
+ * Decode a base58 string into bytes.
+ * Throws on an empty string or an invalid character — a payload that cannot
+ * be decoded is a caller error, not an empty result.
+ *
+ * The result is a `Buffer`, not a plain `Uint8Array`. That is not cosmetic:
+ * the decode path reads floats with `readFloatLE`/`readDoubleLE` and renders
+ * `bytes` arguments with `toString('base64')`, and it re-encodes and compares
+ * with `Buffer.equals`. A plain `Uint8Array` has none of those, so a
+ * base58-decoded payload failed in three different places while the SAME
+ * bytes as hex (which `decodeHex` produces as a Buffer) decoded fine:
+ *
+ *   - src/union.mjs refused every base58 payload ("unionDecode needs the
+ *     payload bytes as a Buffer"),
+ *   - f32/f64 arguments died with "slice.readDoubleLE is not a function",
+ *   - a `bytes` argument came out as a comma-separated byte list
+ *     ("1,2,3,255") instead of base64 — corruption, not an error.
+ *
+ * Measured against the published v0.4.4 install; fixed in v0.4.5.
+ * A Buffer IS a Uint8Array, so every existing caller keeps working.
+ */
+export function decodeBase58(input) {
+  if (typeof input !== 'string' || input.length === 0) {
+    throw new Error('base58 payload must be a non-empty string');
+  }
+  let zeros = 0;
+  while (zeros < input.length && input[zeros] === '1') zeros++;
+  // Empty accumulator for the same reason as in encodeBase58: an all-'1'
+  // input is N zero bytes, not N+1.
+  const bytes = [];
+  for (let index = zeros; index < input.length; index++) {
+    const value = ALPHABET_MAP.get(input[index]);
+    if (value === undefined) throw new Error(`invalid base58 character ${JSON.stringify(input[index])}`);
+    let carry = value;
+    for (let position = 0; position < bytes.length; position++) {
+      carry += bytes[position] * 58;
+      bytes[position] = carry & 0xff;
+      carry >>= 8;
+    }
+    while (carry > 0) {
+      bytes.push(carry & 0xff);
+      carry >>= 8;
+    }
+  }
+  const out = new Uint8Array(zeros + bytes.length);
+  for (let index = 0; index < bytes.length; index++) out[zeros + index] = bytes[bytes.length - 1 - index];
+  // A Buffer VIEW over the same bytes: no copy, and the byte order is
+  // exactly what was decoded.
+  return Buffer.from(out.buffer, out.byteOffset, out.byteLength);
+}

package/src/canonical.mjs

@@ -0,0 +1,24 @@
+// Canonical JSON — the exact serialization the store fingerprints.
+//
+// Lives in its own module so a CONSUMER can verify a receipt without
+// pulling in the acquisition path: `src/pull.mjs` imports @solana/web3.js
+// (PDA derivation), and a dependency-free repository that only wants to
+// confirm "these bytes are the bytes the receipt claims" must not have to
+// install it. `src/pull.mjs` re-exports this, so nothing that imports
+// `canonicalJson` from there changes.
+//
+// Property order is sorted, arrays keep their order, and every value must be
+// JSON-encodable. Two structurally equal objects therefore always produce
+// the same bytes, which is what makes sha256(canonicalJson(idl) + '\n') a
+// content address rather than a snapshot of whatever JSON.stringify felt
+// like doing that day.
+
+export function canonicalJson(value) {
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(',')}]`;
+  if (value && typeof value === 'object') {
+    return `{${Object.keys(value).sort().map(k => `${JSON.stringify(k)}:${canonicalJson(value[k])}`).join(',')}}`;
+  }
+  const encoded = JSON.stringify(value);
+  if (encoded === undefined) throw new Error('non-JSON value');
+  return encoded;
+}