@thru/abi 0.2.0 → 0.2.1

package/src/imports/resolveImports.ts

@@ -0,0 +1,306 @@
+/**
+ * Import Resolver
+ *
+ * Resolves ABI imports and builds a manifest for WASM consumption.
+ */
+
+import * as yaml from "yaml";
+import type {
+  ImportSource,
+  ImportSourceYaml,
+  PackageId,
+  ResolvedPackage,
+  ResolutionResult,
+  AbiMetadata,
+  AbiFile,
+  RpcEndpoints,
+  RevisionSpec,
+} from "./types";
+import { ResolutionError, DEFAULT_RPC_ENDPOINTS } from "./types";
+import { OnchainFetcher, type OnchainFetcherConfig } from "./onchainFetcher";
+
+export interface ResolverConfig {
+  onchainFetcher?: OnchainFetcher;
+  rpcEndpoints?: RpcEndpoints;
+  maxDepth?: number;
+}
+
+/**
+ * Resolve all imports for an ABI and return a manifest.
+ *
+ * The resolver only supports on-chain imports for browser environments.
+ * For path imports, use the CLI `bundle` command.
+ */
+export async function resolveImports(
+  rootAbiYaml: string,
+  config: ResolverConfig = {}
+): Promise<ResolutionResult> {
+  const resolver = new ImportResolver(config);
+  return resolver.resolve(rootAbiYaml);
+}
+
+/**
+ * Create a manifest from an ABI and its resolved imports.
+ *
+ * The manifest maps package names to ABI YAML content.
+ */
+export function createManifest(result: ResolutionResult): Record<string, string> {
+  return result.manifest;
+}
+
+class ImportResolver {
+  private onchainFetcher: OnchainFetcher;
+  private maxDepth: number;
+  private visited: Map<string, ResolvedPackage>;
+  private inProgress: Set<string>;
+
+  constructor(config: ResolverConfig = {}) {
+    this.onchainFetcher =
+      config.onchainFetcher ??
+      new OnchainFetcher({
+        rpcEndpoints: { ...DEFAULT_RPC_ENDPOINTS, ...config.rpcEndpoints },
+      });
+    this.maxDepth = config.maxDepth ?? 10;
+    this.visited = new Map();
+    this.inProgress = new Set();
+  }
+
+  async resolve(rootAbiYaml: string): Promise<ResolutionResult> {
+    this.visited.clear();
+    this.inProgress.clear();
+
+    const rootPackage = await this.resolvePackage(rootAbiYaml, false, 0);
+    const allPackages = Array.from(this.visited.values());
+    const manifest: Record<string, string> = {};
+
+    for (const pkg of allPackages) {
+      manifest[pkg.id.packageName] = pkg.abiYaml;
+    }
+
+    return {
+      root: rootPackage,
+      allPackages,
+      manifest,
+    };
+  }
+
+  private async resolvePackage(
+    abiYaml: string,
+    isRemote: boolean,
+    depth: number
+  ): Promise<ResolvedPackage> {
+    if (depth > this.maxDepth) {
+      throw new ResolutionError(
+        "CYCLIC_DEPENDENCY",
+        `Maximum resolution depth (${this.maxDepth}) exceeded`
+      );
+    }
+
+    const abiFile = this.parseAbiYaml(abiYaml);
+    const packageId = this.extractPackageId(abiFile);
+    const canonicalKey = `${packageId.packageName}@${packageId.version}`;
+
+    /* Check for cycle */
+    if (this.inProgress.has(canonicalKey)) {
+      throw new ResolutionError(
+        "CYCLIC_DEPENDENCY",
+        `Cyclic dependency detected: ${canonicalKey}`
+      );
+    }
+
+    /* Check if already resolved (keyed by name@version to match inProgress) */
+    const existing = this.visited.get(canonicalKey);
+    if (existing) {
+      return existing;
+    }
+
+    /* Check for version conflict: same package name, different version */
+    for (const [key, pkg] of this.visited) {
+      if (pkg.id.packageName === packageId.packageName && pkg.id.version !== packageId.version) {
+        throw new ResolutionError(
+          "VERSION_CONFLICT",
+          `Version conflict for ${packageId.packageName}: ` +
+            `${pkg.id.version} vs ${packageId.version}`,
+          { existing: pkg.id, conflicting: packageId }
+        );
+      }
+    }
+
+    this.inProgress.add(canonicalKey);
+
+    const imports = abiFile.abi.imports ?? [];
+    const dependencies: PackageId[] = [];
+
+    for (const importYaml of imports) {
+      const importSource = this.normalizeImportSource(importYaml);
+
+      /* Enforce local import restriction */
+      if (isRemote && importSource.type === "path") {
+        throw new ResolutionError(
+          "UNSUPPORTED_IMPORT_TYPE",
+          `Remote package ${packageId.packageName} cannot import local path: ${importSource.path}`
+        );
+      }
+
+      /* Determine child remoteness from the import source type, not the parent.
+         Non-path imports (onchain, git, http) are always remote. */
+      const childIsRemote = importSource.type !== "path";
+      const depPackage = await this.resolveImport(importSource, childIsRemote, depth + 1);
+      dependencies.push(depPackage.id);
+    }
+
+    this.inProgress.delete(canonicalKey);
+
+    const resolvedPackage: ResolvedPackage = {
+      id: packageId,
+      source: { type: "path", path: "<root>" },
+      abiYaml,
+      dependencies,
+      isRemote,
+    };
+
+    this.visited.set(canonicalKey, resolvedPackage);
+    return resolvedPackage;
+  }
+
+  private async resolveImport(
+    source: ImportSource,
+    parentIsRemote: boolean,
+    depth: number
+  ): Promise<ResolvedPackage> {
+    switch (source.type) {
+      case "path":
+        throw new ResolutionError(
+          "UNSUPPORTED_IMPORT_TYPE",
+          `Path imports are not supported in browser. Use CLI 'bundle' command. Path: ${source.path}`
+        );
+
+      case "git":
+        throw new ResolutionError(
+          "UNSUPPORTED_IMPORT_TYPE",
+          `Git imports are not supported in browser. Use CLI 'bundle' command. URL: ${source.url}`
+        );
+
+      case "http":
+        throw new ResolutionError(
+          "UNSUPPORTED_IMPORT_TYPE",
+          `HTTP imports are not supported in browser. Use CLI 'bundle' command. URL: ${source.url}`
+        );
+
+      case "onchain":
+        return this.resolveOnchainImport(source, depth);
+
+      default:
+        throw new ResolutionError(
+          "UNSUPPORTED_IMPORT_TYPE",
+          `Unknown import type: ${(source as ImportSource).type}`
+        );
+    }
+  }
+
+  private async resolveOnchainImport(
+    source: Extract<ImportSource, { type: "onchain" }>,
+    depth: number
+  ): Promise<ResolvedPackage> {
+    const result = await this.onchainFetcher.fetch(
+      source.address,
+      source.target,
+      source.network,
+      source.revision
+    );
+
+    const resolved = await this.resolvePackage(result.abiYaml, true, depth);
+    resolved.source = source;
+    resolved.isRemote = true;
+
+    return resolved;
+  }
+
+  private parseAbiYaml(yamlContent: string): AbiFile {
+    try {
+      const parsed = yaml.parse(yamlContent);
+      if (!parsed || typeof parsed !== "object") {
+        throw new Error("Invalid ABI YAML: not an object");
+      }
+      if (!parsed.abi || typeof parsed.abi !== "object") {
+        throw new Error("Invalid ABI YAML: missing 'abi' section");
+      }
+      return parsed as AbiFile;
+    } catch (error) {
+      throw new ResolutionError(
+        "PARSE_ERROR",
+        `Failed to parse ABI YAML: ${error instanceof Error ? error.message : String(error)}`,
+        error
+      );
+    }
+  }
+
+  private extractPackageId(abiFile: AbiFile): PackageId {
+    const metadata = abiFile.abi;
+    if (!metadata.package) {
+      throw new ResolutionError("PARSE_ERROR", "ABI missing 'package' field");
+    }
+    return {
+      packageName: metadata.package,
+      version: metadata["package-version"] ?? "0.0.0",
+    };
+  }
+
+  private normalizeImportSource(source: ImportSourceYaml): ImportSource {
+    switch (source.type) {
+      case "path":
+        return { type: "path", path: source.path };
+
+      case "git":
+        return {
+          type: "git",
+          url: source.url,
+          ref: source.ref,
+          path: source.path,
+        };
+
+      case "http":
+        return { type: "http", url: source.url };
+
+      case "onchain": {
+        const revision = this.parseRevisionSpec(source.revision);
+        return {
+          type: "onchain",
+          address: source.address,
+          target: source.target ?? "program",
+          network: source.network,
+          revision,
+        };
+      }
+
+      default:
+        throw new ResolutionError(
+          "UNSUPPORTED_IMPORT_TYPE",
+          `Unknown import type: ${(source as ImportSourceYaml).type}`
+        );
+    }
+  }
+
+  private parseRevisionSpec(revision: number | string | undefined): RevisionSpec {
+    if (revision === undefined || revision === "latest") {
+      return { type: "latest" };
+    }
+    if (typeof revision === "number") {
+      return { type: "exact", value: revision };
+    }
+    if (typeof revision === "string") {
+      if (revision.startsWith(">=")) {
+        const value = parseInt(revision.slice(2), 10);
+        if (isNaN(value)) {
+          throw new Error(`Invalid minimum revision: ${revision}`);
+        }
+        return { type: "minimum", value };
+      }
+      const value = parseInt(revision, 10);
+      if (!isNaN(value)) {
+        return { type: "exact", value };
+      }
+    }
+    throw new Error(`Invalid revision specification: ${revision}`);
+  }
+}

