feat: add ERC20Votes delegateBySig EIP-712 helpers + two-step example flow

Adds reusable EIP-712 builders for OpenZeppelin `ERC20Votes`-style
`delegateBySig` so cold-custody clients can delegate voting power to a
self-custody hot wallet without moving funds:

- `buildErc20VotesDelegationTypedData` returns the canonical
  `Delegation(address delegatee,uint256 nonce,uint256 expiry)` typed
  data with a well-formed `EIP712Domain` block.
- `encodeErc20VotesDelegationTypedDataDigest(Hex)` produces the v4
  `\x19\x01 || hashStruct(domain) || hashStruct(message)` digest used
  by BitGo typed-data tx requests (`messageEncoded` / `typedDataEncoded`).
- `encodeDelegateBySigCalldata` returns the ABI-encoded on-chain
  submission payload so any relayer can post the signature.
- Ships a WLFI Ethereum mainnet domain helper as a reference template.

Also:
- Wires `MessageStandardType.EIP712` through
  `createTxRequestWithIntentForTypedDataSigning` /
  `IntentOptionsForTypedData` / `PopulatedIntentForTypedDataSigning` so
  WP can distinguish typed-data delegation messages from plain
  `signMessage` intents and route them to TAT instead of sendQ.
- Adds the runnable two-step client flow under examples:
  - `examples/ts/eth/push-erc20-votes-delegation-txrequest.ts` creates
    a custodial tx request via `wallet.signTypedData(...)` and prints
    the `txRequestId` for the operator to sign in TAT.
  - `examples/ts/eth/fetch-erc20-votes-delegation-txrequest-signature.ts`
    reads the latest signed snapshot of that tx request and prints
    `v, r, s` plus optional `delegateBySig` calldata.
- Adds client-facing docs at
  `examples/docs/erc20-votes-delegate-by-sig.md` covering the full
  push -> TAT signs -> fetch -> submit on-chain flow.
- Unit tests cover the domain/message hash, digest hex, calldata, and
  factory wiring.

Ticket: CGD-842
Co-authored-by: Cursor <cursoragent@cursor.com>

Author: 0xPrabh

examples/docs/erc20-votes-delegate-by-sig.md

