@integraledger/lcp-binding-evm-common 0.9.0

package/dist/events.js

@@ -0,0 +1,90 @@
+/**
+ * On-chain event helpers for the EIP-3009 binding: the `AuthorizationUsed` ABI and the transport-free
+ * atrHash-recovery scan (the caller fetches the receipt with its own viem client and passes `{ logs }`).
+ */
+import { atrHashEquals } from "@integraledger/lcp-kernel";
+import { decodeEventLog } from "viem";
+/** Build a `SettlementRef` without materializing absent fields — `exactOptionalPropertyTypes` forbids
+ *  `txHash: undefined`, so the spreads keep the ref exactly as sparse as the caller's knowledge. Shared
+ *  by the EVM adapters (it was byte-identical in two of them and inlined in the third). */
+export function refOf(chainId, txHash, logIndex) {
+    return {
+        chainId,
+        ...(txHash !== undefined ? { txHash } : {}),
+        ...(logIndex !== null ? { logIndex } : {}),
+    };
+}
+/** USDC `AuthorizationUsed(authorizer, nonce)` — both indexed; the on-chain artifact of every EIP-3009
+ *  settlement. `nonce` carries the atrHash (WLD-3: recoverable, forward-indexable on the nonce topic). */
+export const AUTHORIZATION_USED_ABI = [
+    {
+        type: "event",
+        name: "AuthorizationUsed",
+        inputs: [
+            { name: "authorizer", type: "address", indexed: true },
+            { name: "nonce", type: "bytes32", indexed: true },
+        ],
+        anonymous: false,
+    },
+];
+/**
+ * Decode every `AuthorizationUsed(authorizer, indexed nonce)` in a set of logs (a single settlement's
+ * logs, from `ChainReader.getTransactionLogs`, or a range query). This is the EXTRACT path (recover the
+ * committed nonce), distinct from `verifyAtrHashOnChain`'s CHECK path (assert a known nonce is present).
+ * When `asset` is supplied only that token's events are read; otherwise every AuthorizationUsed is decoded.
+ */
+export function readAuthorizationUsed(logs, asset) {
+    const want = asset?.toLowerCase();
+    const out = [];
+    for (const log of logs) {
+        const address = log.address.toLowerCase();
+        if (want !== undefined && address !== want)
+            continue;
+        try {
+            const decoded = decodeEventLog({
+                abi: AUTHORIZATION_USED_ABI,
+                data: log.data,
+                topics: log.topics,
+            });
+            if (decoded.eventName === "AuthorizationUsed")
+                out.push({
+                    nonce: decoded.args.nonce.toLowerCase(),
+                    authorizer: decoded.args.authorizer.toLowerCase(),
+                    logIndex: log.logIndex,
+                    address,
+                });
+        }
+        catch {
+            // Not an AuthorizationUsed log from this ABI — ignore.
+        }
+    }
+    return out;
+}
+/**
+ * Confirm the atrHash was committed on-chain: scan a settlement tx receipt for the token's
+ * `AuthorizationUsed(authorizer, indexed nonce)` event and assert `nonce === atrHash` (case-insensitive).
+ */
+export function verifyAtrHashOnChain(receipt, params) {
+    const asset = params.asset.toLowerCase();
+    for (const log of receipt.logs) {
+        if (log.address.toLowerCase() !== asset)
+            continue;
+        try {
+            const decoded = decodeEventLog({
+                abi: AUTHORIZATION_USED_ABI,
+                data: log.data,
+                topics: log.topics,
+            });
+            if (decoded.eventName === "AuthorizationUsed") {
+                const nonce = decoded.args.nonce.toLowerCase();
+                if (atrHashEquals(nonce, params.atrHash))
+                    return { ok: true, onChainNonce: nonce };
+            }
+        }
+        catch {
+            // Not an AuthorizationUsed log from this ABI — ignore.
+        }
+    }
+    return { ok: false, onChainNonce: null };
+}
+//# sourceMappingURL=events.js.map

