micro-eth-signer

Micro-eth-signer supports Clear Signing via ERC-7730 descriptor maps. These maps allow raw transaction data to be decoded into human-readable 'intents'.

Descriptor Map Options

• CLEARSIG_REPO: The base repository containing generic ERC interfaces, curated contracts (Uniswap, etc.), and a built-in token registry.
• addTokens(repo, tokens): Extends a repository with custom token metadata (address, symbol, decimals). This also automatically binds ERC-2612 permit interfaces to those tokens.
• CLEARSIG_REPO_FULL: A large (approx. 500KB) repository containing every descriptor from the upstream registry. Import this via the specific subpath micro-eth-signer/clearsig/repo-full.js only when needed.

import { CLEARSIG_REPO, addTokens } from 'micro-eth-signer/abi.js';
import { CLEARSIG_REPO_FULL } from 'micro-eth-signer/clearsig/repo-full.js';

const base = CLEARSIG_REPO;

const mine = addTokens(CLEARSIG_REPO, {
  '0x00000000000000000000000000000000000000123': {
    abi: 'ERC20',
    symbol: 'MTK',
    decimals: 18,
  },
});

const full = { ...CLEARSIG_REPO, ...CLEARSIG_REPO_FULL };

To use micro-eth-signer network features, you must provide an RpcClient. It is recommended to use micro-ftch to wrap the standard fetch API, as it provides features like batching, logging, and concurrency control.

To enable JSON-RPC batching (which significantly improves latency for methods like tokenBalances), pass a batchSize in the jsonrpc options.

Conventions:

• Timestamps: All timestamps (e.g., BlockInfo.timestamp) are in Unix seconds.
• Numbers: Block numbers and indexes are number; balances, fees, and gas are bigint (wei/token units).
• Addresses: Returned as reported by the node (lowercase in logs, checksummed elsewhere). Use addr.addChecksum from the core module to normalize.
• Errors: Methods throw on failure. Web3Error includes method, rpcCode, and isRevert. In batch methods (like tokenInfo), individual contract errors are returned as { contract, error } objects instead of throwing.

import { jsonrpc } from 'micro-ftch';
import { RpcClient } from 'micro-eth-signer/net.js';

const RPC_URL = 'http://localhost:8545';
// Basic initialization
const prov = new RpcClient(jsonrpc(fetch, RPC_URL));

// Initialization with batching for performance
const provBatched = new RpcClient(jsonrpc(fetch, RPC_URL, { batchSize: 20 }));

// Initialization with custom Origin header
const provWithOrigin = new RpcClient(jsonrpc(fetch, 'https://nodes.mewapi.io/rpc/eth', { Origin: 'https://www.myetherwallet.com' }));

The transaction lifecycle involves preparing fields (nonce, gas, etc.), signing the transaction, broadcasting it, and waiting for inclusion.

prov.prepare supports two population policies:

1. viem v3-compatible (Default): Attempts eth_fillTransaction. If unsupported, it falls back to manual population using a pending nonce, estimateGas(), and viem-style fee calculation (1.2 * latest base fee + eth_maxPriorityFeePerGas).
2. ethers_v6-compatible: Pass 'ethers_v6' as the second argument. It uses 2 * latest base fee + priority fee, a 1 gwei priority fallback, and unscaled legacy gas prices.

waitForReceipt accepts an options object: { confirmations, timeoutMs, pollIntervalMs, signal }.

import { Transaction } from 'micro-eth-signer';

async function main(privateKey: string, prov: RpcClient) {
  // 1. Prepare fields (nonce, gas, etc.)
  const fields = await prov.prepare({
    from: '0xd8da6bf26964af9d7eed9e03e53415d37aa96045',
    to: '0x7aa96045d8da6bf26964af9d7eed9e03e53415d3',
    value: 10n ** 18n, // 1 eth in wei
  });

  // 2. Create and sign the transaction
  const tx = Transaction.prepare(fields).signBy(privateKey);

  // 3. Broadcast to the network
  const txHash = await prov.broadcast(tx);

  // 4. Wait for inclusion
  const receipt = await prov.waitForReceipt(txHash, { confirmations: 2 });
  console.log(receipt.status === 1 ? 'confirmed' : 'reverted');
}

The library uses a two-step process to manage NFT inventory: discovery via history and verification via on-chain state.

1. Discover candidates with nftCandidates()

Pass transaction history rows to nftCandidates() to identify ERC-721 and ERC-1155 contracts the address has interacted with. This function returns NftCandidate[] objects containing contract addresses, ABIs, and a map of token IDs seen in transfers.