@@ -0,0 +1,158 @@
+# ERC20Votes `delegateBySig` from a BitGo cold (custodial) wallet
+
+> Linear: [CGD-842](https://linear.app/bitgo/issue/CGD-842) ·
+> PR: [BitGo/BitGoJS#8660](https://github.com/BitGo/BitGoJS/pull/8660)
+
+This is the client workflow for delegating governance voting power from an
+**ETH MPC custodial cold wallet** (e.g. WLFI, UNI, COMP, ARB, ENS, OP, …) to a
+self-custody hot wallet **without moving funds and without paying gas from the
+cold wallet**. Funds stay in custody; only the *votes* are delegated.
+
+The pattern uses OpenZeppelin `ERC20Votes.delegateBySig`: BitGo signs the
+EIP-712 typed-data message with your cold wallet's MPC keys, and any relayer
+(or your hot wallet) submits the resulting `delegateBySig(...)` transaction.
+
+The flow is **two scripts**:
+
+| Step | Script | What it does |
+| --- | --- | --- |
+| 1 | [`examples/ts/eth/push-erc20-votes-delegation-txrequest.ts`](../ts/eth/push-erc20-votes-delegation-txrequest.ts) | Creates a custodial tx request (`signTypedStructuredData` intent) and prints a `txRequestId`. The unsigned message appears in TAT for approval / signing. |
+| 2 | [`examples/ts/eth/fetch-erc20-votes-delegation-txrequest-signature.ts`](../ts/eth/fetch-erc20-votes-delegation-txrequest-signature.ts) | Once TAT signs, fetches the tx request and prints `v, r, s` (and optional `delegateBySig` calldata). |
+
+Between the two steps, signing happens in **TAT** (operator-driven). You only
+re-run the fetch script after the message moves to `signed`.
+
+## Prerequisites
+
+- Node.js `>=20`
+- A repo-root `.env` file (the scripts load this via `dotenv`)
+- A custodial ETH MPC wallet on BitGo
+- A BitGo access token with permissions on that wallet
+- For test/non-WLFI tokens: the token's on-chain `eip712Domain()` values
+- A JSON-RPC URL for the chain that hosts the token (used to read
+  `nonces(delegator)`), or the nonce fetched out-of-band
+
+## `.env` template
+
+Both scripts read the same environment variable names.
+
+```bash
+# auth
+BITGO_ACCESS_TOKEN=...             # or ACCESS_TOKEN
+BITGO_ENV=test                     # or `prod`
+
+# wallet
+WALLET_ID=...
+COIN=hteth                         # eth | teth | hteth (must match the wallet)
+
+# delegation message
+DELEGATEE=0x...                    # address that will vote (often a hot wallet)
+EXPIRY=                            # optional unix seconds; default: now + 1h
+
+# nonce lookup (one of these)
+ETH_RPC_URL=https://...            # script will call nonces(delegator) on the token
+NONCE=                             # OR set this manually if you already have it
+
+# domain (one of these)
+EIP712_DOMAIN_JSON={"name":"...","version":"...","chainId":1,"verifyingContract":"0x..."}
+# (omit EIP712_DOMAIN_JSON if you are running BITGO_ENV=prod COIN=eth and want
+#  the WLFI mainnet defaults baked into the script)
+
+# step 2 only — set after step 1 prints it
+TX_REQUEST_ID=
+```
+
+## Step 1 — push the EIP-712 delegation tx request
+
+From the repo root:
+
+```bash
+npx tsx examples/ts/eth/push-erc20-votes-delegation-txrequest.ts
+```
+
+The script will:
+
+1. Fetch the token's `nonces(delegator)` over `ETH_RPC_URL` (or use `NONCE`).
+2. Build the OZ `Delegation(address delegatee,uint256 nonce,uint256 expiry)`
+   typed-data via `Erc20VotesDelegationMessageBuilder` from
+   `@bitgo/abstract-eth`.
+3. `POST /api/v2/wallet/{walletId}/txrequests` with intent
+   `signTypedStructuredData`, `isTss: true`, and
+   `messageStandardType: EIP712`.
+4. Print the created tx request, including `txRequestId`.
+
+**Save the `txRequestId`.** Put it in `.env` as `TX_REQUEST_ID` for step 2.
+
+The unsigned message now appears in **TAT** for the operator to approve and
+sign with the cold wallet's MPC keys. WP routes EIP-712 typed-data messages
+through TAT (Kafka topic) instead of `sendQ` because the intent is tagged
+`messageStandardType: EIP712`.
+
+## Step 2 — fetch the signature once TAT signs
+
+```bash
+npx tsx examples/ts/eth/fetch-erc20-votes-delegation-txrequest-signature.ts
+```
+
+The script will:
+
+1. `GET /api/v2/wallet/{walletId}/txrequests?txRequestIds={id}&latest=true`.
+2. The list endpoint returns multiple **versioned snapshots** of the same
+   `txRequestId` as the message moves through MPC rounds. The script picks
+   the snapshot whose `messages[0].state === "signed"` (and whose `txHash`
+   is a complete 65-byte ECDSA hex).
+3. If no signed snapshot exists yet, it prints
+   `Message not signed yet, try again later.` and exits. Re-run once TAT has
+   signed.
+4. Otherwise it splits `messages[0].txHash` into **`v`, `r`, `s`** with
+   `ethers.utils.splitSignature` and prints them, plus ABI-encoded
+   `delegateBySig(delegatee, nonce, expiry, v, r, s)` calldata when
+   `messageRaw` is the delegation typed-data JSON.
+
+## Step 3 — submit `delegateBySig` on-chain
+
+Take `v, r, s` (or the printed calldata) and submit from any address. The
+cold wallet does not pay gas and does not move funds.
+
+```ts
+await wlfiToken.delegateBySig(delegatee, nonce, expiry, v, r, s);
+```
+
+If you printed calldata in step 2, broadcast a normal transaction from your
+hot wallet with `to = domain.verifyingContract` and `data = <calldata>`.
+
+After confirmation, on-chain `delegates(coldWallet)` returns `delegatee` and
+the cold wallet's voting power is delegated.
+
+## Troubleshooting
+
+- **`Set BITGO_ACCESS_TOKEN ...`** — `.env` was not found or the variable is
+  unset. The scripts try `process.cwd()/.env` first, then
+  `<script-dir>/../../../.env`. Run from the repo root, or export the
+  variables in your shell.
+- **`Coin unsupported` from step 1** — `COIN` must match the wallet's chain
+  in WP. Try `hteth` for Holesky, `eth` for mainnet.
+- **Step 2 prints `Message not signed yet.`** — TAT has not signed yet, or
+  the operator rejected the request. Check TAT for the `txRequestId` from
+  step 1; re-run step 2 after it moves to `signed`.
+- **Multiple snapshots returned** — The list endpoint legitimately returns
+  one row per MPC round. Step 2 always picks the signed snapshot when
+  available, so this is informational.
+- **`splitSignature` throws** — Means `messages[0].txHash` is not a complete
+  65-byte hex. Wait for `messages[0].state === "signed"` and re-run.
+
+## Where this lives in the SDK
+
+- `@bitgo/abstract-eth` (`modules/abstract-eth/src/lib/eip712/erc20VotesDelegation.ts`)
+  - `buildErc20VotesDelegationTypedData({ domain, message })`
+  - `encodeErc20VotesDelegationTypedDataDigest(Hex)`
+  - `encodeDelegateBySigCalldata({ delegatee, nonce, expiry, v, r, s })`
+  - `wlfiEthereumMainnetDelegationDomain()`
+- `@bitgo/abstract-eth` messages
+  (`modules/abstract-eth/src/lib/messages/eip712/`)
+  - `Erc20VotesDelegationMessage` / `Erc20VotesDelegationMessageBuilder`
+  - `MessageBuilderFactory.getErc20VotesDelegationBuilder()`
+- `@bitgo/sdk-core`
+  - `IntentOptionsForTypedData.messageStandardType`
+  - `Wallet.signTypedData` sets `MessageStandardType.EIP712` so WP routes
+    the message to TAT.

examples/ts/eth/fetch-erc20-votes-delegation-txrequest-signature.ts

@@ -0,0 +1,235 @@
+/* eslint-disable no-console */
+/**
+ * Fetch a custodial TSS typed-data (EIP-712) tx request and print the ECDSA signature
+ * as v, r, s for use with ERC20Votes-style `delegateBySig`.
+ *
+ * Step 2 of the two-step ERC20Votes / WLFI cold-custody delegation flow described in
+ * `examples/docs/erc20-votes-delegate-by-sig.md` (CGD-842). Step 1 is
+ * `examples/ts/eth/push-erc20-votes-delegation-txrequest.ts`, which creates the tx
+ * request and prints its `txRequestId`.
+ *
+ * API: GET /api/v2/wallet/{walletId}/txrequests?txRequestIds={id}&latest=true
+ * (same shape as {@link https://developers.bitgo.com/reference/v2wallettxrequestget v2.wallet.txrequest.get})
+ *
+ * After signing completes, BitGo stores the 65-byte secp256k1 signature on
+ * `messages[0].txHash` (see wallet `signTypedDataTss`).
+ *
+ * The list endpoint can return **multiple rows** for the same `txRequestId`
+ * (versioned snapshots: MPC rounds, then `signed`). This script picks the
+ * snapshot whose `messages[0].state === "signed"` (and whose `txHash` is a
+ * complete 65-byte ECDSA hex). If no signed snapshot exists yet, it prints
+ * "Message not signed yet, try again later." — re-run after TAT signs.
+ *
+ * Configuration is read from `.env` via dotenv. The file is resolved as:
+ * `{current working directory}/.env` if it exists, otherwise the monorepo
+ * root `.env` next to this script (`examples/ts/eth` → three levels up).
+ *
+ * Environment (same names as the companion push script):
+ * - `BITGO_ACCESS_TOKEN` (or `ACCESS_TOKEN`)
+ * - `WALLET_ID`
+ * - `TX_REQUEST_ID` — id printed by the push script
+ * - `COIN` — must match the wallet's chain (e.g. `eth`, `teth`, `hteth`)
+ * - `BITGO_ENV` — `test` (default) or `prod`
+ *
+ * Copyright 2026, BitGo, Inc.  All Rights Reserved.
+ */
+import fs from 'fs';
+import path from 'path';
+
+import dotenv from 'dotenv';
+import { BitGoAPI } from '@bitgo/sdk-api';
+import { EnvironmentName } from '@bitgo/sdk-core';
+import { Eth, Hteth, Teth } from '@bitgo/sdk-coin-eth';
+import { ethers } from 'ethers';
+
+async function loadEnv(): Promise<void> {
+  const candidates = [path.join(process.cwd(), '.env'), path.join(__dirname, '../../../.env')];
+  for (const envPath of candidates) {
+    try {
+      await fs.promises.access(envPath, fs.constants.F_OK);
+      dotenv.config({ path: envPath });
+      return;
+    } catch {
+      // try next candidate
+    }
+  }
+  dotenv.config();
+}
+
+type TxRequestMessage = {
+  state?: string;
+  messageRaw?: string;
+  txHash?: string;
+};
+
+type TxRequestBody = {
+  txRequestId?: string;
+  state?: string;
+  /** Monotonic snapshot id when BitGo returns several rows for one logical tx request */
+  version?: number;
+  /** True on the row you should treat as current (e.g. delivered + signed txHash) */
+  latest?: boolean;
+  messages?: TxRequestMessage[];
+};
+
+/** BitGo stores a 65-byte secp256k1 ECDSA signature as hex (130 digits, optional 0x). */
+function isCompleteSignatureHex(txHash: string | undefined): boolean {
+  if (!txHash?.trim()) {
+    return false;
+  }
+  const hex = txHash.trim().startsWith('0x') ? txHash.trim().slice(2) : txHash.trim();
+  if (!/^[0-9a-fA-F]+$/i.test(hex)) {
+    return false;
+  }
+  return hex.length === 130;
+}
+
+function isSignedMessageSnapshot(t: TxRequestBody): boolean {
+  const m = t.messages?.[0];
+  return m?.state === 'signed' && isCompleteSignatureHex(m.txHash);
+}
+
+function maxByVersion(txRequests: TxRequestBody[]): TxRequestBody {
+  return txRequests.reduce((best, cur) => ((cur.version ?? -1) >= (best.version ?? -1) ? cur : best));
+}
+
+function pickSignedSnapshot(txRequests: TxRequestBody[]): TxRequestBody | undefined {
+  const signedSnapshots = txRequests.filter(isSignedMessageSnapshot);
+  if (signedSnapshots.length === 0) {
+    return undefined;
+  }
+  return maxByVersion(signedSnapshots);
+}
+
+function registerEthCoins(bitgo: BitGoAPI): void {
+  bitgo.register('eth', Eth.createInstance);
+  bitgo.register('teth', Teth.createInstance);
+  bitgo.register('hteth', Hteth.createInstance);
+}
+
+function encodeDelegateBySigCalldata(params: {
+  delegatee: string;
+  nonce: string;
+  expiry: string;
+  v: number;
+  r: string;
+  s: string;
+}): string {
+  const delegateBySigAbi = [
+    'function delegateBySig(address delegatee, uint256 nonce, uint256 expiry, uint8 v, bytes32 r, bytes32 s)',
+  ];
+  const iface = new ethers.utils.Interface(delegateBySigAbi);
+  return iface.encodeFunctionData('delegateBySig', [
+    ethers.utils.getAddress(params.delegatee),
+    ethers.BigNumber.from(params.nonce),
+    ethers.BigNumber.from(params.expiry),
+    params.v,
+    params.r,
+    params.s,
+  ]);
+}
+
+function tryParseDelegationFields(messageRaw: string):
+  | {
+      delegatee: string;
+      nonce: string;
+      expiry: string;
+    }
+  | undefined {
+  try {
+    const parsed = JSON.parse(messageRaw) as { message?: Record<string, unknown> };
+    const msg = parsed.message;
+    if (!msg || typeof msg !== 'object') {
+      return undefined;
+    }
+    const { delegatee, nonce, expiry } = msg;
+    if (typeof delegatee !== 'string' || typeof nonce === 'undefined' || typeof expiry === 'undefined') {
+      return undefined;
+    }
+    return { delegatee, nonce: String(nonce), expiry: String(expiry) };
+  } catch {
+    return undefined;
+  }
+}
+
+async function fetchTxRequests(bitgo: BitGoAPI, walletId: string, txRequestId: string): Promise<TxRequestBody[]> {
+  const res = (await bitgo
+    .get(bitgo.url('/wallet/' + walletId + '/txrequests', 2))
+    .query({ txRequestIds: txRequestId, latest: 'true' })
+    .result()) as { txRequests: TxRequestBody[] };
+
+  if (!res.txRequests?.length) {
+    throw new Error(`No tx request found for id ${txRequestId}`);
+  }
+  return res.txRequests;
+}
+
+async function main(): Promise<void> {
+  await loadEnv();
+
+  const accessToken = process.env.BITGO_ACCESS_TOKEN ?? process.env.ACCESS_TOKEN;
+  const walletId = process.env.WALLET_ID;
+  const txRequestId = process.env.TX_REQUEST_ID;
+  const coin = process.env.COIN;
+  const env: EnvironmentName = process.env.BITGO_ENV === 'prod' ? 'prod' : 'test';
+
+  if (!accessToken) {
+    throw new Error('Set BITGO_ACCESS_TOKEN (or ACCESS_TOKEN)');
+  }
+  if (!walletId) {
+    throw new Error('Set WALLET_ID');
+  }
+  if (!coin) {
+    throw new Error('Set COIN to the wallet chain (e.g. eth, teth, hteth)');
+  }
+  if (!txRequestId) {
+    throw new Error('Set TX_REQUEST_ID — use the tx request id printed by the push script');
+  }
+
+  const bitgo = new BitGoAPI({ accessToken, env });
+  registerEthCoins(bitgo);
+  bitgo.coin(coin);
+
+  const txRequests = await fetchTxRequests(bitgo, walletId, txRequestId);
+  const signed = pickSignedSnapshot(txRequests);
+
+  if (!signed) {
+    console.log('Message not signed yet, try again later.');
+    return;
+  }
+
+  const msg0 = signed.messages?.[0];
+  const txHash = msg0?.txHash;
+  if (!msg0 || !txHash) {
+    console.log('Message not signed yet, try again later.');
+    return;
+  }
+  const sigHex = txHash.startsWith('0x') ? txHash : `0x${txHash}`;
+  const { v, r, s } = ethers.utils.splitSignature(sigHex);
+
+  console.log('txRequestId:', signed.txRequestId ?? txRequestId);
+  console.log('snapshot version:', signed.version ?? 'n/a');
+  console.log('messages[0].state:', msg0.state);
+  console.log('\nECDSA signature (from messages[0].txHash):');
+  console.log('v:', v);
+  console.log('r:', r);
+  console.log('s:', s);
+
+  if (msg0.messageRaw) {
+    const fields = tryParseDelegationFields(msg0.messageRaw);
+    if (fields) {
+      try {
+        const calldata = encodeDelegateBySigCalldata({ ...fields, v, r, s });
+        console.log('\ndelegateBySig calldata:');
+        console.log(calldata);
+      } catch (e) {
+        console.warn('Could not build delegateBySig calldata:', (e as Error).message);
+      }
+    }
+  }
+}
+
+main().catch((e) => {
+  console.error(e);
+  process.exitCode = 1;
+});