package/dist/events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { makeChainReader } from "./client.js";
+export { decodeEasAttestation, EAS_GET_ATTESTATION_ABI, type EasAttestation, isEasValidAsOf, type RawEasAttestation, readEasAttestation, } from "./eas.js";
+export { hashEip712 } from "./eip712.js";
+export { assertBytes32, type BuildEip3009Input, buildEip3009TypedData, type Eip3009Authorization, type Eip3009TypedData, eip155ChainId, type LcpEvmSigner, TRANSFER_WITH_AUTHORIZATION_TYPE, } from "./eip3009.js";
+export { assetWasTransferred, ERC20_TRANSFER_TOPIC0 } from "./erc20.js";
+export { ACCEPTANCE_DOMAIN_NAME, ACCEPTANCE_DOMAIN_VERSION, ACCEPTANCE_ENVELOPE_TYPE, type AcceptanceSignatureInput, type AcceptanceTypedData, type AcceptanceVerifyOpts, buildAcceptanceTypedData, EVM_ACCEPTANCE_SCHEMES, EVM_PAYLOAD_TYPES, type EvmAcceptanceScheme, type EvmPayloadType, isEvmAcceptanceScheme, isEvmPayloadType, makeEvmAcceptanceVerifier, makeLocalEvmSigner, rfc3339ToUnixSeconds, verifyAcceptanceSignature, } from "./erc1271.js";
+export { AUTHORIZATION_USED_ABI, type AuthorizationUsedEvent, type OnChainAtrHashProof, readAuthorizationUsed, refOf, verifyAtrHashOnChain, } from "./events.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EACL,oBAAoB,EACpB,uBAAuB,EACvB,KAAK,cAAc,EACnB,cAAc,EACd,KAAK,iBAAiB,EACtB,kBAAkB,GACnB,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EACL,aAAa,EACb,KAAK,iBAAiB,EACtB,qBAAqB,EACrB,KAAK,oBAAoB,EACzB,KAAK,gBAAgB,EACrB,aAAa,EACb,KAAK,YAAY,EACjB,gCAAgC,GACjC,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AACxE,OAAO,EACL,sBAAsB,EACtB,yBAAyB,EACzB,wBAAwB,EACxB,KAAK,wBAAwB,EAC7B,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,EACzB,wBAAwB,EACxB,sBAAsB,EACtB,iBAAiB,EACjB,KAAK,mBAAmB,EACxB,KAAK,cAAc,EACnB,qBAAqB,EACrB,gBAAgB,EAChB,yBAAyB,EACzB,kBAAkB,EAClB,oBAAoB,EACpB,yBAAyB,GAC1B,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,sBAAsB,EACtB,KAAK,sBAAsB,EAC3B,KAAK,mBAAmB,EACxB,qBAAqB,EACrB,KAAK,EACL,oBAAoB,GACrB,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -0,0 +1,8 @@
+export { makeChainReader } from "./client.js";
+export { decodeEasAttestation, EAS_GET_ATTESTATION_ABI, isEasValidAsOf, readEasAttestation, } from "./eas.js";
+export { hashEip712 } from "./eip712.js";
+export { assertBytes32, buildEip3009TypedData, eip155ChainId, TRANSFER_WITH_AUTHORIZATION_TYPE, } from "./eip3009.js";
+export { assetWasTransferred, ERC20_TRANSFER_TOPIC0 } from "./erc20.js";
+export { ACCEPTANCE_DOMAIN_NAME, ACCEPTANCE_DOMAIN_VERSION, ACCEPTANCE_ENVELOPE_TYPE, buildAcceptanceTypedData, EVM_ACCEPTANCE_SCHEMES, EVM_PAYLOAD_TYPES, isEvmAcceptanceScheme, isEvmPayloadType, makeEvmAcceptanceVerifier, makeLocalEvmSigner, rfc3339ToUnixSeconds, verifyAcceptanceSignature, } from "./erc1271.js";
+export { AUTHORIZATION_USED_ABI, readAuthorizationUsed, refOf, verifyAtrHashOnChain, } from "./events.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EACL,oBAAoB,EACpB,uBAAuB,EAEvB,cAAc,EAEd,kBAAkB,GACnB,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EACL,aAAa,EAEb,qBAAqB,EAGrB,aAAa,EAEb,gCAAgC,GACjC,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AACxE,OAAO,EACL,sBAAsB,EACtB,yBAAyB,EACzB,wBAAwB,EAIxB,wBAAwB,EACxB,sBAAsB,EACtB,iBAAiB,EAGjB,qBAAqB,EACrB,gBAAgB,EAChB,yBAAyB,EACzB,kBAAkB,EAClB,oBAAoB,EACpB,yBAAyB,GAC1B,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,sBAAsB,EAGtB,qBAAqB,EACrB,KAAK,EACL,oBAAoB,GACrB,MAAM,aAAa,CAAC"}

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@integraledger/lcp-binding-evm-common",
+  "version": "0.9.0",
+  "description": "Shared EVM machinery for LCP rail bindings: typed-data construction and signature verification.",
+  "keywords": [
+    "lcp",
+    "legal-context-protocol",
+    "legal-terms",
+    "agentic-commerce",
+    "settlement",
+    "atr-hash",
+    "evm",
+    "eip-712",
+    "eip-3009"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src",
+    "CHANGELOG.md",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/IntegraLedger/integra-protocol.git",
+    "directory": "packages/binding-evm-common"
+  },
+  "bugs": {
+    "url": "https://github.com/IntegraLedger/integra-protocol/issues"
+  },
+  "homepage": "https://github.com/IntegraLedger/integra-protocol/tree/main/packages/binding-evm-common#readme",
+  "dependencies": {
+    "viem": "2.55.11",
+    "@integraledger/lcp-authority": "0.9.0",
+    "@integraledger/lcp-binding-core": "0.9.0",
+    "@integraledger/lcp-kernel": "0.9.0"
+  },
+  "devDependencies": {
+    "@types/node": "24.13.3",
+    "fast-check": "4.9.0",
+    "vitest": "4.1.10"
+  },
+  "license": "Apache-2.0",
+  "engines": {
+    "node": ">=24"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  }
+}

