ABI Encoding and Decoding

/**
 * Low-level ABI encoding and decoding utilities
 */
class AbiCoder {
  // Encoding
  encode(types: ReadonlyArray<string | ParamType>, values: ReadonlyArray<any>): string;
  
  // Decoding  
  decode(types: ReadonlyArray<string | ParamType>, data: BytesLike, loose?: boolean): Result;
  
  // Hash computation
  getDefaultValue(types: ReadonlyArray<string | ParamType>): Result;
}

import { AbiCoder } from "ethers";

const coder = AbiCoder.defaultAbiCoder();

// Encode function parameters
const encoded = coder.encode(
  ["address", "uint256"],
  ["0x1234567890123456789012345678901234567890", "1000000000000000000"]
);

// Decode data
const decoded = coder.decode(
  ["address", "uint256"],
  "0x0000000000000000000000001234567890123456789012345678901234567890000000000000000000000000000000000000000000000000000de0b6b3a7640000"
);

/**
 * High-level contract interface management with automatic ABI operations
 */
class Interface {
  constructor(fragments: InterfaceAbi);
  
  readonly fragments: ReadonlyArray<Fragment>;
  readonly deploy: ConstructorFragment;
  readonly fallback?: FallbackFragment;
  readonly receive?: boolean;
  
  // Function operations
  encodeFunctionData(fragment: string | FunctionFragment, values?: ReadonlyArray<any>): string;
  decodeFunctionData(fragment: string | FunctionFragment, data: BytesLike): Result;
  encodeFunctionResult(fragment: string | FunctionFragment, values?: ReadonlyArray<any>): string;
  decodeFunctionResult(fragment: string | FunctionFragment, data: BytesLike): Result;
  
  // Error operations
  encodeErrorResult(fragment: string | ErrorFragment, values?: ReadonlyArray<any>): string;
  decodeErrorResult(fragment: string | ErrorFragment, data: BytesLike): Result;
  
  // Event operations
  encodeEventLog(fragment: string | EventFragment, values: ReadonlyArray<any>): { data: string; topics: ReadonlyArray<string> };
  decodeEventLog(fragment: string | EventFragment, data: BytesLike, topics?: ReadonlyArray<string>): Result;
  
  // Fragment retrieval
  getFunction(key: string | FunctionFragment): FunctionFragment;
  getEvent(key: string | EventFragment): EventFragment;
  getError(key: string | ErrorFragment): ErrorFragment;
  
  // Selectors and signatures
  getSighash(fragment: string | FunctionFragment): string;
  getEventTopic(fragment: string | EventFragment): string;
  
  // Parsing
  parseTransaction(tx: { data: string; value?: BigNumberish }): null | TransactionDescription;
  parseLog(log: { topics: ReadonlyArray<string>; data: string }): null | LogDescription;
  parseError(data: BytesLike): null | ErrorDescription;
  
  // Format conversion
  format(format?: FormatType): string | ReadonlyArray<string>;
  formatJson(): string;
  
  // Static utilities
  static from(value: InterfaceAbi): Interface;
}

type InterfaceAbi = string | ReadonlyArray<Fragment | JsonFragment | string>;

import { Interface } from "ethers";

// Create interface from human-readable ABI
const iface = new Interface([
  "function transfer(address to, uint256 amount) returns (bool)",
  "function balanceOf(address owner) view returns (uint256)",
  "event Transfer(address indexed from, address indexed to, uint256 value)"
]);

// Encode function call
const data = iface.encodeFunctionData("transfer", [
  "0x1234567890123456789012345678901234567890",
  "1000000000000000000"
]);

// Decode function result
const result = iface.decodeFunctionResult("balanceOf", "0x000000000000000000000000000000000000000000000000000de0b6b3a7640000");

// Parse transaction
const txDescription = iface.parseTransaction({
  data: "0xa9059cbb000000000000000000000000...",
  value: 0
});

