@thru/abi 0.2.0 → 0.2.1

package/dist/index.d.ts

@@ -67,5 +67,252 @@ interface FormatOptions {
     includeByteOffsets?: boolean;
 }
 declare function formatReflection(raw: JsonValue, options?: FormatOptions): FormattedReflection;
+type Manifest = Record<string, string>;
+/**
+ * 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
+ */
+declare function reflectWithManifest(manifest: Manifest, rootPackage: string, typeName: string, payload: ReflectRootPayload): Promise<JsonValue>;
+/**
+ * Reflect an instruction using a pre-resolved manifest.
+ */
+declare function reflectInstructionWithManifest(manifest: Manifest, rootPackage: string, payload: ReflectRootPayload): Promise<JsonValue>;
+/**
+ * Reflect an account using a pre-resolved manifest.
+ */
+declare function reflectAccountWithManifest(manifest: Manifest, rootPackage: string, payload: ReflectRootPayload): Promise<JsonValue>;
+/**
+ * Reflect an event using a pre-resolved manifest.
+ */
+declare function reflectEventWithManifest(manifest: Manifest, rootPackage: string, payload: ReflectRootPayload): Promise<JsonValue>;
+/**
+ * Build layout IR using a pre-resolved manifest.
+ */
+declare function buildLayoutIrWithManifest(manifest: Manifest, rootPackage: string): Promise<JsonValue>;
+/**
+ * Get the list of package names in a manifest.
+ */
+declare function getManifestPackages(manifest: Manifest): Promise<string[]>;
+interface ManifestPackageInfo {
+    name: string;
+    package: string;
+    version: number;
+    type_count: number;
+    has_root_types: boolean;
+}
+/**
+ * Validate a manifest and return information about its contents.
+ */
+declare function validateManifest(manifest: Manifest): Promise<ManifestPackageInfo[]>;
+
+/**
+ * Import Source Types
+ *
+ * These types mirror the Rust ImportSource enum and related types.
+ */
+type OnchainTarget = "program" | "abi-meta" | "abi";
+type RevisionSpec = {
+    type: "exact";
+    value: number;
+} | {
+    type: "minimum";
+    value: number;
+} | {
+    type: "latest";
+};
+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;
+};
+interface PackageId {
+    packageName: string;
+    version: string;
+}
+interface ResolvedPackage {
+    id: PackageId;
+    source: ImportSource;
+    abiYaml: string;
+    dependencies: PackageId[];
+    isRemote: boolean;
+}
+interface ResolutionResult {
+    root: ResolvedPackage;
+    allPackages: ResolvedPackage[];
+    manifest: Record<string, string>;
+}
+declare class ResolutionError extends Error {
+    code: "CYCLIC_DEPENDENCY" | "VERSION_CONFLICT" | "FETCH_ERROR" | "PARSE_ERROR" | "NOT_FOUND" | "UNSUPPORTED_IMPORT_TYPE";
+    details?: unknown | undefined;
+    constructor(code: "CYCLIC_DEPENDENCY" | "VERSION_CONFLICT" | "FETCH_ERROR" | "PARSE_ERROR" | "NOT_FOUND" | "UNSUPPORTED_IMPORT_TYPE", message: string, details?: unknown | undefined);
+}
+declare const ABI_ACCOUNT_HEADER_SIZE = 45;
+declare const ABI_STATE_OPEN = 0;
+declare const ABI_STATE_FINALIZED = 1;
+interface AbiAccountData {
+    abiMetaAccount: Uint8Array;
+    revision: bigint;
+    state: number;
+    content: string;
+}
+interface RpcEndpoints {
+    [network: string]: string;
+}
+declare const DEFAULT_RPC_ENDPOINTS: RpcEndpoints;
+interface AbiMetadata {
+    package: string;
+    name?: string;
+    "abi-version": number;
+    "package-version": string;
+    description: string;
+    imports?: ImportSourceYaml[];
+}
+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;
+};
+interface AbiFile {
+    abi: AbiMetadata;
+    types: unknown[];
+}
+
+/**
+ * On-chain ABI Fetcher
+ *
+ * Fetches ABI content from on-chain accounts.
+ */
+
+/**
+ * Minimal interface for a Thru RPC client that can fetch raw accounts.
+ * This is compatible with @thru/thru-sdk client but doesn't require it.
+ */
+interface ThruRpcClient {
+    query: {
+        getRawAccount: (request: {
+            address: {
+                value: Uint8Array;
+            };
+            versionContext: Record<string, unknown>;
+        }) => Promise<{
+            rawData?: Uint8Array;
+        }>;
+    };
+}
+/**
+ * Derive the official ABI account address for a given program.
+ *
+ * This performs the same derivation as OnchainFetcher.fetch() with target="program",
+ * returning the raw 32-byte address of the ABI account.
+ */
+declare function deriveOfficialAbiAddress(programAddress: string, abiManagerProgramId?: string): Promise<Uint8Array>;
+/**
+ * Parse ABI account data from raw bytes.
+ *
+ * Account header layout (45 bytes):
+ * - abi_meta_account: [u8; 32]
+ * - revision: u64 (little-endian)
+ * - state: u8 (0x00=OPEN, 0x01=FINALIZED)
+ * - content_sz: u32 (little-endian)
+ * - content: [u8; content_sz]
+ */
+declare function parseAbiAccountData(data: Uint8Array): AbiAccountData;
+/**
+ * Check if a revision matches the specification.
+ */
+declare function revisionMatches(revision: bigint, spec: RevisionSpec): boolean;
+interface OnchainFetcherConfig {
+    rpcEndpoints?: RpcEndpoints;
+    thruClient?: ThruRpcClient;
+    abiManagerProgramId?: string;
+    abiManagerIsEphemeral?: boolean;
+}
+interface FetchResult {
+    abiYaml: string;
+    revision: bigint;
+    isFinalized: boolean;
+}
+/**
+ * Fetcher for on-chain ABI accounts.
+ *
+ * Supports fetching ABI from:
+ * - Official ABI via program (target: "program")
+ * - ABI via ABI meta account (target: "abi-meta")
+ * - Direct ABI account (target: "abi")
+ */
+declare class OnchainFetcher {
+    private rpcEndpoints;
+    private thruClient?;
+    private abiManagerProgramId;
+    private abiManagerIsEphemeral;
+    constructor(config?: OnchainFetcherConfig);
+    /**
+     * Fetch ABI content from an on-chain account.
+     */
+    fetch(address: string, target: OnchainTarget, network: string, revision: RevisionSpec): Promise<FetchResult>;
+    /**
+     * Get the RPC endpoint for a network.
+     */
+    getRpcEndpoint(network: string): string;
+    private parseAddress;
+    private fetchAccountData;
+    private fetchWithThruClient;
+    private fetchWithHttp;
+}
+
+/**
+ * Import Resolver
+ *
+ * Resolves ABI imports and builds a manifest for WASM consumption.
+ */
+
+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.
+ */
+declare function resolveImports(rootAbiYaml: string, config?: ResolverConfig): Promise<ResolutionResult>;
+/**
+ * Create a manifest from an ABI and its resolved imports.
+ *
+ * The manifest maps package names to ABI YAML content.
+ */
+declare function createManifest(result: ResolutionResult): Record<string, string>;
 