package/src/client.ts

@@ -0,0 +1,31 @@
+import type {
+  ChainReader,
+  SettlementRef,
+} from "@integraledger/lcp-binding-core";
+import type { PublicClient } from "viem";
+
+/**
+ * Adapt a viem `PublicClient` into binding-core's `ChainReader` port (viem lives here and in the two
+ * EVM adapters, nowhere else). Imperative shell over viem — the pure verifier logic reads through the port.
+ */
+export function makeChainReader(client: PublicClient): ChainReader {
+  return {
+    getLogs: (q) => client.getLogs(q as never),
+    getTransactionLogs: async (ref: SettlementRef): Promise<unknown[]> => {
+      if (ref.txHash === undefined)
+        throw new Error(
+          "getTransactionLogs requires a txHash on the SettlementRef",
+        );
+      const receipt = await client.getTransactionReceipt({ hash: ref.txHash });
+      return [...receipt.logs];
+    },
+    readContract: (c) => client.readContract(c as never),
+    blockTime: async (ref: SettlementRef): Promise<bigint> => {
+      if (ref.txHash === undefined)
+        throw new Error("blockTime requires a txHash on the SettlementRef");
+      const receipt = await client.getTransactionReceipt({ hash: ref.txHash });
+      const block = await client.getBlock({ blockNumber: receipt.blockNumber });
+      return block.timestamp;
+    },
+  };
+}

package/src/eas.ts

