EIP-712 Typed Data

Sign structured data with domain separation

Skill — Copyable reference implementation. Use as-is or customize. See Skills Philosophy.

EIP-712 enables human-readable message signing with domain separation. Instead of signing opaque hex blobs, users see structured data in their wallet prompts.

Domain Separator

The domain separator cryptographically binds signatures to specific contract + chain combinations, preventing replay attacks.

import * as EIP712 from '@voltaire/crypto/eip712';
import * as Address from '@voltaire/primitives/address';

const domain = {
  name: 'MyDApp',           // Application name
  version: '1',             // Version string
  chainId: 1n,              // Chain ID (bigint)
  verifyingContract: Address.from('0x742d35Cc6634C0532925a3b844Bc9e7595f251e3')
};

// Hash the domain separator
const domainHash = EIP712.Domain.hash(domain);
// Returns: Uint8Array(32) - keccak256 hash

Domain fields:

• name: DApp name shown to user
• version: Versioning for signature schema changes
• chainId: Prevents cross-chain replay (mainnet=1, polygon=137)
• verifyingContract: Contract that will verify the signature
• salt (optional): Additional entropy for extra separation

Type Definitions

Define message structure using Solidity-like type definitions:

const types = {
  // Simple struct
  Person: [
    { name: 'name', type: 'string' },
    { name: 'wallet', type: 'address' }
  ],

  // Struct with nested reference
  Mail: [
    { name: 'from', type: 'Person' },      // References Person type
    { name: 'to', type: 'Person' },
    { name: 'contents', type: 'string' }
  ]
};

// Encode type for debugging
const typeString = EIP712.encodeType('Mail', types);
// "Mail(Person from,Person to,string contents)Person(string name,address wallet)"

// Get type hash
const typeHash = EIP712.hashType('Mail', types);

Supported types:

• Integers: uint8 through uint256, int8 through int256
• Address: address
• Boolean: bool
• Fixed bytes: bytes1 through bytes32
• Dynamic: bytes, string
• Arrays: type[], type[N]
• Custom structs: Referenced by name

Hashing Typed Data

Complete typed data combines domain, types, primary type, and message:

import * as EIP712 from '@voltaire/crypto/eip712';
import * as Address from '@voltaire/primitives/address';

const typedData = {
  domain: {
    name: 'Ether Mail',
    version: '1',
    chainId: 1n,
    verifyingContract: Address.from('0xCcCCccccCCCCcCCCCCCcCcCccCcCCCcCcccccccC')
  },
  types: {
    Person: [
      { name: 'name', type: 'string' },
      { name: 'wallet', type: 'address' }
    ],
    Mail: [
      { name: 'from', type: 'Person' },
      { name: 'to', type: 'Person' },
      { name: 'contents', type: 'string' }
    ]
  },
  primaryType: 'Mail',
  message: {
    from: {
      name: 'Alice',
      wallet: Address.from('0xCD2a3d9F938E13CD947Ec05AbC7FE734Df8DD826')
    },
    to: {
      name: 'Bob',
      wallet: Address.from('0xbBbBBBBbbBBBbbbBbbBbbbbBBbBbbbbBbBbbBBbB')
    },
    contents: 'Hello, Bob!'
  }
};

// Hash for signing: keccak256("\x19\x01" || domainSeparator || hashStruct(message))
const hash = EIP712.hashTypedData(typedData);
// Returns: Uint8Array(32)

Signing Typed Data

Sign with a private key to produce ECDSA signature:

import * as EIP712 from '@voltaire/crypto/eip712';
import * as PrivateKey from '@voltaire/primitives/private-key';

// Your private key (32 bytes)
const privateKey = PrivateKey.from('0x...');

// Sign - produces { r, s, v }
const signature = EIP712.signTypedData(typedData, privateKey);

console.log(signature.r);  // Uint8Array(32)
console.log(signature.s);  // Uint8Array(32)
console.log(signature.v);  // 27 or 28

The signature can be submitted to:

• Smart contracts via ecrecover
• Relayers for meta-transactions
• Order books for DEX orders

Verifying Typed Signatures

Recover the signer’s address and verify it matches expected:

import * as EIP712 from '@voltaire/crypto/eip712';
import * as Address from '@voltaire/primitives/address';