// Parse event log
const logDescription = iface.parseLog({
  topics: ["0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef", "0x000000000000000000000000..."],
  data: "0x000000000000000000000000000000000000000000000000000de0b6b3a7640000"
});

/**
 * Base class for all ABI fragments
 */
abstract class Fragment {
  readonly type: string;
  readonly inputs: ReadonlyArray<ParamType>;
  
  constructor(guard: any, type: string, inputs: ReadonlyArray<ParamType>);
  
  format(format?: FormatType): string;
  static from(obj: any): Fragment;
}

/**
 * Function fragment for contract methods
 */
class FunctionFragment extends NamedFragment {
  readonly constant: boolean;
  readonly stateMutability: string;
  readonly payable: boolean;
  readonly gas?: bigint;
  readonly outputs?: ReadonlyArray<ParamType>;
  
  constructor(guard: any, name: string, inputs: ReadonlyArray<ParamType>, outputs?: ReadonlyArray<ParamType>, stateMutability?: string);
  
  static from(obj: any): FunctionFragment;
  static getSelector(name: string, params?: ReadonlyArray<ParamType | string>): string;
}

/**
 * Event fragment for contract events
 */
class EventFragment extends NamedFragment {
  readonly anonymous: boolean;
  
  constructor(guard: any, name: string, inputs: ReadonlyArray<ParamType>, anonymous?: boolean);
  
  static from(obj: any): EventFragment;
  static getEventTopic(name: string, params?: ReadonlyArray<ParamType | string>): string;
}

/**
 * Error fragment for contract errors
 */
class ErrorFragment extends NamedFragment {
  constructor(guard: any, name: string, inputs: ReadonlyArray<ParamType>);
  
  static from(obj: any): ErrorFragment;
  static getSelector(name: string, params?: ReadonlyArray<ParamType | string>): string;
}

/**
 * Constructor fragment for contract deployment
 */
class ConstructorFragment extends Fragment {
  readonly payable: boolean;
  readonly gas?: bigint;
  
  constructor(guard: any, inputs: ReadonlyArray<ParamType>, payable?: boolean, gas?: bigint);
  
  static from(obj: any): ConstructorFragment;
}

/**
 * Fallback fragment for fallback functions
 */
class FallbackFragment extends Fragment {
  readonly payable: boolean;
  
  constructor(guard: any, payable?: boolean);
  
  static from(obj: any): FallbackFragment;
}

/**
 * Base class for named fragments
 */
abstract class NamedFragment extends Fragment {
  readonly name: string;
  
  constructor(guard: any, type: string, name: string, inputs: ReadonlyArray<ParamType>);
}

/**
 * Struct fragment for complex types
 */
class StructFragment extends NamedFragment {
  constructor(guard: any, name: string, inputs: ReadonlyArray<ParamType>);
  
  static from(obj: any): StructFragment;
}

/**
 * Parameter type representation for ABI encoding/decoding
 */
class ParamType {
  readonly name: string;
  readonly type: string;
  readonly baseType: string;
  readonly indexed?: boolean;
  readonly components?: ReadonlyArray<ParamType>;
  readonly arrayLength?: number;
  readonly arrayChildren?: ParamType;
  
  constructor(guard: any, name: string, type: string, baseType: string, indexed?: boolean, components?: ReadonlyArray<ParamType>, arrayLength?: number, arrayChildren?: ParamType);
  
  // Tree walking
  walk(value: any, process: ParamTypeWalkFunc): any;
  walkAsync(value: any, process: ParamTypeWalkAsyncFunc): Promise<any>;
  
  // Formatting
  format(format?: FormatType): string;
  
  // Static creation
  static from(obj: any, allowIndexed?: boolean): ParamType;
  static fromObject(obj: any): ParamType;
  static fromString(value: string, allowIndexed?: boolean): ParamType;
}

type ParamTypeWalkFunc = (type: string, value: any) => any;
type ParamTypeWalkAsyncFunc = (type: string, value: any) => any | Promise<any>;