@@ -0,0 +1,120 @@
+/**
+ * EAS (Ethereum Attestation Service) read — the EVM substrate adapter for a profiled attestation
+ * (`authority`'s attestation-profile.ts interprets attestations generically; the per-substrate on-chain
+ * read lives here, pure over the injected viem client). This reads `getAttestation(uid)` and
+ * normalizes the on-chain `Attestation` struct into a typed, as-of-checkable value. It verifies nothing
+ * cryptographically beyond the chain's own state — EAS attestations are on-chain records, so their
+ * validity is a state read (attester, expiration, revocation), evaluated AS OF a settlement time exactly
+ * like `authority`'s status-list discipline (never "is it valid now" — "was it valid at settlement").
+ */
+import type { Hex, PublicClient } from "viem";
+
+/** EAS `getAttestation(bytes32) returns (Attestation)` — the canonical struct (EAS v0.26+ field order). */
+export const EAS_GET_ATTESTATION_ABI = [
+  {
+    type: "function",
+    name: "getAttestation",
+    stateMutability: "view",
+    inputs: [{ name: "uid", type: "bytes32" }],
+    outputs: [
+      {
+        type: "tuple",
+        name: "",
+        components: [
+          { name: "uid", type: "bytes32" },
+          { name: "schema", type: "bytes32" },
+          { name: "time", type: "uint64" },
+          { name: "expirationTime", type: "uint64" },
+          { name: "revocationTime", type: "uint64" },
+          { name: "refUID", type: "bytes32" },
+          { name: "recipient", type: "address" },
+          { name: "attester", type: "address" },
+          { name: "revocable", type: "bool" },
+          { name: "data", type: "bytes" },
+        ],
+      },
+    ],
+  },
+] as const;
+
+/** The raw shape viem decodes an EAS `Attestation` tuple into (named components → object). */
+export interface RawEasAttestation {
+  uid: Hex;
+  schema: Hex;
+  time: bigint;
+  expirationTime: bigint;
+  revocationTime: bigint;
+  refUID: Hex;
+  recipient: Hex;
+  attester: Hex;
+  revocable: boolean;
+  data: Hex;
+}
+
+/** A normalized EAS attestation (addresses lowercased; times as bigints; `exists` = a non-zero uid). */
+export interface EasAttestation {
+  uid: Hex;
+  schema: Hex;
+  time: bigint;
+  expirationTime: bigint;
+  revocationTime: bigint;
+  refUID: Hex;
+  recipient: Hex;
+  attester: Hex;
+  revocable: boolean;
+  data: Hex;
+  /** EAS returns a zero-filled struct for an unknown uid — this flags that non-existence explicitly. */
+  exists: boolean;
+}
+
+const ZERO_UID =
+  "0x0000000000000000000000000000000000000000000000000000000000000000";
+
+/** Normalize viem's decoded tuple into an `EasAttestation` (idempotent field mapping; addresses lowercased). */
+export function decodeEasAttestation(raw: RawEasAttestation): EasAttestation {
+  return {
+    uid: raw.uid.toLowerCase() as Hex,
+    schema: raw.schema.toLowerCase() as Hex,
+    time: raw.time,
+    expirationTime: raw.expirationTime,
+    revocationTime: raw.revocationTime,
+    refUID: raw.refUID.toLowerCase() as Hex,
+    recipient: raw.recipient.toLowerCase() as Hex,
+    attester: raw.attester.toLowerCase() as Hex,
+    revocable: raw.revocable,
+    data: raw.data.toLowerCase() as Hex,
+    exists: raw.uid.toLowerCase() !== ZERO_UID,
+  };
+}
+
+/**
+ * Was this attestation valid AS OF `asOfUnixSeconds`? — it must exist, not have been revoked at/before the
+ * as-of time (revocationTime 0 = never revoked), and not have expired by then (expirationTime 0 = no expiry).
+ * EAS has no historical query, so a live read yields today's revocationTime; a settlement-time snapshot of the
+ * uid is the authority (same as the Bitstring status-list as-of rule) — this predicate states the semantics.
+ */
+export function isEasValidAsOf(
+  att: EasAttestation,
+  asOfUnixSeconds: bigint,
+): boolean {
+  if (!att.exists) return false;
+  if (att.revocationTime !== 0n && att.revocationTime <= asOfUnixSeconds)
+    return false;
+  if (att.expirationTime !== 0n && att.expirationTime <= asOfUnixSeconds)
+    return false;
+  return true;
+}
+
+/** Read + normalize an EAS attestation by uid, over the injected viem client (imperative shell). */
+export async function readEasAttestation(
+  client: PublicClient,
+  params: { eas: string; uid: string },
+): Promise<EasAttestation> {
+  const raw = (await client.readContract({
+    address: params.eas as Hex,
+    abi: EAS_GET_ATTESTATION_ABI,
+    functionName: "getAttestation",
+    args: [params.uid as Hex],
+  })) as RawEasAttestation;
+  return decodeEasAttestation(raw);
+}

