hardhat-external-artifacts 0.0.1

package/src/artifacts/converter.ts

@@ -0,0 +1,346 @@
+import type {ExternalArtifact, RichArtifact, LinkReferences} from './types.js';
+import {isRichArtifact} from './types.js';
+
+export interface SyntheticCompilation {
+	solcVersion: string;
+	compilerInput: CompilerInput;
+	compilerOutput: CompilerOutput;
+}
+
+interface CompilerInput {
+	language: string;
+	sources: Record<string, {content: string}>;
+	settings: {
+		optimizer: {enabled: boolean; runs?: number};
+		outputSelection: Record<string, Record<string, string[]>>;
+		remappings?: string[];
+		metadata?: {useLiteralContent?: boolean; bytecodeHash?: string};
+	};
+}
+
+interface CompilerOutput {
+	sources: Record<string, {id: number; ast: object}>;
+	contracts: Record<
+		string,
+		Record<
+			string,
+			{
+				abi: readonly any[];
+				evm: {
+					bytecode: BytecodeOutput;
+					deployedBytecode: BytecodeOutput;
+					methodIdentifiers: Record<string, string>;
+				};
+				metadata?: string;
+				devdoc?: any;
+				userdoc?: any;
+				storageLayout?: any;
+			}
+		>
+	>;
+}
+
+interface BytecodeOutput {
+	object: string;
+	opcodes: string;
+	sourceMap: string;
+	linkReferences: LinkReferences;
+	immutableReferences?: Record<string, Array<{start: number; length: number}>>;
+	generatedSources?: any[];
+	functionDebugData?: Record<string, any>;
+}
+
+/**
+ * Creates a minimal valid AST for a source file.
+ * This is needed because Hardhat's contract decoder expects a valid AST structure.
+ */
+function createMinimalAst(
+	sourceName: string,
+	sourceId: number,
+	contracts?: Array<{name: string; nodeId: number}>,
+): object {
+	const nodes: object[] = [];
+	const exportedSymbols: Record<string, number[]> = {};
+
+	// Add contract definition nodes if provided
+	if (contracts) {
+		for (const contract of contracts) {
+			nodes.push({
+				nodeType: 'ContractDefinition',
+				id: contract.nodeId,
+				src: `0:0:${sourceId}`,
+				name: contract.name,
+				contractKind: 'contract',
+				abstract: false,
+				fullyImplemented: true,
+				linearizedBaseContracts: [contract.nodeId],
+				nodes: [],
+				scope: sourceId,
+			});
+			exportedSymbols[contract.name] = [contract.nodeId];
+		}
+	}
+
+	return {
+		nodeType: 'SourceUnit',
+		src: `0:0:${sourceId}`,
+		id: sourceId,
+		absolutePath: sourceName,
+		exportedSymbols,
+		nodes,
+	};
+}
+
+/**
+ * Convert artifacts to compilation format.
+ * If artifacts are "rich" (have solcInput), use the embedded data.
+ * Otherwise, synthesize a minimal compilation.
+ */
+export function artifactsToCompilations(
+	artifacts: ExternalArtifact[],
+	defaultSolcVersion: string,
+): SyntheticCompilation[] {
+	// Group artifacts by whether they have solcInput
+	const richArtifacts = artifacts.filter(isRichArtifact);
+	const simpleArtifacts = artifacts.filter((a) => !isRichArtifact(a));
+
+	const compilations: SyntheticCompilation[] = [];
+
+	// Process rich artifacts - these have embedded solcInput
+	for (const artifact of richArtifacts) {
+		const compilation = richArtifactToCompilation(artifact);
+		if (compilation) {
+			compilations.push(compilation);
+		}
+	}
+
+	// Process simple artifacts - synthesize compilation
+	if (simpleArtifacts.length > 0) {
+		compilations.push(
+			synthesizeCompilation(simpleArtifacts, defaultSolcVersion),
+		);
+	}
+
+	return compilations;
+}
+
+/**
+ * Convert a rich artifact (with embedded solcInput) to a compilation.
+ * Uses the embedded solcInput directly for maximum fidelity.
+ */
+function richArtifactToCompilation(
+	artifact: RichArtifact,
+): SyntheticCompilation | null {
+	if (!artifact.solcInput) {
+		return null;
+	}
+
+	// Parse the embedded solcInput
+	const compilerInput: CompilerInput = JSON.parse(artifact.solcInput);
+
+	// Extract solc version from metadata
+	let solcVersion = '0.8.20'; // Default
+	if (artifact.metadata) {
+		try {
+			const metadata = JSON.parse(artifact.metadata);
+			if (metadata.compiler?.version) {
+				// Format: "0.8.10+commit.fc410830" -> extract "0.8.10"
+				solcVersion = metadata.compiler.version.split('+')[0];
+			}
+		} catch {
+			// Ignore parsing errors, use default
+		}
+	}
+
+	// Build compiler output from the artifact
+	// Only include sources that we have contract data for
+	// Including empty sources/contracts can cause EDR selector fixup issues
+	const compilerOutput: CompilerOutput = {
+		sources: {},
+		contracts: {},
+	};
+
+	const sourceName = artifact.sourceName;
+
+	// Track source IDs for all input sources (needed for consistent source indexing)
+	let sourceId = 0;
+	const sourceIds: Record<string, number> = {};
+	for (const srcName of Object.keys(compilerInput.sources)) {
+		sourceIds[srcName] = sourceId++;
+	}
+
+	// Only include the source that contains our contract
+	const contractSourceId = sourceIds[sourceName] ?? sourceId++;
+	const contractNodeId = contractSourceId + 1000; // Use an offset to avoid ID conflicts
+
+	compilerOutput.sources[sourceName] = {
+		id: contractSourceId,
+		ast: createMinimalAst(sourceName, contractSourceId, [
+			{name: artifact.contractName, nodeId: contractNodeId},
+		]),
+	};
+	compilerOutput.contracts[sourceName] = {};
+
+	// Ensure the source is in compilerInput as well
+	if (!compilerInput.sources[sourceName]) {
+		compilerInput.sources[sourceName] = {content: ''};
+	}
+
+	// Build bytecode output, ensuring proper format
+	// Standard solc output has bytecode.object without 0x prefix
+	const bytecode: BytecodeOutput = {
+		object: stripHexPrefix(
+			artifact.evm?.bytecode?.object ?? artifact.bytecode ?? '0x',
+		),
+		opcodes: artifact.evm?.bytecode?.opcodes ?? '',
+		sourceMap: artifact.evm?.bytecode?.sourceMap ?? '',
+		linkReferences:
+			artifact.evm?.bytecode?.linkReferences ?? artifact.linkReferences ?? {},
+		generatedSources: artifact.evm?.bytecode?.generatedSources,
+		functionDebugData: artifact.evm?.bytecode?.functionDebugData,
+	};
+
+	const deployedBytecode: BytecodeOutput = {
+		object: stripHexPrefix(
+			artifact.evm?.deployedBytecode?.object ??
+				artifact.deployedBytecode ??
+				'0x',
+		),
+		opcodes: artifact.evm?.deployedBytecode?.opcodes ?? '',
+		sourceMap: artifact.evm?.deployedBytecode?.sourceMap ?? '',
+		linkReferences:
+			artifact.evm?.deployedBytecode?.linkReferences ??
+			artifact.deployedLinkReferences ??
+			{},
+		immutableReferences:
+			artifact.evm?.deployedBytecode?.immutableReferences ?? {},
+		generatedSources: artifact.evm?.deployedBytecode?.generatedSources,
+		functionDebugData: artifact.evm?.deployedBytecode?.functionDebugData,
+	};
+
+	// IMPORTANT: Do NOT provide method identifiers - let EDR compute them
+	// EDR has internal "selector fixup" logic for function overloading that can fail
+	// if we provide method identifiers that it then tries to reconcile with AST info.
+	// The error "Failed to fix up the selector for ... #supportsInterface" happens
+	// when EDR can't match provided selectors with overloaded functions.
+	// By providing an empty object, EDR will compute selectors from the ABI directly.
+	const methodIdentifiers: Record<string, string> = {};
+
+	compilerOutput.contracts[sourceName][artifact.contractName] = {
+		abi: artifact.abi,
+		evm: {
+			bytecode,
+			deployedBytecode,
+			methodIdentifiers,
+		},
+		metadata: artifact.metadata,
+		devdoc: artifact.devdoc,
+		userdoc: artifact.userdoc,
+		storageLayout: artifact.storageLayout,
+	};
+
+	return {
+		solcVersion,
+		compilerInput,
+		compilerOutput,
+	};
+}
+
+/**
+ * Synthesize a minimal compilation from simple artifacts.
+ * Used when artifacts don't have embedded solcInput.
+ */
+function synthesizeCompilation(
+	artifacts: ExternalArtifact[],
+	solcVersion: string,
+): SyntheticCompilation {
+	const sources: CompilerInput['sources'] = {};
+	const outputSources: CompilerOutput['sources'] = {};
+	const contracts: CompilerOutput['contracts'] = {};
+
+	// First, group artifacts by source
+	const contractsBySource: Record<
+		string,
+		Array<{name: string; artifact: ExternalArtifact}>
+	> = {};
+	for (const artifact of artifacts) {
+		if (!contractsBySource[artifact.sourceName]) {
+			contractsBySource[artifact.sourceName] = [];
+		}
+		contractsBySource[artifact.sourceName].push({
+			name: artifact.contractName,
+			artifact,
+		});
+	}
+
+	// Track IDs for AST nodes
+	let nextId = 0;
+
+	// Create sources with contract definitions in AST
+	for (const [sourceName, sourceContracts] of Object.entries(
+		contractsBySource,
+	)) {
+		const sourceId = nextId++;
+		sources[sourceName] = {content: ''};
+		contracts[sourceName] = {};
+
+		// Create contract nodes for AST
+		const contractNodes: Array<{name: string; nodeId: number}> = [];
+		for (const {name} of sourceContracts) {
+			const nodeId = nextId++;
+			contractNodes.push({name, nodeId});
+		}
+
+		outputSources[sourceName] = {
+			id: sourceId,
+			ast: createMinimalAst(sourceName, sourceId, contractNodes),
+		};
+
+		// Add contract outputs
+		for (const {name, artifact} of sourceContracts) {
+			contracts[sourceName][name] = {
+				abi: artifact.abi,
+				evm: {
+					bytecode: {
+						object: stripHexPrefix(artifact.bytecode),
+						opcodes: '',
+						sourceMap: '',
+						linkReferences: artifact.linkReferences ?? {},
+					},
+					deployedBytecode: {
+						object: stripHexPrefix(artifact.deployedBytecode),
+						opcodes: '',
+						sourceMap: '',
+						linkReferences: artifact.deployedLinkReferences ?? {},
+						immutableReferences: {},
+					},
+					// Empty object - let EDR compute selectors to avoid selector fixup issues
+					// with overloaded functions (consistent with richArtifactToCompilation)
+					methodIdentifiers: {},
+				},
+			};
+		}
+	}
+
+	return {
+		solcVersion,
+		compilerInput: {
+			language: 'Solidity',
+			sources,
+			settings: {
+				optimizer: {enabled: false},
+				outputSelection: {
+					'*': {'*': ['abi', 'evm.bytecode', 'evm.deployedBytecode']},
+				},
+			},
+		},
+		compilerOutput: {
+			sources: outputSources,
+			contracts,
+		},
+	};
+}
+
+function stripHexPrefix(hex: string): string {
+	return hex.startsWith('0x') ? hex.slice(2) : hex;
+}