package/src/imports/types.ts

@@ -0,0 +1,120 @@
+/**
+ * Import Source Types
+ *
+ * These types mirror the Rust ImportSource enum and related types.
+ */
+
+/* Target type for on-chain ABI imports */
+export type OnchainTarget = "program" | "abi-meta" | "abi";
+
+/* Revision specifier for on-chain imports */
+export type RevisionSpec =
+  | { type: "exact"; value: number }
+  | { type: "minimum"; value: number }
+  | { type: "latest" };
+
+/* Import source specification */
+export type ImportSource =
+  | { type: "path"; path: string }
+  | { type: "git"; url: string; ref: string; path: string }
+  | { type: "http"; url: string }
+  | {
+      type: "onchain";
+      address: string;
+      target: OnchainTarget;
+      network: string;
+      revision: RevisionSpec;
+    };
+
+/* Package identifier */
+export interface PackageId {
+  packageName: string;
+  version: string;
+}
+
+/* Resolved package information */
+export interface ResolvedPackage {
+  id: PackageId;
+  source: ImportSource;
+  abiYaml: string;
+  dependencies: PackageId[];
+  isRemote: boolean;
+}
+
+/* Resolution result */
+export interface ResolutionResult {
+  root: ResolvedPackage;
+  allPackages: ResolvedPackage[];
+  manifest: Record<string, string>;
+}
+
+/* Resolution error */
+export class ResolutionError extends Error {
+  constructor(
+    public code:
+      | "CYCLIC_DEPENDENCY"
+      | "VERSION_CONFLICT"
+      | "FETCH_ERROR"
+      | "PARSE_ERROR"
+      | "NOT_FOUND"
+      | "UNSUPPORTED_IMPORT_TYPE",
+    message: string,
+    public details?: unknown
+  ) {
+    super(message);
+    this.name = "ResolutionError";
+  }
+}
+
+/* ABI account header constants (matches Rust) */
+export const ABI_ACCOUNT_HEADER_SIZE = 45;
+export const ABI_STATE_OPEN = 0x00;
+export const ABI_STATE_FINALIZED = 0x01;
+
+/* Parsed ABI account data */
+export interface AbiAccountData {
+  abiMetaAccount: Uint8Array;
+  revision: bigint;
+  state: number;
+  content: string;
+}
+
+/* RPC endpoint configuration */
+export interface RpcEndpoints {
+  [network: string]: string;
+}
+
+/* Default RPC endpoints */
+export const DEFAULT_RPC_ENDPOINTS: RpcEndpoints = {
+  mainnet: "https://rpc.thru.network",
+  testnet: "https://rpc-testnet.thru.network",
+};
+
+/* ABI metadata parsed from YAML */
+export interface AbiMetadata {
+  package: string;
+  name?: string;
+  "abi-version": number;
+  "package-version": string;
+  description: string;
+  imports?: ImportSourceYaml[];
+}
+
+/* Import source as it appears in YAML */
+export type ImportSourceYaml =
+  | { type: "path"; path: string }
+  | { type: "git"; url: string; ref: string; path: string }
+  | { type: "http"; url: string }
+  | {
+      type: "onchain";
+      address: string;
+      target?: OnchainTarget;
+      network: string;
+      revision?: number | string;
+    };
+
+/* Parsed ABI file */
+export interface AbiFile {
+  abi: AbiMetadata;
+  types: unknown[];
+}