// Recover signer address from signature
const recoveredAddress = EIP712.recoverAddress(signature, typedData);

// Verify against expected signer
const expectedSigner = Address.from('0xCD2a3d9F938E13CD947Ec05AbC7FE734Df8DD826');
const isValid = EIP712.verifyTypedData(signature, typedData, expectedSigner);

if (isValid) {
  console.log('Signature is valid');
} else {
  console.log('Invalid signature or wrong signer');
}

Verification uses constant-time comparison to prevent timing attacks.

Complete Example: ERC-2612 Permit

Gasless token approvals using EIP-712:

import * as EIP712 from '@voltaire/crypto/eip712';
import * as Address from '@voltaire/primitives/address';
import * as PrivateKey from '@voltaire/primitives/private-key';

// Token holder's private key
const ownerKey = PrivateKey.from('0x...');

// Permit message for gasless approval
const permitData = {
  domain: {
    name: 'USD Coin',
    version: '2',
    chainId: 1n,
    verifyingContract: Address.from('0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48')
  },
  types: {
    Permit: [
      { name: 'owner', type: 'address' },
      { name: 'spender', type: 'address' },
      { name: 'value', type: 'uint256' },
      { name: 'nonce', type: 'uint256' },
      { name: 'deadline', type: 'uint256' }
    ]
  },
  primaryType: 'Permit',
  message: {
    owner: Address.from('0xOwnerAddress...'),
    spender: Address.from('0xSpenderAddress...'),
    value: 1000000n,        // 1 USDC (6 decimals)
    nonce: 0n,              // Current nonce from contract
    deadline: 1735689600n   // Unix timestamp expiry
  }
};

// Sign the permit
const signature = EIP712.signTypedData(permitData, ownerKey);

// Submit to contract: permit(owner, spender, value, deadline, v, r, s)
// Relayer pays gas, owner's tokens get approved

Validation

Validate typed data structure before signing:

import * as EIP712 from '@voltaire/crypto/eip712';

try {
  EIP712.validate(typedData);
  console.log('Valid typed data structure');
} catch (error) {
  console.error('Invalid:', error.message);
}

Validation checks:

• Primary type exists in types
• All referenced types are defined
• Message fields match type definitions
• No circular type references

Error Handling

import * as EIP712 from '@voltaire/crypto/eip712';
import {
  Eip712Error,
  Eip712TypeNotFoundError,
  Eip712InvalidMessageError,
  Eip712EncodingError
} from '@voltaire/crypto/eip712';

try {
  const hash = EIP712.hashTypedData(typedData);
} catch (error) {
  if (error instanceof Eip712TypeNotFoundError) {
    // Referenced type not in types object
  } else if (error instanceof Eip712InvalidMessageError) {
    // Message doesn't match type definition
  } else if (error instanceof Eip712EncodingError) {
    // Value encoding failed (wrong type, size, etc.)
  }
}

Security Best Practices

1. Always include deadlines - Prevent signature reuse after expiry
2. Use nonces - Contract tracks nonces to prevent replay
3. Validate before signing - Call validate() on user-provided data
4. Verify recovered address - Never trust signatures without verification
5. Include chainId - Prevents cross-chain replay attacks

// Good: Time-bounded with nonce
message: {
  action: 'approve',
  nonce: await contract.nonces(userAddress),
  deadline: BigInt(Math.floor(Date.now() / 1000) + 3600) // 1 hour
}

API Reference

Function	Description
hashTypedData(typedData)	Hash complete typed data for signing
signTypedData(typedData, privateKey)	Sign typed data, returns {r, s, v}
verifyTypedData(signature, typedData, address)	Verify signature matches expected signer
recoverAddress(signature, typedData)	Recover signer address from signature
Domain.hash(domain)	Hash domain separator
encodeType(primaryType, types)	Get canonical type encoding string
hashType(primaryType, types)	Hash type encoding
hashStruct(primaryType, message, types)	Hash struct data
encodeValue(type, value, types)	Encode single value
validate(typedData)	Validate typed data structure
format(typedData)	Format for human-readable display

Related

• EIP-712 Specification
• ERC-2612 Permit
• Secp256k1 Signing
• Keccak256 Hashing