@pushchain/core
Version:
Push Chain is a true universal L1 that is 100% EVM compatible. It allows developers to deploy once and make their apps instantly compatible with users from all other L1s (Ethereum, Solana, etc) with zero on-chain code change.
209 lines (208 loc) • 7.83 kB
TypeScript
import { UniversalSigner } from '../universal/universal.types';
import { ClientOptions, ReadContractParams, TxResponse, WriteContractParams } from './vm-client.types';
import { PublicClient, Hex } from 'viem';
/**
* EVM client for reading and writing to Ethereum-compatible chains
*
* @example
* // Initialize with an RPC URL
* const evmClient = new EvmClient({
* rpcUrl: 'https://eth-sepolia.g.alchemy.com/v2/your-api-key'
* });
*/
export declare class EvmClient {
publicClient: PublicClient;
constructor({ rpcUrls }: ClientOptions);
/**
* Returns the balance (in wei) of an EVM address.
*
* @param address - The EVM address to check balance for
* @returns Balance as a bigint in wei
*
* @example
* // Get balance of an address
* const balance = await evmClient.getBalance('0x123...');
* console.log(`Balance: ${balance} wei`);
*
* @example
* // Check if an address has zero balance
* const newAddress = privateKeyToAccount(generatePrivateKey()).address;
* const balance = await evmClient.getBalance(newAddress);
* if (balance === BigInt(0)) {
* console.log('Address has no funds');
* }
*/
getBalance(address: `0x${string}`): Promise<bigint>;
/**
* Performs a read-only call to a smart contract.
*
* @param params - Parameters including ABI, contract address, function name, and args
* @returns The result of the contract call with the specified type
*
* @example
* // Read a greeting value from a contract
* const greeting = await evmClient.readContract<string>({
* abi: parseAbi(['function greet() view returns (string)']),
* address: '0x2ba5873eF818BEE57645B7d674149041C44F42c6',
* functionName: 'greet',
* });
* console.log(`Current greeting: ${greeting}`);
*
* @example
* // Reading with arguments
* const balance = await evmClient.readContract<bigint>({
* abi: parseAbi(['function balanceOf(address) view returns (uint256)']),
* address: '0xTokenAddress',
* functionName: 'balanceOf',
* args: ['0xUserAddress'],
* });
*/
readContract<T = unknown>({ abi, address, functionName, args, }: ReadContractParams): Promise<T>;
/**
* Returns the ERC-20 token balance of an owner address.
*
* This is a convenience wrapper around readContract using the minimal
* ERC-20 ABI: balanceOf(address) -> uint256.
*/
getErc20Balance({ tokenAddress, ownerAddress, }: {
tokenAddress: `0x${string}`;
ownerAddress: `0x${string}`;
}): Promise<bigint>;
/**
* Writes a transaction to a smart contract using a UniversalSigner.
* This function handles contract interaction by encoding function data
* and sending the transaction through sendTransaction.
*
* @param params - Parameters including ABI, contract address, function name, args, value and signer
* @returns Transaction hash as a hex string
*
* @example
* // Set a new greeting on a contract
* const txHash = await evmClient.writeContract({
* abi: parseAbi(['function setGreeting(string _greeting)']),
* address: '0x2ba5873eF818BEE57645B7d674149041C44F42c6',
* functionName: 'setGreeting',
* args: ['Hello from Push SDK!'],
* signer: universalSigner,
* });
* console.log(`Transaction sent: ${txHash}`);
*
* @example
* // Sending ether with a contract interaction
* const txHash = await evmClient.writeContract({
* abi: parseAbi(['function deposit() payable']),
* address: '0xContractAddress',
* functionName: 'deposit',
* value: parseEther('0.1'), // Send 0.1 ETH
* signer: universalSigner,
* });
*/
writeContract({ abi, address, functionName, args, value, signer, }: WriteContractParams): Promise<Hex>;
/**
* Sends a raw EVM transaction using a UniversalSigner.
* This handles the full transaction flow:
* 1. Gets nonce, estimates gas, and gets current fee data
* 2. Serializes and signs the transaction
* 3. Broadcasts the signed transaction to the network
*
* @param params - Transaction parameters including destination, data, value and signer
* @returns Transaction hash as a hex string
*
* @example
* // Send a simple ETH transfer
* const txHash = await evmClient.sendTransaction({
* to: '0xRecipientAddress',
* data: '0x', // empty data for a simple transfer
* value: parseEther('0.01'),
* signer: universalSigner,
* });
* console.log(`ETH transfer sent: ${txHash}`);
*/
sendTransaction({ to, data, value, signer, }: {
to: `0x${string}`;
data: Hex;
value?: bigint;
signer: UniversalSigner;
}): Promise<Hex>;
/**
* Estimates the gas required for a transaction.
*
* @param params - Parameters including from/to addresses, value and optional data
* @returns Estimated gas as a bigint
*
* @example
* // Estimate gas for a simple transfer
* const gasEstimate = await evmClient.estimateGas({
* from: '0xSenderAddress',
* to: '0xRecipientAddress',
* value: parseEther('0.01'),
* });
* console.log(`Estimated gas: ${gasEstimate}`);
*
* @example
* // Estimate gas for a contract interaction
* const data = encodeFunctionData({
* abi: parseAbi(['function setGreeting(string)']),
* functionName: 'setGreeting',
* args: ['New greeting'],
* });
*
* const gasEstimate = await evmClient.estimateGas({
* from: universalSigner.account.address as `0x${string}`,
* to: '0xContractAddress',
* data,
* value: BigInt(0),
* });
*/
estimateGas({ from, to, value, data, }: {
from?: `0x${string}`;
to: `0x${string}`;
value?: bigint;
data?: `0x${string}`;
}): Promise<bigint>;
/**
* Gets the current gas price on the network.
* This is primarily used for legacy transactions, but can be useful
* for gas cost estimation in EIP-1559 transactions as well.
*
* @returns Current gas price in wei as a bigint
*
* @example
* // Get current gas price for cost estimation
* const gasPrice = await evmClient.getGasPrice();
* console.log(`Current gas price: ${gasPrice} wei`);
*
* @example
* // Calculate total cost of a transaction
* const gasPrice = await evmClient.getGasPrice();
* const gasEstimate = await evmClient.estimateGas({...});
* const totalCost = gasPrice * gasEstimate;
* console.log(`Estimated transaction cost: ${totalCost} wei`);
*/
getGasPrice(): Promise<bigint>;
/**
* Fetches the full transaction response by hash.
*
* @param txHash - The transaction hash to query
* @returns The transaction object or null if not found
*
* @example
* const tx = await evmClient.getTransaction('0xabc...');
* console.log(tx?.from, tx?.to, tx?.value);
*/
getTransaction(txHash: `0x${string}`): Promise<TxResponse>;
/**
* Waits for a transaction to achieve the desired number of confirmations.
*
* @param txHash - Transaction hash
* @param confirmations - Number of confirmations to wait for (default: 3)
* @param pollIntervalMs - How often to check (default: 1000 ms)
* @param timeoutMs - Maximum time to wait before error (default: 60000 ms)
*/
waitForConfirmations({ txHash, confirmations, pollIntervalMs, timeoutMs, }: {
txHash: `0x${string}`;
confirmations?: number;
pollIntervalMs?: number;
timeoutMs?: number;
}): Promise<void>;
}