package/src/artifacts/loader.ts

@@ -0,0 +1,148 @@
+import type {
+	ExternalArtifact,
+	RichArtifact,
+	ExternalArtifactsConfig,
+} from './types.js';
+import {
+	readJsonFile,
+	getAllFilesMatching,
+} from '@nomicfoundation/hardhat-utils/fs';
+import path from 'node:path';
+import fs from 'node:fs/promises';
+
+export class ArtifactLoader {
+	readonly #config: ExternalArtifactsConfig;
+	readonly #projectRoot: string;
+
+	constructor(config: ExternalArtifactsConfig, projectRoot: string) {
+		this.#config = config;
+		this.#projectRoot = projectRoot;
+	}
+
+	async loadAll(): Promise<ExternalArtifact[]> {
+		const artifacts: ExternalArtifact[] = [];
+
+		// Load from paths
+		if (this.#config.paths) {
+			for (const pathOrGlob of this.#config.paths) {
+				const absolutePath = path.resolve(this.#projectRoot, pathOrGlob);
+				artifacts.push(...(await this.#loadFromPath(absolutePath)));
+			}
+		}
+
+		// Load from resolver function
+		if (this.#config.resolver) {
+			const resolvedArtifacts = await this.#config.resolver();
+			artifacts.push(...resolvedArtifacts);
+		}
+
+		return artifacts;
+	}
+
+	async #loadFromPath(absolutePath: string): Promise<ExternalArtifact[]> {
+		let stat: Awaited<ReturnType<typeof fs.stat>>;
+
+		try {
+			stat = await fs.stat(absolutePath);
+		} catch {
+			// Path doesn't exist, return empty array
+			if (this.#config.warnOnInvalidArtifacts !== false) {
+				console.warn(
+					`[hardhat-external-artifacts] Path not found: ${absolutePath}`,
+				);
+			}
+			return [];
+		}
+
+		if (stat.isFile()) {
+			try {
+				return [await this.#loadArtifactFile(absolutePath)];
+			} catch (error) {
+				if (this.#config.warnOnInvalidArtifacts !== false) {
+					console.warn(
+						`[hardhat-external-artifacts] Failed to load artifact: ${absolutePath}`,
+						error,
+					);
+				}
+				return [];
+			}
+		}
+
+		if (stat.isDirectory()) {
+			// Support both .json and .ts artifact files
+			const files = await getAllFilesMatching(absolutePath, (p) =>
+				p.endsWith('.json'),
+			);
+
+			const loadedArtifacts: ExternalArtifact[] = [];
+			for (const file of files) {
+				try {
+					loadedArtifacts.push(await this.#loadArtifactFile(file));
+				} catch (error) {
+					if (this.#config.warnOnInvalidArtifacts !== false) {
+						console.warn(
+							`[hardhat-external-artifacts] Failed to load artifact: ${file}`,
+							error,
+						);
+					}
+				}
+			}
+			return loadedArtifacts;
+		}
+
+		return [];
+	}
+
+	async #loadArtifactFile(filePath: string): Promise<ExternalArtifact> {
+		const content = await readJsonFile(filePath);
+		return this.#normalizeArtifact(content, filePath);
+	}
+
+	#normalizeArtifact(raw: any, source: string): ExternalArtifact {
+		// Validate required fields - only ABI is truly required
+		if (!raw.abi || !Array.isArray(raw.abi)) {
+			throw new Error(
+				`Artifact from ${source} is missing required field 'abi' or it's not an array`,
+			);
+		}
+
+		// Infer contractName from filename if not provided
+		// e.g., "/path/to/EIP173Proxy.json" -> "EIP173Proxy"
+		let contractName = raw.contractName;
+		if (!contractName || typeof contractName !== 'string') {
+			const filename = path.basename(source, '.json');
+			contractName = filename;
+		}
+
+		// Infer sourceName from filename if not provided
+		// e.g., "EIP173Proxy" -> "external/EIP173Proxy.sol"
+		let sourceName = raw.sourceName;
+		if (!sourceName || typeof sourceName !== 'string') {
+			sourceName = `external/${contractName}.sol`;
+		}
+
+		// Base artifact fields - required
+		const artifact: ExternalArtifact = {
+			contractName,
+			sourceName,
+			abi: raw.abi,
+			bytecode: raw.bytecode ?? '0x',
+			deployedBytecode: raw.deployedBytecode ?? '0x',
+			linkReferences: raw.linkReferences ?? {},
+			deployedLinkReferences: raw.deployedLinkReferences ?? {},
+		};
+
+		// Check if this is a "rich" artifact with embedded solcInput
+		if (raw.solcInput) {
+			// Rich artifact - has full compilation data
+			(artifact as RichArtifact).solcInput = raw.solcInput;
+			(artifact as RichArtifact).metadata = raw.metadata;
+			(artifact as RichArtifact).evm = raw.evm;
+			(artifact as RichArtifact).devdoc = raw.devdoc;
+			(artifact as RichArtifact).userdoc = raw.userdoc;
+			(artifact as RichArtifact).storageLayout = raw.storageLayout;
+		}
+
+		return artifact;
+	}
+}

package/src/artifacts/types.ts

@@ -0,0 +1,132 @@
+/**
+ * A minimal artifact format that can be provided externally.
+ * Supports both Hardhat v2 and v3 formats.
+ */
+export interface ExternalArtifact {
+	/** Contract name */
+	contractName: string;
+
+	/** Source file path/identifier */
+	sourceName: string;
+
+	/** Contract ABI */
+	abi: readonly any[];
+
+	/** Deployment bytecode (0x-prefixed) */
+	bytecode: string;
+
+	/** Deployed/runtime bytecode (0x-prefixed) */
+	deployedBytecode: string;
+
+	/** Library link references for deployment bytecode */
+	linkReferences?: LinkReferences;
+
+	/** Library link references for deployed bytecode */
+	deployedLinkReferences?: LinkReferences;
+}
+
+/**
+ * A rich artifact that includes embedded solcInput and full compilation data.
+ * This is the format from hardhat-deploy or other tools that preserve
+ * the full compilation output.
+ */
+export interface RichArtifact extends ExternalArtifact {
+	/** The full solc compiler input JSON (stringified) */
+	solcInput?: string;
+
+	/** Contract metadata JSON (contains solc version, settings, etc.) */
+	metadata?: string;
+
+	/** Full EVM output including generated sources, source maps, etc. */
+	evm?: {
+		bytecode: {
+			object: string;
+			opcodes: string;
+			sourceMap: string;
+			linkReferences: LinkReferences;
+			generatedSources?: any[];
+			functionDebugData?: Record<string, any>;
+		};
+		deployedBytecode: {
+			object: string;
+			opcodes: string;
+			sourceMap: string;
+			linkReferences: LinkReferences;
+			immutableReferences?: Record<
+				string,
+				Array<{start: number; length: number}>
+			>;
+			generatedSources?: any[];
+			functionDebugData?: Record<string, any>;
+		};
+		methodIdentifiers?: Record<string, string>;
+		gasEstimates?: any;
+	};
+
+	/** Developer documentation */
+	devdoc?: any;
+
+	/** User documentation */
+	userdoc?: any;
+
+	/** Storage layout */
+	storageLayout?: any;
+}
+
+export interface LinkReferences {
+	[sourceName: string]: {
+		[libraryName: string]: Array<{start: number; length: number}>;
+	};
+}
+
+/**
+ * Type guard to check if an artifact is a rich artifact
+ */
+export function isRichArtifact(
+	artifact: ExternalArtifact,
+): artifact is RichArtifact {
+	return 'solcInput' in artifact && artifact.solcInput !== undefined;
+}
+
+/**
+ * Function type for dynamically resolving artifacts
+ */
+export type ArtifactResolver = () =>
+	| Promise<ExternalArtifact[]>
+	| ExternalArtifact[];
+
+/**
+ * Configuration for external artifacts
+ */
+export interface ExternalArtifactsConfig {
+	/**
+	 * Paths to artifact files or directories
+	 * - File path: loads single artifact JSON
+	 * - Directory path: loads all .json files recursively
+	 */
+	paths?: string[];
+
+	/**
+	 * Function that resolves and returns artifacts dynamically
+	 * Useful for loading from APIs, databases, or complex logic
+	 */
+	resolver?: ArtifactResolver;
+
+	/**
+	 * Solc version to use when creating synthetic compilations
+	 * @default "0.8.20"
+	 */
+	solcVersion?: string;
+
+	/**
+	 * Whether to log warnings for malformed artifacts
+	 * @default true
+	 */
+	warnOnInvalidArtifacts?: boolean;
+
+	/**
+	 * Enable debug logging to diagnose issues
+	 * @default false
+	 */
+	debug?: boolean;
+}

package/src/hooks/config.ts

@@ -0,0 +1,43 @@
+import type {ConfigHooks} from 'hardhat/types/hooks';
+import type {ExternalArtifactsConfig} from '../artifacts/types.js';
+
+export default async (): Promise<Partial<ConfigHooks>> => {
+	const handlers: Partial<ConfigHooks> = {
+		resolveUserConfig: async (
+			userConfig,
+			resolveConfigurationVariable,
+			next,
+		) => {
+			const resolvedConfig = await next(
+				userConfig,
+				resolveConfigurationVariable,
+			);
+
+			// Get user's external artifacts config
+			const externalArtifactsUserConfig = userConfig.externalArtifacts as
+				| ExternalArtifactsConfig
+				| undefined;
+
+			// Apply defaults
+			const externalArtifacts: Required<
+				Omit<ExternalArtifactsConfig, 'resolver'>
+			> & {
+				resolver?: ExternalArtifactsConfig['resolver'];
+			} = {
+				paths: externalArtifactsUserConfig?.paths ?? [],
+				resolver: externalArtifactsUserConfig?.resolver,
+				solcVersion: externalArtifactsUserConfig?.solcVersion ?? '0.8.20',
+				warnOnInvalidArtifacts:
+					externalArtifactsUserConfig?.warnOnInvalidArtifacts ?? true,
+				debug: externalArtifactsUserConfig?.debug ?? false,
+			};
+
+			return {
+				...resolvedConfig,
+				externalArtifacts,
+			};
+		},
+	};
+
+	return handlers;
+};