Universal Signer

Universal Signer

Overview

@universal-signer/core provides a unified, type-safe interface for various signing providers, all compatible with Viem v2. It allows you to write blockchain logic once and switch between AWS KMS, Google Cloud KMS, Ledger, Trezor, Turnkey, and local keys through configuration.

Installation

npm install @universal-signer/core viem

Then install only the provider(s) you need:

Quick Start

import { createUniversalClient, createAwsAccount } from "@universal-signer/core";
import { mainnet } from "viem/chains";
import { http } from "viem";

// 1. Create an account
const account = await createAwsAccount({
  keyId: "alias/my-key",
  region: "us-east-1"
});

// 2. Create a Viem-compatible client
const client = createUniversalClient(account, mainnet, http());

// 3. Sign transactions or messages normally
const hash = await client.sendTransaction({
  to: "0x...",
  value: 1000000000000000n
});

Features & Configuration

For detailed setup and configuration for specific providers, see the following:

• [Provider Configurations](references/providers.md): Details for AWS, GCP, Hardware Wallets, and Turnkey.
• [Troubleshooting & Technical Details](references/troubleshooting.md): Common errors and signature normalization info.

Key Capabilities

• Unified API: All providers return a standard Viem LocalAccount.
• Full Support: signTransaction, signMessage, and signTypedData (EIP-712).
• KMS Normalization: Automatic EIP-2 signature normalization and v recovery.
• Hardware Ready: Built-in HID management for Ledger and Trezor.

Universal Signer Skills

This skill provides guidance and implementation patterns for using @universal-signer/core with Viem v2. It simplifies the integration of hardware wallets (Ledger, Trezor) and Cloud KMS providers (AWS, GCP) into Ethereum applications.

Features

• Unified Signer Interface: One API for Local, Hardware, and Cloud keys.
• Viem Native: Seamlessly integrates with WalletClient and LocalAccount.
• Advanced Signing: Handles KMS DER signature normalization and recovery automatically.
• Provider Support: AWS KMS, Google Cloud KMS, Ledger, Trezor, Turnkey, and Local.

Installation

To add this skill to your project, run:

npx skills add melonask/universal-signer-skills

Contents

• `SKILL.md`: Main guide with quick start and overview.
• `references/providers.md`: Detailed configuration for each signer type.
• `references/troubleshooting.md`: Solutions for common errors and technical details.

Usage

Trigger this skill by asking:

• "How do I use AWS KMS with Viem?"
• "Set up a Ledger signer for my wallet client."
• "What's the best way to handle GCP KMS signatures in Ethereum?"
• "Switch between local and hardware signing using universal-signer."

Universal Signer Providers

Details for configuring and using the various signing providers supported by @universal-signer/core.

1. AWS KMS

Signs with AWS Key Management Service using ECC_SECG_P256K1.

npm install @aws-sdk/client-kms

Prerequisites:

• Key Spec: ECC_SECG_P256K1
• IAM Permissions: kms:GetPublicKey, kms:Sign

import { createAwsAccount } from "@universal-signer/core";

const account = await createAwsAccount({
  keyId: "alias/my-eth-key", // ARN, ID, or Alias
  region: "us-east-1",
  // credentials: { accessKeyId: "...", secretAccessKey: "..." } // Optional
});

2. Google Cloud KMS

Signs with Google Cloud KMS using EC_SIGN_SECP256K1_SHA256.

npm install @google-cloud/kms

Prerequisites:

• Purpose: ASYMMETRIC_SIGN
• IAM Role: roles/cloudkms.signerVerifier

import { createGcpAccount } from "@universal-signer/core";

const account = await createGcpAccount({
  name: "projects/my-project/locations/global/keyRings/my-ring/cryptoKeys/my-key/cryptoKeyVersions/1",
  clientOptions: { projectId: "my-project" } // Optional
});

3. Hardware Wallets (Ledger & Trezor)

Ledger

Uses USB HID. Ensure the Ethereum app is open and Blind Signing is enabled.

npm install @ledgerhq/hw-app-eth @ledgerhq/hw-transport-node-hid

import { createLedgerAccount } from "@universal-signer/core";

const account = await createLedgerAccount({
  derivationPath: "44'/60'/0'/0/0"
});
// Important: call account.close() when finished
await account.close();

Trezor

Requires a valid manifest (email, appUrl, appName).

npm install @trezor/connect

import { createTrezorAccount } from "@universal-signer/core";

const account = await createTrezorAccount({
  email: "dev@example.com",
  appUrl: "https://example.com",
  appName: "My App",
  derivationPath: "m/44'/60'/0'/0/0"
});

4. Turnkey

Cloud-based KMS with organizational isolation.

npm install @turnkey/viem @turnkey/http @turnkey/api-key-stamper

import { createTurnkeyAccount } from "@universal-signer/core";

const account = await createTurnkeyAccount({
  baseUrl: "https://api.turnkey.com",
  apiPublicKey: process.env.TURNKEY_PUBLIC_KEY!,
  apiPrivateKey: process.env.TURNKEY_PRIVATE_KEY!,
  organizationId: process.env.TURNKEY_ORG_ID!,
  privateKeyId: process.env.TURNKEY_PK_ID!
});

5. Local (Development)

Wraps Viem's native account logic. Warning: Not for production secrets.

import { createLocalAccount } from "@universal-signer/core";

const account = createLocalAccount({
  privateKey: "0x..." // or mnemonic: "..."
});

Troubleshooting Universal Signer

Solutions for common issues across different signing providers.

KMS Issues (AWS/GCP)

"Invalid DER: Unexpected end of data"

KMS returned a truncated or malformed signature.

• Solution: Check network stability and retry. Verify key configuration is SECP256K1.

Permission Errors

• AWS: Ensure kms:GetPublicKey and kms:Sign are granted.
• GCP: Ensure roles/cloudkms.signerVerifier is granted to the service account.

Hardware Wallets

Ledger Connection Failures

• Causes: Ledger Live is open, another browser tab has the device, or udev rules (Linux).
• Solution: Close other apps. On Linux, ensure udev rules allow USB access.

Trezor "Manifest not set"

• Solution: Ensure email, appUrl, and appName are all provided in the config.

Trezor "chainId is required"

Trezor is strict about EIP-155.

• Solution: Pass chainId explicitly in the sendTransaction or signTransaction call.

Technical Details: Normalization

KMS providers return ASN.1 DER signatures. @universal-signer/core automatically: 1. Parses DER to extract r and s. 2. Normalizes s (EIP-2) to prevent malleability. 3. Recovers v by trial recovery against the known public key.