package/src/eip3009.ts

@@ -0,0 +1,142 @@
+/**
+ * The EIP-3009 `TransferWithAuthorization` typed-data machinery for the LCP canonical EVM binding
+ * `LCP-X402-EVM-NONCE-1`: the buyer signs an EIP-3009 authorization whose `nonce` field IS the
+ * `atrHash`, so the fingerprint is committed on-chain in the token's `AuthorizationUsed(authorizer,
+ * indexed nonce)` event — no overlay contract.
+ *
+ * The x402-client scheme class is deliberately NOT here; it lives in binding-evm-x402. This module is
+ * protocol-agnostic typed-data construction, viem-only.
+ */
+import { type Address, getAddress, type Hex, type TypedDataDomain } from "viem";
+
+/** EIP-3009 TransferWithAuthorization typed-data field layout (USDC FiatTokenV2). */
+export const TRANSFER_WITH_AUTHORIZATION_TYPE = {
+  TransferWithAuthorization: [
+    { name: "from", type: "address" },
+    { name: "to", type: "address" },
+    { name: "value", type: "uint256" },
+    { name: "validAfter", type: "uint256" },
+    { name: "validBefore", type: "uint256" },
+    { name: "nonce", type: "bytes32" },
+  ],
+} as const;
+
+/** Parse the EIP-155 chain id out of a CAIP-2 network string; throws on anything that is not
+ *  `eip155:<digits>` (never defaults — the chain id binds the EIP-712 domain). */
+export function eip155ChainId(network: string): number {
+  const m = /^eip155:(\d+)$/.exec(network);
+  if (!m)
+    throw new Error(`expected CAIP-2 network "eip155:<id>", got "${network}"`);
+  return Number(m[1]);
+}
+
+/** The atrHash rides the EIP-3009 nonce as a 0x-prefixed 32-byte value. Any-case digits accepted
+ *  (ATR canon), then lowercased for the on-chain nonce (the nonce is matched lowercase on decode). */
+export function assertBytes32(value: string): Hex {
+  if (!/^0x[0-9a-fA-F]{64}$/.test(value))
+    throw new Error(
+      `atrHash must be a 0x-prefixed 32-byte (64 hex) value to ride as the EIP-3009 nonce, got "${value}"`,
+    );
+  return value.toLowerCase() as Hex;
+}
+
+/** The EIP-3009 authorization object (string-encoded uint fields, as the x402 wire expects). */
+export interface Eip3009Authorization {
+  from: Address;
+  to: Address;
+  value: string;
+  validAfter: string;
+  validBefore: string;
+  nonce: Hex;
+}
+
+/** Everything needed to build an EIP-3009 authorization whose `nonce` IS the atrHash. Two fields are the
+ *  usual mistake: `tokenName`/`tokenVersion` are the token's own EIP-712 domain and DIFFER between USDC
+ *  deployments, so copying them from one chain to another yields a signature the token rejects. Amounts
+ *  and times are strings here (base units, unix seconds) and become `bigint` in the typed data. */
+export interface BuildEip3009Input {
+  /** The LCP carrier value — becomes the on-chain nonce. */
+  atrHash: string;
+  /** Payer address; checksummed via `getAddress`. */
+  from: string;
+  /** Recipient address; checksummed via `getAddress`. */
+  to: string;
+  /** Amount in token base units (string). */
+  value: string;
+  validAfter: string;
+  validBefore: string;
+  chainId: number;
+  /** EIP-712 domain `name`/`version` for the token (USDC). */
+  tokenName: string;
+  tokenVersion: string;
+  /** Token contract — the EIP-712 `verifyingContract`; checksummed via `getAddress`. */
+  verifyingContract: string;
+}
+
+/** The EIP-712 payload a payer signs for an EIP-3009 transfer. Distinct from the authorization: the
+ *  authorization is what goes on the wire, this is what is signed, and their numeric fields differ in type
+ *  (`bigint` here, decimal strings there) because that is what each side requires. */
+export type Eip3009TypedData = {
+  domain: TypedDataDomain;
+  types: typeof TRANSFER_WITH_AUTHORIZATION_TYPE;
+  primaryType: "TransferWithAuthorization";
+  message: {
+    from: Address;
+    to: Address;
+    value: bigint;
+    validAfter: bigint;
+    validBefore: bigint;
+    nonce: Hex;
+  };
+};
+
+/**
+ * Build the EIP-3009 authorization + the EIP-712 typed-data to sign, with `nonce = atrHash`.
+ * `authorization` is the wire payload; `typedData` is what the signer signs.
+ */
+export function buildEip3009TypedData(i: BuildEip3009Input): {
+  authorization: Eip3009Authorization;
+  typedData: Eip3009TypedData;
+} {
+  const nonce = assertBytes32(i.atrHash);
+  const from = getAddress(i.from);
+  const to = getAddress(i.to);
+  const authorization: Eip3009Authorization = {
+    from,
+    to,
+    value: i.value,
+    validAfter: i.validAfter,
+    validBefore: i.validBefore,
+    nonce,
+  };
+  const typedData: Eip3009TypedData = {
+    domain: {
+      name: i.tokenName,
+      version: i.tokenVersion,
+      chainId: i.chainId,
+      verifyingContract: getAddress(i.verifyingContract),
+    },
+    types: TRANSFER_WITH_AUTHORIZATION_TYPE,
+    primaryType: "TransferWithAuthorization",
+    message: {
+      from,
+      to,
+      value: BigInt(i.value),
+      validAfter: BigInt(i.validAfter),
+      validBefore: BigInt(i.validBefore),
+      nonce,
+    },
+  };
+  return { authorization, typedData };
+}
+
+/** Minimal EVM signer — the structural subset a scheme needs (viem LocalAccount / CDP account / injected wallet). */
+export interface LcpEvmSigner {
+  readonly address: Address;
+  signTypedData(message: {
+    domain: Record<string, unknown>;
+    types: Record<string, unknown>;
+    primaryType: string;
+    message: Record<string, unknown>;
+  }): Promise<Hex>;
+}

package/src/eip712.ts

@@ -0,0 +1,11 @@
+import { hashTypedData } from "viem";
+import type { Eip3009TypedData } from "./eip3009.js";
+
+/**
+ * The EIP-712 digest of an EIP-3009 typed-data message — viem's reference EIP-712 hashing
+ * (keccak256(0x1901 ‖ domainSeparator ‖ hashStruct(message))). This is what the signer signs over
+ * and what pins the typed-data structure in the vector fixtures.
+ */
+export function hashEip712(typedData: Eip3009TypedData): `0x${string}` {
+  return hashTypedData(typedData);
+}