eth-adapter

1.0.7 verified Fri May 01 auth: no javascript

A high-level Ethereum abstraction layer that auto-generates typed contract methods from ABI/artifact files, reducing boilerplate over ethers.js or web3.js. Version 1.0.7 supports both injected wallets (e.g., MetaMask) and JSON RPC providers. It includes a CLI transpiler (ethpst) that pre-processes ABI files and exposes environment-based contract address configuration. Ships TypeScript types. Notable differentiator: generates per-contract methods with IN/OUT naming to handle overloaded functions automatically.

Common errors

error ethAdapter.contractMethods.STORAGE is undefined ↓

cause ethpst hasn't been run or .env address missing/incorrect; artifact file not found or named incorrectly.

fix

Ensure artifact JSON is in /artifacts, .env has CONTRACT_ADDRESS_STORAGE=0x..., and run npx ethpst.

error TypeError: contractMethods.STORAGE.retrieve_view_IN0_OUT1 is not a function ↓

cause Method called before connecting to provider or function name mismatch (wrong IN/OUT count).

fix

Call await ethAdapter.connectToWeb3Wallet() or setJsonRpcProvider() first. Check the generated method signature; ensure parameter object is passed.

error Cannot find module 'eth-adapter' or its corresponding type declarations ↓

cause Package not installed, or missing TypeScript types (though types are bundled).

fix

Run npm install eth-adapter. For TS, ensure tsconfig.json includes 'node_modules/@types' or 'moduleResolution': 'node'.

error ethpst: command not found ↓

cause eth-adapter not installed globally or npx not used.

fix

Use npx ethpst or install as devDependency and run via npm scripts.

Warnings

breaking Contract methods require deconstructed parameter objects {paramName: value}, not positional arguments. ↓

fix Call methods with an object: contractMethods.CONTRACT.foo_IN1_OUT1({param: val}) instead of contractMethods.CONTRACT.foo_IN1_OUT1(val).

gotcha Environment variable naming: CONTRACT_ADDRESS_{UPPERCASE_CONTRACT_NAME} (e.g., CONTRACT_ADDRESS_STORAGE). For React, REACT_APP_ prefix variations are also parsed. ↓

fix Ensure .env keys follow pattern CONTRACT_ADDRESS_{NAME} where {NAME} matches artifact filename without .json, uppercased.

gotcha ethpst CLI must be run whenever ABIs change; otherwise, generated methods may be stale. ↓

fix Run npx ethpst before starting dev server. For React, prepend scripts with npx ethpst;.

deprecated ethAdapter.ethers is exposed but direct ethers usage is discouraged; use generated methods instead. ↓

fix Prefer ethAdapter.contractMethods over raw ethers calls.

breaking CJS support requires explicit .env setting: ETH_ADAPTER_USE_CJS='TRUE'. Without it, default is ESM only. ↓

fix Add ETH_ADAPTER_USE_CJS='TRUE' to .env and re-run ethpst for CJS output.

Install

npm install eth-adapter

yarn add eth-adapter

pnpm add eth-adapter

Imports

default
wrong
```
const ethAdapter = require('eth-adapter')
```
correct
```
import ethAdapter from 'eth-adapter'
```
Package is ESM-first; CJS requires setting ETH_ADAPTER_USE_CJS='TRUE' in .env before transpilation.
ethAdapter
wrong
```
import { ethAdapter } from 'eth-adapter'
```
correct
```
const ethAdapter = require('eth-adapter')
```
Default export only; named import is incorrect. CJS require works only if transpiled to CJS.
types (TypeScript)
```
import type { EthAdapter, ContractMethods } from 'eth-adapter'
```
TypeScript types are bundled; use 'import type' for type-only imports. The exact type names depend on internal types.

Quickstart

Shows setup steps (install, artifacts, ethpst), two ways to connect (wallet/JSON RPC), and calling a generated contract method with error handling.

// Setup: npm install eth-adapter, create artifacts/ folder with compiled ABI JSON, set CONTRACT_ADDRESS_STORAGE in .env
// Run npx ethpst before starting app (e.g., in script: "start": "npx ethpst; react-scripts start")

import ethAdapter from 'eth-adapter';

// Connect to injected wallet (MetaMask) or use JSON RPC provider
await ethAdapter.connectToWeb3Wallet();
// OR: ethAdapter.setJsonRpcProvider('https://localhost:8545');

// Call a generated contract method
const result = await ethAdapter.contractMethods.STORAGE.retrieve_view_IN0_OUT1();
if (result.error) {
  console.error('Contract call error:', result.error);
} else {
  console.log('Stored value:', result);
}