Skip to content

Files

Latest commit

ZetazzzZetazzz
remove beta
Jun 11, 2025
015cb3e · Jun 11, 2025

History

History
281 lines (214 loc) · 11.2 KB

README.md

File metadata and controls

281 lines (214 loc) · 11.2 KB

@interchainjs/ethereum

Welcome to the InterchainJS Ethereum tutorial! This guide will help you quickly get started with sending transactions, interacting with smart contracts, and handling Ethereum utilities using the @interchainjs/ethereum package. Whether you're building backend services or frontend dApps, you'll find practical examples and tips below. Let's dive in! ✨

Overview

Transaction codec and client to communicate with the Ethereum blockchain.

Installation

npm install @interchainjs/ethereum

Usage

Using a Private Key

Import and Construct Signer

import { SignerFromPrivateKey } from "@interchainjs/ethereum/signers/SignerFromPrivateKey";
const signer = new SignerFromPrivateKey(privateKey, RPC_URL);

Get Address, Balance, and Nonce

// Get the address and current balance
type Address = string
const address: Address = signer.getAddress()
console.log("Address:", address)

const balance: bigint = await signer.getBalance()
console.log("Balance (wei):", balance)

// Get the current nonce
const nonce: number = await signer.getNonce()
console.log("Nonce:", nonce)

Send Legacy and EIP-1559 Transactions

// Send a legacy transaction with automatic gas limit
const { txHash: legacyHash, wait: legacyWait } = await signer.sendLegacyTransactionAutoGasLimit(
  recipientAddress,
  1000000000000000n, // 0.001 ETH
  '0x'
)
const legacyReceipt = await legacyWait()
console.log("Legacy tx receipt:", legacyReceipt)

// Send an EIP-1559 transaction with automatic gas settings
const { txHash: eipHash, wait: eipWait } = await signer.sendEIP1559TransactionAutoGasLimit(
  recipientAddress,
  1000000000000000n // 0.001 ETH
)
const eipReceipt = await eipWait()
console.log("EIP-1559 tx receipt:", eipReceipt)

Sign and Verify a Personal Message

// Sign and verify a personal message
const message: string = "Hello, Ethereum!"
const signature: string = signer.personalSign(message)
console.log("Signature:", signature)

const isValid: boolean = SignerFromPrivateKey.verifyPersonalSignature(
  message,
  signature,
  address
)
console.log("Signature valid:", isValid)
}

Estimate Gas for a Transaction

// Estimate gas for an arbitrary transaction
const estimatedGas: bigint = await signer.estimateGas(
  recipientAddress,
  500000000000000000n, // 0.5 ETH
  "0x" // optional data
);
console.log("Estimated gas:", estimatedGas.toString());

Deploy a Smart Contract

// Deploy a smart contract
const bytecode = "0x..."; // compiled contract bytecode
const { txHash: deployHash, wait: deployWait } =
  await signer.sendLegacyTransactionAutoGasLimit("", 0n, bytecode);
const deployReceipt = await deployWait();
console.log("Contract deployed at:", deployReceipt.contractAddress);

Interact with a Deployed Contract (ERC20 Transfer)

// Interact with a deployed contract (transfer ERC20 tokens)
import { ContractEncoder } from "@interchainjs/ethereum/utils/ContractEncoder";
const abi = [
  /* ERC20 contract ABI */
];
const contractAddress = deployReceipt.contractAddress;
const contract = new ContractEncoder(abi);
const dataHex = contract.transfer(recipientAddress, 1000000n);
const { txHash: tokenHash, wait: tokenWait } =
  await signer.sendLegacyTransactionAutoGasLimit(contractAddress, 0n, dataHex);
const tokenReceipt = await tokenWait();
console.log("Token transfer receipt:", tokenReceipt);

Monitor Contract Events via WebSocket

// Monitor contract events via WebSocket
import { WebSocketContractMonitor } from "@interchainjs/ethereum/providers/WebSocketContractMonitor";
const wsUrl = "ws://127.0.0.1:8546";
const monitor = new WebSocketContractMonitor(contractAddress, abi, wsUrl);
await monitor.connect();
monitor.on("Transfer", (event) => {
  console.log("Transfer event:", event);
});

