Core Blockchain Operations

/**
 * Get the latest block number
 * @returns Promise resolving to the latest block number
 */
getBlockNumber(): Promise<number>;

/**
 * Get block details by hash or number
 * @param blockHashOrTag - Block hash, number, or tag ("latest", "earliest", "pending")
 * @returns Promise resolving to block details
 */
getBlock(blockHashOrTag: string | number, includeTransactions?: boolean): Promise<Block>;

/**
 * Get multiple blocks by range
 * @param params - Block range parameters
 * @returns Promise resolving to array of blocks
 */
getBlocks(params: GetBlocksParams): Promise<Block[]>;

interface Block {
  number: number;
  hash: string;
  parentHash: string;
  timestamp: number;
  transactions: string[] | TransactionResponse[];
  gasLimit: BigNumber;
  gasUsed: BigNumber;
  miner: string;
  extraData: string;
  baseFeePerGas?: BigNumber;
}

interface GetBlocksParams {
  blockTag: "latest" | "earliest" | "pending" | number;
  blockCount: number;
  includeTransactions?: boolean;
}

/**
 * Get transaction details by hash
 * @param transactionHash - Transaction hash to query
 * @returns Promise resolving to transaction details
 */
getTransaction(transactionHash: string): Promise<TransactionResponse>;

/**
 * Get transaction receipt
 * @param transactionHash - Transaction hash to query
 * @returns Promise resolving to transaction receipt
 */
getTransactionReceipt(transactionHash: string): Promise<TransactionReceipt>;

/**
 * Get multiple transaction receipts in batch
 * @param transactionHashes - Array of transaction hashes
 * @returns Promise resolving to array of receipts
 */
getTransactionReceipts(params: GetTransactionReceiptsParams): Promise<TransactionReceiptsResponse>;

/**
 * Wait for transaction to be mined
 * @param transactionHash - Transaction hash to wait for
 * @param confirmations - Number of confirmations to wait for
 * @param timeout - Timeout in milliseconds
 * @returns Promise resolving to transaction receipt
 */
waitForTransaction(
  transactionHash: string, 
  confirmations?: number, 
  timeout?: number
): Promise<TransactionReceipt>;

interface TransactionResponse {
  hash: string;
  blockNumber: number;
  blockHash: string;
  from: string;
  to: string;
  value: BigNumber;
  gasLimit: BigNumber;
  gasPrice: BigNumber;
  data: string;
  nonce: number;
  confirmations: number;
}

interface TransactionReceipt {
  transactionHash: string;
  blockNumber: number;
  blockHash: string;
  status: number;
  from: string;
  to: string;
  gasUsed: BigNumber;
  cumulativeGasUsed: BigNumber;
  logs: Log[];
  contractAddress?: string;
}

interface GetTransactionReceiptsParams {
  transactionHashes: string[];
}

interface TransactionReceiptsResponse {
  receipts: (TransactionReceipt | null)[];
}

/**
 * Get token balances for an address
 * @param address - Address to query balances for
 * @param tokenAddresses - Optional array of specific token addresses
 * @returns Promise resolving to token balances
 */
getTokenBalances(
  address: string, 
  tokenAddresses?: string[]
): Promise<TokenBalancesResponse>;

/**
 * Get ERC-20 token metadata
 * @param address - Token contract address
 * @returns Promise resolving to token metadata
 */
getTokenMetadata(address: string): Promise<TokenMetadata>;

/**
 * Get token allowance
 * @param params - Token allowance parameters
 * @returns Promise resolving to allowance amount
 */
getTokenAllowance(params: GetTokenAllowanceParams): Promise<string>;

interface TokenBalancesResponse {
  address: string;
  tokenBalances: TokenBalance[];
}

interface TokenBalance {
  contractAddress: string;
  tokenBalance: string;
  error?: string;
}

interface TokenMetadata {
  name: string;
  symbol: string;
  decimals: number;
  logo?: string;
}

interface GetTokenAllowanceParams {
  contract: string;
  owner: string;
  spender: string;
}

/**
 * Get historical asset transfers
 * @param params - Transfer query parameters
 * @returns Promise resolving to transfer history
 */
getAssetTransfers(params: AssetTransfersParams): Promise<AssetTransfersResponse>;

interface AssetTransfersParams {
  fromBlock?: string | number;
  toBlock?: string | number;
  fromAddress?: string;
  toAddress?: string;
  contractAddresses?: string[];
  category?: AssetTransfersCategory[];
  order?: SortingOrder;
  withMetadata?: boolean;
  excludeZeroValue?: boolean;
  maxCount?: number;
  pageKey?: string;
}

