eth-chess-id

Generate deterministic chess positions from Ethereum addresses. Each address produces a unique, valid chess position that can be used for visual identification—like identicons, but with chess.

Installation

npm install eth-chess-id

Usage

import {
  generateChessPosition,
  addressToFen,
  addressToSvg,
  addressToAscii,
} from 'eth-chess-id';

// Generate a full position object
const position = generateChessPosition('0x742d35Cc6634C0532925a3b844Bc454e4438f44e');
console.log(position.fen);
// "r1bqk2r/pppp1ppp/2n2n2/2b1p3/..."

// Get just the FEN string
const fen = addressToFen('0x742d35Cc6634C0532925a3b844Bc454e4438f44e');

// Generate an SVG
const svg = addressToSvg('0x742d35Cc6634C0532925a3b844Bc454e4438f44e', {
  size: 400,
  lightSquare: '#f0d9b5',
  darkSquare: '#b58863',
});

// ASCII output for terminals
console.log(addressToAscii('0x742d35Cc6634C0532925a3b844Bc454e4438f44e'));

API

generateChessPosition(address, options?)

Returns a ChessPosition object containing:

• fen - FEN string representation
• address - Normalized Ethereum address
• board - 8x8 array of pieces
• turn - Side to move ('w' or 'b')
• material - Piece counts for each side

addressToFen(address)

Returns just the FEN string.

addressToSvg(address, options?)

Generates an SVG string. Options:

• size - Size in pixels (default: 400)
• lightSquare - Light square color (default: '#f0d9b5')
• darkSquare - Dark square color (default: '#b58863')
• showCoordinates - Show file/rank labels (default: false)
• flipped - Black on bottom (default: false)

addressToAscii(address, flipped?)

Returns an ASCII representation for terminal display.

verifyPosition(address, fen)

Verify that a FEN was generated from a specific address.

How It Works

The library uses a seeded PRNG derived from the Ethereum address to:

1. Place kings on non-adjacent squares
2. Generate weighted piece pools (pawns more common than queens)
3. Place pieces on valid squares (no pawns on 1st/8th rank)
4. Validate the position using chess.js

The same address always produces the same position.

License

MIT