See more usages in the unit test

In the frontend

Send Transaction from Browser Wallet

import { SignerFromBrowser } from "@interchainjs/ethereum/signers/SignerFromBrowser";
const signer = new SignerFromBrowser(window.ethereum);
const tx = await signer.send({
  to: recipientAddress,
  value: BigInt(10 ** 18),
});
const receipt = await tx.wait();

For more details, see this example

Utility Functions

Denominations

Parse and Format ETH/Token Amounts

import {
  parseEther,
  formatEther,
  parseUnits,
  formatUnits
} from "@interchainjs/ethereum/utils/denominations";

// Parse ETH to wei
const wei: bigint = parseEther("1.5"); // 1500000000000000000n

// Format wei to ETH
const eth: string = formatEther(wei); // "1.5"

// Parse a token amount (e.g., 6 decimals)
const units: bigint = parseUnits("123.456", 6);

// Format back to human‐readable
const amount: string = formatUnits(units, 6); // "123.456"

Encoding

UTF-8 and Hex Conversion

import {
  utf8ToHex,
  hexToUtf8
} from "@interchainjs/ethereum/utils/encoding";

const hex = utf8ToHex("Hello, Ethereum!"); // "48656c6c6f2c20457468657265756d21"
const str = hexToUtf8("0x48656c6c6f");     // "Hello"

Address Utilities

Validate and Checksum Ethereum Addresses

import {
  isValidEthereumAddress,
  toChecksumAddress
} from "@interchainjs/ethereum/utils/address";

const addr = "0xfB6916095ca1df60bB79Ce92cE3Ea74c37c5d359";
console.log(isValidEthereumAddress(addr));
// true

const lower = "0xfB6916095ca1df60bb79ce92ce3ea74c37c5d359";
console.log(toChecksumAddress(lower));
// "0xfB6916095ca1df60bB79Ce92cE3Ea74c37c5d359"

Implementations

  • SignerFromPrivateKey from @interchainjs/ethereum/signers/SignerFromPrivateKey
  • SignerFromBrowser from @interchainjs/ethereum/signers/SignerFromBrowser

Interchain JavaScript Stack ⚛️

A unified toolkit for building applications and smart contracts in the Interchain ecosystem

Category Tools Description
Chain Information Chain Registry, Utils, Client Everything from token symbols, logos, and IBC denominations for all assets you want to support in your application.
Wallet Connectors Interchain Kit, Cosmos Kit Experience the convenience of connecting with a variety of web3 wallets through a single, streamlined interface.
Signing Clients InterchainJS, CosmJS A single, universal signing interface for any network
SDK Clients Telescope Your Frontend Companion for Building with TypeScript with Cosmos SDK Modules.
Starter Kits Create Interchain App, Create Cosmos App Set up a modern Interchain app by running one command.
UI Kits Interchain UI The Interchain Design System, empowering developers with a flexible, easy-to-use UI kit.
Testing Frameworks Starship Unified Testing and Development for the Interchain.
TypeScript Smart Contracts Create Hyperweb App Build and deploy full-stack blockchain applications with TypeScript
CosmWasm Contracts CosmWasm TS Codegen Convert your CosmWasm smart contracts into dev-friendly TypeScript classes.

Credits

🛠 Built by Hyperweb (formerly Cosmology) — if you like our tools, please checkout and contribute to our github ⚛️

Disclaimer

AS DESCRIBED IN THE LICENSES, THE SOFTWARE IS PROVIDED “AS IS”, AT YOUR OWN RISK, AND WITHOUT WARRANTIES OF ANY KIND.

No developer or entity involved in creating this software will be liable for any claims or damages whatsoever associated with your use, inability to use, or your interaction with other users of the code, including any direct, indirect, incidental, special, exemplary, punitive or consequential damages, or loss of profits, cryptocurrencies, tokens, or anything else of value.