interface AssetTransfersResponse {
  transfers: AssetTransfersResult[];
  pageKey?: string;
}

interface AssetTransfersResult {
  blockNum: string;
  hash: string;
  from: string;
  to: string;
  value: number;
  erc721TokenId?: string;
  erc1155Metadata?: Erc1155Metadata[];
  tokenId?: string;
  asset: string;
  category: AssetTransfersCategory;
  rawContract: RawContract;
  metadata: AssetTransfersMetadata;
}

enum AssetTransfersCategory {
  EXTERNAL = "external",
  INTERNAL = "internal", 
  ERC20 = "erc20",
  ERC721 = "erc721",
  ERC1155 = "erc1155",
  SPECIALNFT = "specialnft",
}

enum SortingOrder {
  ASC = "asc",
  DESC = "desc",
}

/**
 * Estimate gas for a transaction
 * @param transaction - Transaction to estimate gas for
 * @returns Promise resolving to gas estimate
 */
estimateGas(transaction: TransactionRequest): Promise<BigNumber>;

/**
 * Get current gas price
 * @returns Promise resolving to gas price in wei
 */
getGasPrice(): Promise<BigNumber>;

/**
 * Get fee data including EIP-1559 fee structure
 * @returns Promise resolving to fee data
 */
getFeeData(): Promise<FeeData>;

interface FeeData {
  gasPrice?: BigNumber;
  maxFeePerGas?: BigNumber;
  maxPriorityFeePerGas?: BigNumber;
}

interface TransactionRequest {
  to?: string;
  from?: string;
  value?: BigNumber | string;
  data?: string;
  gasLimit?: BigNumber | string;
  gasPrice?: BigNumber | string;
  maxFeePerGas?: BigNumber | string;
  maxPriorityFeePerGas?: BigNumber | string;
  nonce?: number;
  type?: number;
}

/**
 * Execute a contract call (read-only)
 * @param transaction - Call parameters
 * @param blockTag - Block to execute call at
 * @returns Promise resolving to call result
 */
call(transaction: TransactionRequest, blockTag?: string | number): Promise<string>;

/**
 * Send a raw signed transaction
 * @param signedTransaction - Signed transaction hex string
 * @returns Promise resolving to transaction hash
 */
sendTransaction(signedTransaction: string): Promise<TransactionResponse>;

/**
 * Get transaction count (nonce) for address
 * @param address - Address to get nonce for
 * @param blockTag - Block to query at
 * @returns Promise resolving to transaction count
 */
getTransactionCount(address: string, blockTag?: string | number): Promise<number>;

/**
 * Get event logs matching filter criteria
 * @param filter - Log filter parameters
 * @returns Promise resolving to matching logs
 */
getLogs(filter: Filter): Promise<Log[]>;

interface Filter {
  fromBlock?: string | number;
  toBlock?: string | number;
  address?: string | string[];
  topics?: Array<string | string[] | null>;
}

interface Log {
  address: string;
  topics: string[];
  data: string;
  blockNumber: number;
  blockHash: string;
  transactionHash: string;
  transactionIndex: number;
  logIndex: number;
  removed: boolean;
}

/**
 * Resolve ENS name to address
 * @param name - ENS name to resolve
 * @returns Promise resolving to address or null
 */
resolveName(name: string): Promise<string | null>;

/**
 * Reverse lookup address to ENS name
 * @param address - Address to lookup
 * @returns Promise resolving to ENS name or null
 */
lookupAddress(address: string): Promise<string | null>;

import { Alchemy, Network } from "alchemy-sdk";

const alchemy = new Alchemy({
  apiKey: "your-api-key",
  network: Network.ETH_MAINNET,
});

// Get latest block
const blockNumber = await alchemy.core.getBlockNumber();
const block = await alchemy.core.getBlock("latest");

// Query token balances
const balances = await alchemy.core.getTokenBalances("0x...");

// Get transaction details
const tx = await alchemy.core.getTransaction("0x...");
const receipt = await alchemy.core.getTransactionReceipt("0x...");

// Query asset transfers
const transfers = await alchemy.core.getAssetTransfers({
  fromAddress: "0x...",
  category: ["erc20", "erc721"],
  withMetadata: true,
});

// Estimate gas for transaction
const gasEstimate = await alchemy.core.estimateGas({
  to: "0x...",
  value: "1000000000000000000", // 1 ETH in wei
});