Contributing

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