ABI Parsing

/**
 * Main ABI parser function that converts raw ABI to Contract object
 * @param abi - Array of raw ABI definitions from JSON
 * @param path - Contract file path for name resolution
 * @param documentation - Optional documentation from devdoc/userdoc
 * @returns Parsed contract object with functions, events, and metadata
 */
function parse(abi: RawAbiDefinition[], path: string, documentation?: DocumentationResult): Contract;

import { parse, extractAbi } from "typechain";

const rawJson = `{
  "abi": [
    {
      "type": "function",
      "name": "transfer",
      "inputs": [
        {"name": "to", "type": "address"},
        {"name": "value", "type": "uint256"}
      ],
      "outputs": [{"name": "", "type": "bool"}],
      "stateMutability": "nonpayable"
    }
  ]
}`;

const abi = extractAbi(rawJson);
const contract = parse(abi, "./MyToken.sol/MyToken.json");
console.log(contract.functions.transfer[0].inputs[0].type); // AddressType

/**
 * Extracts ABI array from various JSON formats (Truffle, Hardhat, raw ABI)
 * @param rawJson - Raw JSON string containing ABI data
 * @returns Array of raw ABI definitions
 * @throws MalformedAbiError if JSON is invalid or ABI not found
 */
function extractAbi(rawJson: string): RawAbiDefinition[];

/**
 * Extracts bytecode from various JSON formats
 * @param rawContents - Raw JSON string containing bytecode
 * @returns Bytecode with optional link references, or undefined if not found
 */
function extractBytecode(rawContents: string): BytecodeWithLinkReferences | undefined;

/**
 * Extracts documentation from compiler output (devdoc/userdoc)
 * @param rawContents - Raw JSON string containing documentation
 * @returns Combined documentation result, or undefined if not found
 */
function extractDocumentation(rawContents: string): DocumentationResult | undefined;

interface Contract {
  /** Contract name (normalized) */
  name: string;
  /** Original contract name from file */
  rawName: string;
  /** Contract path components for organization */
  path: string[];
  /** Optional fallback function */
  fallback?: FunctionWithoutInputDeclaration;
  /** Constructor functions (can be overloaded) */
  constructor: FunctionWithoutOutputDeclaration[];
  /** Contract functions grouped by name */
  functions: Dictionary<FunctionDeclaration[]>;
  /** Contract events grouped by name */
  events: Dictionary<EventDeclaration[]>;
  /** Contract structs grouped by name */
  structs: Dictionary<StructType[]>;
  /** Optional contract documentation */
  documentation?: object;
}

type Dictionary<T> = { [key: string]: T };

interface FunctionDeclaration {
  /** Function name */
  name: string;
  /** State mutability (pure, view, nonpayable, payable) */
  stateMutability: StateMutability;
  /** Input parameters */
  inputs: AbiParameter[];
  /** Output parameters */
  outputs: AbiOutputParameter[];
  /** Optional function documentation */
  documentation?: FunctionDocumentation;
}

type StateMutability = 'pure' | 'view' | 'nonpayable' | 'payable';

interface FunctionWithoutOutputDeclaration {
  name: string;
  stateMutability: StateMutability;
  inputs: AbiParameter[];
  outputs: [];
  documentation?: FunctionDocumentation;
}

interface FunctionWithoutInputDeclaration {
  name: string;
  stateMutability: StateMutability;
  inputs: [];
  outputs: AbiOutputParameter[];
  documentation?: FunctionDocumentation;
}

interface AbiParameter {
  /** Parameter name */
  name: string;
  /** EVM type information */
  type: EvmType;
}

interface AbiOutputParameter {
  /** Parameter name (may be empty) */
  name: string;
  /** EVM output type information */
  type: EvmOutputType;
}

interface EventDeclaration {
  /** Event name */
  name: string;
  /** Whether event is anonymous */
  isAnonymous: boolean;
  /** Event arguments */
  inputs: EventArgDeclaration[];
}

interface EventArgDeclaration {
  /** Whether argument is indexed for filtering */
  isIndexed: boolean;
  /** Optional argument name */
  name?: string;
  /** EVM type */
  type: EvmType;
}

interface FunctionDocumentation {
  /** Function author */
  author?: string;
  /** Detailed description */
  details?: string;
  /** User notice */
  notice?: string;
  /** Parameter descriptions by name */
  params?: { [paramName: string]: string };
  /** Return value description */
  return?: string;
}

interface DocumentationResult {
  /** Author information */
  author?: string;
  /** Detailed description */
  details?: string;
  /** User notice */
  notice?: string;
  /** Documentation title */
  title?: string;
  /** Method documentation by signature */
  methods?: { [methodName: string]: FunctionDocumentation };
}

interface RawAbiDefinition {
  /** Function/event name */
  name: string;
  /** Legacy constant flag */
  constant: boolean;
  /** Legacy payable flag */
  payable: boolean;
  /** State mutability (preferred over constant/payable) */
  stateMutability?: StateMutability;
  /** Input parameters */
  inputs: RawAbiParameter[];
  /** Output parameters */
  outputs: RawAbiParameter[];
  /** ABI type (function, event, constructor, fallback, receive) */
  type: string;
}

interface RawAbiParameter {
  /** Parameter name */
  name: string;
  /** Solidity type string */
  type: string;
  /** Optional internal type for structs */
  internalType?: string;
  /** Optional tuple components for complex types */
  components?: RawAbiParameter[];
}

interface BytecodeWithLinkReferences {
  /** Contract bytecode as hex string */
  bytecode: string;
  /** Optional library link references */
  linkReferences?: BytecodeLinkReference[];
}

interface BytecodeLinkReference {
  /** Reference placeholder in bytecode */
  reference: string;
  /** Optional library name */
  name?: string;
}

/**
 * Parses contract file path into name components
 * @param path - Contract file path (e.g., "./contracts/MyToken.sol/MyToken.json")
 * @returns Object with normalized name, raw name, and path components
 */
function parseContractPath(path: string): { name: string; rawName: string; path: string[] };

/**
 * Parses event ABI definition
 * @param abiPiece - Raw event ABI definition
 * @param registerStruct - Callback to register discovered struct types
 * @returns Parsed event declaration
 */
function parseEvent(abiPiece: RawEventAbiDefinition, registerStruct: (struct: StructType) => void): EventDeclaration;

interface RawEventAbiDefinition extends RawAbiDefinition {
  type: 'event';
  anonymous?: boolean;
}

/**
 * Extracts documentation for a specific function from contract documentation
 * @param abiPiece - Raw ABI definition for the function
 * @param documentation - Contract documentation result
 * @returns Function documentation if found, undefined otherwise
 */
function getFunctionDocumentation(abiPiece: RawAbiDefinition, documentation?: DocumentationResult): FunctionDocumentation | undefined;

/**
 * Ensures hex string has 0x prefix
 * @param hexString - Hex string that may or may not have 0x prefix
 * @returns Hex string with 0x prefix
 */
function ensure0xPrefix(hexString: string): string;

/**
 * Checks if function is a simple constant (getter)
 * @param fn - Function declaration to check
 * @returns True if function is a constant getter
 */
function isConstant(fn: FunctionDeclaration): boolean;

/**
 * Checks if function is constant (view/pure) but not a simple getter
 * @param fn - Function declaration to check
 * @returns True if function is constant but has inputs or multiple outputs
 */
function isConstantFn(fn: FunctionDeclaration): boolean;