type FormatType = "sighash" | "minimal" | "full" | "json";
type FragmentType = "constructor" | "error" | "event" | "fallback" | "function" | "receive" | "struct";

/**
 * Function call result array with named property access
 */
class Result extends Array<any> {
  readonly [key: string]: any;
  
  constructor(...items: Array<any>);
  
  // Named access
  getValue(name: string): any;
  
  // Array operations
  slice(start?: number, end?: number): Result;
  filter(callback: (value: any, index: number, array: Result) => boolean): Result;
  map<T>(callback: (value: any, index: number, array: Result) => T): Array<T>;
  
  // Conversion
  toArray(): Array<any>;
  toObject(): { [key: string]: any };
}

/**
 * Explicitly typed ABI value wrapper
 */
class Typed {
  readonly type: string;
  readonly value: any;
  
  constructor(guard: any, type: string, value: any, defaultValue?: any);
  
  // Static constructors for common types
  static address(value: string): Typed;
  static bool(value: boolean): Typed;
  static bytes(value: BytesLike): Typed;
  static bytes1(value: BytesLike): Typed;
  static bytes32(value: BytesLike): Typed;
  static int(value: BigNumberish): Typed;
  static int256(value: BigNumberish): Typed;
  static string(value: string): Typed;
  static uint(value: BigNumberish): Typed;
  static uint256(value: BigNumberish): Typed;
  
  // Array types
  static array(value: Array<any>, dynamic?: boolean): Typed;
  static tuple(value: Array<any> | { [key: string]: any }): Typed;
  
  // Overrides
  static overrides(value: Overrides): Typed;
}

/**
 * Parsed transaction description
 */
class TransactionDescription {
  readonly fragment: FunctionFragment;
  readonly name: string;
  readonly args: Result;
  readonly signature: string;
  readonly selector: string;
  readonly value: bigint;
  
  constructor(fragment: FunctionFragment, name: string, args: Result, signature: string, selector: string, value: bigint);
}

/**
 * Parsed event log description
 */
class LogDescription {
  readonly fragment: EventFragment;
  readonly name: string;
  readonly signature: string;
  readonly topic: string;
  readonly args: Result;
  
  constructor(fragment: EventFragment, name: string, signature: string, topic: string, args: Result);
}

/**
 * Parsed error description
 */
class ErrorDescription {
  readonly fragment: ErrorFragment;
  readonly name: string;
  readonly args: Result;
  readonly signature: string;
  readonly selector: string;
  
  constructor(fragment: ErrorFragment, name: string, args: Result, signature: string, selector: string);
}

/**
 * Decode a bytes32 encoded string
 * @param data - The bytes32 data to decode
 * @returns The decoded string
 */
function decodeBytes32String(data: BytesLike): string;

/**
 * Encode a string as bytes32
 * @param text - The string to encode (max 31 bytes)
 * @returns The bytes32 encoded string
 */
function encodeBytes32String(text: string): string;

/**
 * Check function call results for errors and revert reasons
 * @param result - The result array to check
 * @returns The result if no errors, throws if errors found
 */
function checkResultErrors(result: Result): Result;

/**
 * Indexed event parameter marker
 */
class Indexed {
  readonly hash?: string;
  readonly _isIndexed: boolean;
  
  constructor(hash?: string);
  
  static isIndexed(value: any): value is Indexed;
}

type JsonFragment = {
  readonly type?: string;
  readonly name?: string;
  readonly constant?: boolean;
  readonly anonymous?: boolean;
  readonly stateMutability?: string;
  readonly payable?: boolean;
  readonly gas?: string;
  readonly inputs?: ReadonlyArray<JsonFragmentType>;
  readonly outputs?: ReadonlyArray<JsonFragmentType>;
};

type JsonFragmentType = {
  readonly name?: string;
  readonly indexed?: boolean;
  readonly type?: string;
  readonly internalType?: any;
  readonly components?: ReadonlyArray<JsonFragmentType>;
};