package/src/index.ts

@@ -6,7 +6,18 @@ export {
   reflectInstruction,
   reflectAccount,
   reflectEvent,
-  formatReflection
+  formatReflection,
+  /* Manifest-based functions for ABIs with imports */
+  reflectWithManifest,
+  reflectInstructionWithManifest,
+  reflectAccountWithManifest,
+  reflectEventWithManifest,
+  buildLayoutIrWithManifest,
+  getManifestPackages,
+  validateManifest,
 } from "./wasmBridge";
-export type { FormatOptions } from "./wasmBridge";
+export type { FormatOptions, Manifest, ManifestPackageInfo } from "./wasmBridge";
 export type { FormattedReflection, FormattedValue, FormattedValueWithByteRange, ByteRange } from "./types";
+
+/* Import resolver module */
+export * from "./imports";

package/src/wasmBridge.ts

@@ -10,6 +10,14 @@ type WasmReflectBindings = {
   build_layout_ir: (abi: string) => string;
   format_reflection: (raw: string) => string;
   format_reflection_with_options: (raw: string, options: string) => string;
+  /* Manifest-based functions for ABIs with imports */
+  reflect_with_manifest: (manifest: string, rootPackage: string, typeName: string, buffer: Uint8Array) => string;
+  reflect_instruction_with_manifest: (manifest: string, rootPackage: string, buffer: Uint8Array) => string;
+  reflect_account_with_manifest: (manifest: string, rootPackage: string, buffer: Uint8Array) => string;
+  reflect_event_with_manifest: (manifest: string, rootPackage: string, buffer: Uint8Array) => string;
+  build_layout_ir_with_manifest: (manifest: string, rootPackage: string) => string;
+  get_manifest_packages: (manifest: string) => string;
+  validate_manifest: (manifest: string) => string;
   wasm_start?: () => void;
 };
 
