contributing

name	contributing
description	Guides contributions to essential-eth, a lightweight Ethereum library. Covers adding utility functions, writing tests, JSDoc conventions, and build workflow. Use when adding features, fixing bugs, or writing new utilities for this codebase. Use when this capability is needed.
metadata	{"author":"dawsbot"}

Contributing to essential-eth

essential-eth is a minimal, tree-shakeable Ethereum utility library (~43 kB) that serves as a lightweight alternative to ethers.js and web3.js. It uses native bigint instead of BigNumber classes.

Project Structure

src/
├── classes/              # Contract and BaseContract
├── providers/            # JsonRpcProvider, FallthroughProvider, AlchemyProvider
│   └── BaseProvider.ts   # Abstract base with all RPC methods
├── utils/                # One file per utility function
│   └── tests/            # Colocated test files
├── conversions/          # Lightweight conversion-only entry point
├── types/                # TypeScript type definitions (Hex, Address, Hash, etc.)
└── index.ts              # Barrel exports

Adding a New Utility Function

1. Create src/utils/<function-name>.ts with a single exported function
2. Add JSDoc with @param, @returns, and @example tags
3. Create src/utils/tests/<function-name>.test.ts
4. Export from src/index.ts (and src/utils/index-utils.ts if appropriate)

Example utility file

import type { BytesLike } from './bytes';

/**
 * Brief description of what the function does.
 *
 * @param input description of parameter
 * @returns description of return value
 * @example
 * ```javascript
 * myFunction('0x1234');
 * // '0xabcd...'
 * ```
 */
export function myFunction(input: BytesLike): string {
  // implementation
}

Example test file

import { describe, expect, it } from 'vitest';
import { myFunction } from './../my-function';

describe('myFunction', () => {
  it('should handle hex strings', () => {
    expect(myFunction('0x1234')).toBe('expected-output');
  });
});

Coding Conventions

• One function per file in src/utils/, named with kebab-case
• Use interface not type for object shapes (@typescript-eslint/consistent-type-definitions)
• Use import type for type-only imports (@typescript-eslint/consistent-type-imports)
• No console.log -- no-console is set to error
• JSDoc required on all non-test source files with @example blocks
• Branded types -- use Hex, Address, Hash from src/types/Primitives.types.ts
• Native bigint -- never use BigNumber libraries
• No side effects -- all utility functions must be pure

Testing

• Framework: Vitest with globals enabled
• Tests live in src/utils/tests/ or src/<module>/test/
• Timeout: 15 seconds
• Run tests: npm run test (runs vitest + build + eslint)
• Run just vitest: npx vitest run

Build

• tsup builds three entry points: index, utils, conversions
• Output: ESM (with splitting) and CJS
• Run: npm run build
• Bundle size matters -- prefer @noble/hashes over heavier crypto libraries

Provider Methods

When adding provider methods, add them to src/providers/BaseProvider.ts. Each method should include JSDoc with comparison lines to ethers.js and web3.js equivalents.

Key Dependencies

• @noble/hashes -- cryptographic hashing (keccak256, sha3)
• @noble/secp256k1 -- elliptic curve operations
• isomorphic-unfetch -- universal fetch for RPC calls

---

Converted and distributed by TomeVault — claim your Tome and manage your conversions.