-export { type ByteRange, type FormatOptions, type FormattedReflection, type FormattedValue, type FormattedValueWithByteRange, buildLayoutIr, configureWasm, ensureWasmLoaded, formatReflection, reflect, reflectAccount, reflectEvent, reflectInstruction };
+export { ABI_ACCOUNT_HEADER_SIZE, ABI_STATE_FINALIZED, ABI_STATE_OPEN, type AbiAccountData, type AbiFile, type AbiMetadata, type ByteRange, DEFAULT_RPC_ENDPOINTS, type FetchResult, type FormatOptions, type FormattedReflection, type FormattedValue, type FormattedValueWithByteRange, type ImportSource, type ImportSourceYaml, type Manifest, type ManifestPackageInfo, OnchainFetcher, type OnchainFetcherConfig, type OnchainTarget, type PackageId, ResolutionError, type ResolutionResult, type ResolvedPackage, type ResolverConfig, type RevisionSpec, type RpcEndpoints, type ThruRpcClient, buildLayoutIr, buildLayoutIrWithManifest, configureWasm, createManifest, deriveOfficialAbiAddress, ensureWasmLoaded, formatReflection, getManifestPackages, parseAbiAccountData, reflect, reflectAccount, reflectAccountWithManifest, reflectEvent, reflectEventWithManifest, reflectInstruction, reflectInstructionWithManifest, reflectWithManifest, resolveImports, revisionMatches, validateManifest };