@@ -243,3 +251,172 @@ export function formatReflection(raw: JsonValue, options?: FormatOptions): Forma
   const result = bindings.format_reflection(serialized);
   return JSON.parse(result) as FormattedReflection;
 }
+
+/* ============================================================================
+   Manifest-based Functions
+
+   These functions support ABIs with imports by accepting a pre-resolved manifest
+   (a map of package names to their ABI YAML content).
+   ============================================================================ */
+
+export type Manifest = Record<string, string>;
+
+async function callReflectWithManifest(
+  manifest: Manifest,
+  rootPackage: string,
+  typeName: string,
+  buffer: Uint8Array,
+): Promise<JsonValue> {
+  const bindings = await loadBindings();
+  const manifestJson = JSON.stringify(manifest);
+  const result = bindings.reflect_with_manifest(manifestJson, rootPackage, typeName, buffer);
+  return JSON.parse(result);
+}
+
+async function callReflectInstructionWithManifest(
+  manifest: Manifest,
+  rootPackage: string,
+  buffer: Uint8Array,
+): Promise<JsonValue> {
+  const bindings = await loadBindings();
+  const manifestJson = JSON.stringify(manifest);
+  const result = bindings.reflect_instruction_with_manifest(manifestJson, rootPackage, buffer);
+  return JSON.parse(result);
+}
+
+async function callReflectAccountWithManifest(
+  manifest: Manifest,
+  rootPackage: string,
+  buffer: Uint8Array,
+): Promise<JsonValue> {
+  const bindings = await loadBindings();
+  const manifestJson = JSON.stringify(manifest);
+  const result = bindings.reflect_account_with_manifest(manifestJson, rootPackage, buffer);
+  return JSON.parse(result);
+}
+
+async function callReflectEventWithManifest(
+  manifest: Manifest,
+  rootPackage: string,
+  buffer: Uint8Array,
+): Promise<JsonValue> {
+  const bindings = await loadBindings();
+  const manifestJson = JSON.stringify(manifest);
+  const result = bindings.reflect_event_with_manifest(manifestJson, rootPackage, buffer);
+  return JSON.parse(result);
+}
+
+/**
+ * Reflect a binary buffer using a pre-resolved manifest.
+ *
+ * @param manifest - Map of package names to ABI YAML content
+ * @param rootPackage - The package containing the target type
+ * @param typeName - The type name to parse
+ * @param payload - Binary data to reflect
+ */
+export async function reflectWithManifest(
+  manifest: Manifest,
+  rootPackage: string,
+  typeName: string,
+  payload: ReflectRootPayload,
+): Promise<JsonValue> {
+  if (payload.type === 'binary') {
+    return callReflectWithManifest(manifest, rootPackage, typeName, toUint8Array(payload.value));
+  }
+  if (payload.type === 'hex') {
+    return callReflectWithManifest(manifest, rootPackage, typeName, hexToBytes(payload.value));
+  }
+  throw new Error(`Invalid payload type`);
+}
+
+/**
+ * Reflect an instruction using a pre-resolved manifest.
+ */
+export async function reflectInstructionWithManifest(
+  manifest: Manifest,
+  rootPackage: string,
+  payload: ReflectRootPayload,
+): Promise<JsonValue> {
+  if (payload.type === 'binary') {
+    return callReflectInstructionWithManifest(manifest, rootPackage, toUint8Array(payload.value));
+  }
+  if (payload.type === 'hex') {
+    return callReflectInstructionWithManifest(manifest, rootPackage, hexToBytes(payload.value));
+  }
+  throw new Error(`Invalid payload type`);
+}
+
+/**
+ * Reflect an account using a pre-resolved manifest.
+ */
+export async function reflectAccountWithManifest(
+  manifest: Manifest,
+  rootPackage: string,
+  payload: ReflectRootPayload,
+): Promise<JsonValue> {
+  if (payload.type === 'binary') {
+    return callReflectAccountWithManifest(manifest, rootPackage, toUint8Array(payload.value));
+  }
+  if (payload.type === 'hex') {
+    return callReflectAccountWithManifest(manifest, rootPackage, hexToBytes(payload.value));
+  }
+  throw new Error(`Invalid payload type`);
+}
+
+/**
+ * Reflect an event using a pre-resolved manifest.
+ */
+export async function reflectEventWithManifest(
+  manifest: Manifest,
+  rootPackage: string,
+  payload: ReflectRootPayload,
+): Promise<JsonValue> {
+  if (payload.type === 'binary') {
+    return callReflectEventWithManifest(manifest, rootPackage, toUint8Array(payload.value));
+  }
+  if (payload.type === 'hex') {
+    return callReflectEventWithManifest(manifest, rootPackage, hexToBytes(payload.value));
+  }
+  throw new Error(`Invalid payload type`);
+}
+
+/**
+ * Build layout IR using a pre-resolved manifest.
+ */
+export async function buildLayoutIrWithManifest(
+  manifest: Manifest,
+  rootPackage: string,
+): Promise<JsonValue> {
+  const bindings = await loadBindings();
+  const manifestJson = JSON.stringify(manifest);
+  const result = bindings.build_layout_ir_with_manifest(manifestJson, rootPackage);
+  return JSON.parse(result);
+}
+
+/**
+ * Get the list of package names in a manifest.
+ */
+export async function getManifestPackages(manifest: Manifest): Promise<string[]> {
+  const bindings = await loadBindings();
+  const manifestJson = JSON.stringify(manifest);
+  const result = bindings.get_manifest_packages(manifestJson);
+  return JSON.parse(result);
+}
+
+export interface ManifestPackageInfo {
+  name: string;
+  package: string;
+  version: number;
+  type_count: number;
+  has_root_types: boolean;
+}
+
+/**
+ * Validate a manifest and return information about its contents.
+ */
+export async function validateManifest(manifest: Manifest): Promise<ManifestPackageInfo[]> {
+  const bindings = await loadBindings();
+  const manifestJson = JSON.stringify(manifest);
+  const result = bindings.validate_manifest(manifestJson);
+  return JSON.parse(result);
+}