2. Verify ownership with nftHoldings()

Pass the candidates from the previous step to nftHoldings() to perform on-chain checks (e.g., ownerOf or balanceOf). This returns the actual current inventory.

Constraints & Limits:

• Limits: To prevent excessive RPC calls, the process is limited to 256 contracts and 4096 distinct contract/ID pairs. If your inventory exceeds these, you must paginate.
• Errors: Zero-balance IDs are automatically dropped. If a contract check fails, it is returned as a TokenError entry in the results.

// 1. Discover
const candidates = nftCandidates(historyRows);

// 2. Verify
const holdings = await nftHoldings(prov, address, candidates, {
  concurrency: 5,
  signal: abortController.signal
});

The Transaction class allows you to prepare and sign various transaction types, including legacy, EIP-2930, EIP-1559, EIP-4844, and EIP-7702.

Key features:

• Preparation: Use Transaction.prepare() with fields like to, value, maxFeePerGas, and nonce.
• Signing: Use .signBy(privateKey) to sign.
• Hedged Signatures: You can enable or disable hedged signatures (which add extra noise/security) by passing a boolean as the second argument to .signBy(privateKey, boolean). The default is true.
• Max Amount: Use .setMaxAmount(amount) to calculate a transaction that sends the maximum possible amount while reserving the worst-case fee.

import { addr, Transaction, weigwei, weieth } from 'micro-eth-signer';
const random = addr.random();
const tx = Transaction.prepare({
  to: '0xdf90dea0e0bf5ca6d2a7f0cb86874ba6714f463e',
  value: weieth.decode('1.1'), // 1.1eth in wei
  maxFeePerGas: weigwei.decode('100'), // 100gwei in wei
  nonce: 0n,
});

// Sign with hedged signatures (default)
const signedTx = tx.signBy(random.privateKey, true);

// Sign without hedged signatures
const signedTxNoHedge = tx.signBy(random.privateKey, false);

// Send max amount while reserving worst-case fee
const CURRENT_BALANCE = '1.7182050000017';
const txSendingMaxAmount = tx.setMaxAmount(weieth.decode(CURRENT_BALANCE));

The UniswapV3 class allows you to find swap routes and generate transaction data for token swaps.

• Slippage & TTL: You can specify slippagePercent and ttl (time-to-live in seconds) in the swap options.
• Token Lookup: Use tokenFromSymbol from micro-eth-signer/abi.js to resolve symbols to addresses.

import { tokenFromSymbol } from 'micro-eth-signer/abi.js';
import { UniswapV3 } from 'micro-eth-signer/net/uniswap.js';

const USDT = tokenFromSymbol('USDT');
const BAT = tokenFromSymbol('BAT');

async function main() {
  const u3 = new UniswapV3(prov);
  const fromAddress = '0xd8da6bf26964af9d7eed9e03e53415d37aa96045';
  const toAddress = '0xd8da6bf26964af9d7eed9e03e53415d37aa96045';

  // Swap 12.12 USDT to BAT with 0.5% slippage and 30 min expiration
  const swap = await u3.swap(USDT, BAT, '12.12', { slippagePercent: 0.5, ttl: 30 * 60 });
  
  if (!swap) throw new Error('No swap route found');
  
  const swapData = await swap.tx(fromAddress, toAddress);
  console.log(swapData.amount, swapData.expectedAmount, swapData.allowance);
}

EIP-191 is a standard for signing plain text messages. Use the eip191Signer object to handle these operations.

• Signing: eip191Signer.sign(message, privateKey)
• Verification: eip191Signer.verify(signature, message, address)
• Hashing: eip191Signer.getHash(message) returns the digest that gets signed.
• Signature Parsing: Use parseSignature(signature) to extract { r, s, yParity } and serializeSignature({ r, s, yParity }) to rebuild a 65-byte hex signature.

import { eip191Signer, parseSignature, serializeSignature } from 'micro-eth-signer';

const message = 'Hello, Ethereum!';
const privateKey = '0x4c0883a69102937d6231471b5dbb6204fe512961708279f1d7b1b8e7e8b1b1e1';

// Sign
const signature = eip191Signer.sign(message, privateKey);

// Verify
const address = '0xYourEthereumAddress';
const isValid = eip191Signer.verify(signature, message, address);

// Parse and Rebuild
const { r, s, yParity } = parseSignature(signature);
const rebuiltSignature = serializeSignature({ r, s, yParity });