🔐 web3-google-hsm

Feature	Value
Technology
Type Checking
CI/CD
Docs
Package
Meta

🎯 Description

A Python library for using Google Cloud HSM services to sign Ethereum transactions.

✨ Features

• 🔒 Cloud HSM integration for secure key management
• 🌐 Support for web3-google-hsm (extensible to other providers)
• 🛡️ Type-safe configuration using Pydantic

📦 Installation

• Install using pip

pip install web3-google-hsm

🛠️ Environment Setup

🔑 Google Cloud HSM Key

Make sure you have created a key of type ec-sign-secp256k1-sha256 in the Google cloud console. Which will look something like the following

🌟 Required Environment Variables

Before using this library, you need to set up the following environment variables:

GOOGLE_CLOUD_PROJECT=your-project-id
GOOGLE_CLOUD_REGION=us-east1
KEY_RING=eth-keyring
KEY_NAME=eth-key
GOOGLE_APPLICATION_CREDENTIALS=path/to/your/service-account.json

💻 Bash

# Add to ~/.bashrc or ~/.bash_profile
export GOOGLE_CLOUD_PROJECT="your-project-id"
export GOOGLE_CLOUD_REGION="us-east1"
export KEY_RING="eth-keyring"
export KEY_NAME="eth-key"
export GOOGLE_APPLICATION_CREDENTIALS="path/to/your/service-account.json"

# Apply changes
source ~/.bashrc  # or source ~/.bash_profile

🐚 Zsh

# Add to ~/.zshrc
export GOOGLE_CLOUD_PROJECT="your-project-id"
export GOOGLE_CLOUD_REGION="us-east1"
export KEY_RING="eth-keyring"
export KEY_NAME="eth-key"
export GOOGLE_APPLICATION_CREDENTIALS="path/to/your/service-account.json"

# Apply changes
source ~/.zshrc

🐟 Fish

# Add to ~/.config/fish/config.fish
set -x GOOGLE_CLOUD_PROJECT "your-project-id"
set -x GOOGLE_CLOUD_REGION "us-east1"
set -x KEY_RING "eth-keyring"
set -x KEY_NAME "eth-key"
set -x GOOGLE_APPLICATION_CREDENTIALS "path/to/your/service-account.json"
set -x INFURA_KEY "your-infura-key"
set -x WEB3_PROVIDER_URI "https://mainnet.infura.io/v3/$INFURA_KEY"

# Apply changes
source ~/.config/fish/config.fish

📄 Using .env File

You can also create a .env file in your project root:

# .env
GOOGLE_CLOUD_PROJECT=your-project-id
GOOGLE_CLOUD_REGION=us-east1
KEY_RING=eth-keyring
KEY_NAME=eth-key
GOOGLE_APPLICATION_CREDENTIALS=path/to/your/service-account.json

Then load it in your Python code:

from dotenv import load_dotenv
load_dotenv()

📋 Prerequisites

Before you begin, ensure you have:

1. 🔧 Set up your environment variables (see README.md)
2. 🐍 Python 3.10 or higher installed
3. 🌐 Access to a Web3 provider (local or remote) (Optional)

📝 Environment Variable Descriptions

• 🌐 GOOGLE_CLOUD_PROJECT: Your Google Cloud project ID
• 📍 GOOGLE_CLOUD_REGION: The region where your KMS resources are located (e.g., us-east1, europe-west1)
• 🔑 KEY_RING: The name of your KMS key ring
• 🗝️ KEY_NAME: The name of your KMS key
• 📜 GOOGLE_APPLICATION_CREDENTIALS: Path to your Google Cloud service account JSON key file

✅ Verifying Setup

You can verify your environment setup with:

from web3_google_hsm.config import BaseConfig

try:
    config = BaseConfig()
    print("Environment configured successfully!")
    print(f"Project ID: {config.project_id}")
    print(f"Region: {config.location_id}")
except ValueError as e:
    print(f"Configuration error: {e}")

📚 Usage Guide

📚 As A CLI Tool

🔑 Key Generation

Generate a new Ethereum signing key in Google Cloud HSM:

# Specify explicitly
web3-google-hsm generate \
  --project-id my-project \
  --location us-east1 \
  --keyring eth-keyring \
  --key-id eth-key-1 \
  --retention-days 365

web3-google-hsm generate --project-id hsm-testing-445507 --location nam10 --keyring eth-keyring --key-id cli_key

Options:

• --project-id: Google Cloud project ID (env: GOOGLE_CLOUD_PROJECT)
• --location: Cloud KMS location (env: GOOGLE_CLOUD_REGION)
• --keyring: Name of the key ring (env: KEY_RING)
• --key-id: ID for the new key (env: KEY_NAME)
• --retention-days: Days to retain key versions (default: 365)

Example output:

✅ Created Ethereum signing key: projects/my-project/locations/us-east1/keyRings/eth-keyring/cryptoKeys/eth-key-1
🔑 Ethereum address: 0x742d35Cc6634C0532925a3b844Bc454e4438f44e

📝 Message Signing

Sign a message using your HSM key:

# Sign a simple message
web3-google-hsm sign "Hello Ethereum!" --account 0x742d35Cc6634C0532925a3b844Bc454e4438f44e

# Sign a hex message
web3-google-hsm sign "0x4d7920686578206d657373616765" --account 0x742d35Cc6634C0532925a3b844Bc454e4438f44e

Arguments:

• message: The message to sign (text or hex)
• --account, -a: Ethereum address of the signing account

Example output:

✅ Message signed successfully!
📝 Message: Hello Ethereum!
🔏 Signature: 0x4d7920686578206d657373616765000000000000000000000000000000000000
📊 Components:
  v: 27
  r: 0x1b7e9c7c039d8f4688a743b0c5c0e509209e6f200d956bf7f4e89f5ad330c135
  s: 0x0d27e9c7c039d8f4688a743b0c5c0e509209e6f200d956bf7f4e89f5ad330c13

This guide demonstrates how to use the Google Cloud KMS Ethereum signer library for message and transaction signing.

🚀 Basic Setup

from web3_google_hsm.accounts.gcp_kms_account import GCPKmsAccount

account = GCPKmsAccount()

# Get the Ethereum address derived from your GCP KMS key
print(f"GCP KMS Account address: {account.address}")

📝 Message Signing

✍️ Simple Message Signing

# Sign a message
message = "Hello Ethereum!"
signed_message = account.sign_message(message)

# Access signature components
print(f"R: {signed_message.r.hex()}")
print(f"S: {signed_message.s.hex()}")
print(f"V: {signed_message.v}")
print(f"Full signature: {signed_message.to_hex()}")

✔️ Message Signature Verification

from eth_account.messages import encode_defunct
from web3 import Web3
# Create message hash
message_hash = encode_defunct(text=message)

# Initialize Web3 and GCP KMS account
w3 = Web3(Web3.HTTPProvider("http://localhost:8545"))

# Verify the signature using web3.py
recovered_address = w3.eth.account.recover_message(
    message_hash,
    vrs=(signed_message.v, signed_message.r, signed_message.s)
)

# Check if signature is valid
is_valid = recovered_address.lower() == account.address.lower()
print(f"Signature valid: {is_valid}")

💳 Transaction Signing

📤 Creating a Transaction

tx = {
    "from": account.address,
    "chain_id": w3.eth.chain_id,
    "nonce": w3.eth.get_transaction_count(account.address),
    "value": w3.to_wei(0.000001, "ether"),
    "data": "0x00",
    "to": "0xa5D3241A1591061F2a4bB69CA0215F66520E67cf",
    "type": 0,
    "gas_limit": 1000000,
    "gas_price": 300000000000,
}

# Convert dict to Transaction object and sign
signed_tx = account.sign_transaction(Transaction.from_dict(tx))

📡 Sending a Transaction

if signed_tx:
    # Send the transaction
    tx_hash = w3.eth.send_raw_transaction(signed_tx)

    # Wait for transaction receipt
    receipt = w3.eth.wait_for_transaction_receipt(tx_hash)

    print(f"Transaction hash: {receipt['transactionHash'].hex()}")
    print(f"From: {receipt['from']}")
    print(f"To: {receipt['to']}")
    print(f"Gas used: {receipt['gasUsed']}")

🔍 Transaction Signature Verification

# Verify the transaction signature
recovered_address = w3.eth.account.recover_transaction(signed_tx)
is_valid = recovered_address.lower() == account.address.lower()
print(f"Signature valid: {is_valid}")

🏗️ Working with Local Test Networks

Funding Your Account (for testing with Anvil/Hardhat)

# Use a test account (Anvil's default funded account)
funded_account = w3.eth.account.from_key(
    "0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80"
)

# Create funding transaction
fund_tx = {
    "from": funded_account.address,
    "to": account.address,
    "value": w3.to_wei(0.1, "ether"),
    "gas": 21000,
    "gasPrice": w3.eth.gas_price,
    "nonce": w3.eth.get_transaction_count(funded_account.address),
    "chainId": w3.eth.chain_id,
}

# Send funding transaction
signed_fund_tx = w3.eth.account.sign_transaction(fund_tx, funded_account.key)
fund_tx_hash = w3.eth.send_raw_transaction(signed_fund_tx.raw_transaction)
fund_receipt = w3.eth.wait_for_transaction_receipt(fund_tx_hash)

🌐 Using with Different Networks

🏠 Local Network (Anvil/Hardhat)

w3 = Web3(Web3.HTTPProvider("http://localhost:8545"))

🌍 Mainnet (via Infura)

w3 = Web3(Web3.HTTPProvider(f"https://mainnet.infura.io/v3/{INFURA_KEY}"))

🧪 Testnet (sepolia)

w3 = Web3(Web3.HTTPProvider(f"https://sepolia.infura.io/v3/{INFURA_KEY}"))

⚠️ Error Handling

from web3_google_hsm.types.ethereum_types import Transaction

try:
    signed_message = account.sign_message("Hello")
except Exception as e:
    print(f"Signing error: {e}")

try:
    signed_tx = account.sign_transaction(Transaction.from_dict(tx))
    if not signed_tx:
        print("Failed to sign transaction")
except Exception as e:
    print(f"Transaction error: {e}")

🚀 CI/CD Pipeline Integration

🔄 Using in GitHub Actions or Other CI/CD Pipelines

For CI/CD environments where you can't use traditional environment variables or service account files, you can pass the credentials directly as a JSON string:

from web3_google_hsm.accounts.gcp_kms_account import GCPKmsAccount
from web3_google_hsm.config import BaseConfig
import json

# Create config from environment variables
config = BaseConfig(
    project_id="your-project-id",
    location_id="your-location",
    key_ring_id="your-keyring",
    key_id="your-key-id"
)

# Load credentials from CI/CD secret
credentials = json.loads(os.environ["GCP_ADC_CREDENTIALS_STRING"])

# Initialize account with both config and credentials
account = GCPKmsAccount(config=config, credentials=credentials)

# or Let the class read the values from env variables
account = GCPKmsAccount(credentials=credentials)

🔒 GitHub Actions Example

name: Deploy with HSM Signing

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2

      - name: Set up Python
        uses: actions/setup-python@v2
        with:
          python-version: '3.10'

      - name: Install dependencies
        run: pip install web3-google-hsm

      - name: Sign and Deploy
        env:
          GOOGLE_CLOUD_PROJECT: ${{ secrets.GCP_PROJECT_ID }}
          GOOGLE_CLOUD_REGION: ${{ secrets.GCP_REGION }}
          KEY_RING: ${{ secrets.GCP_KEYRING }}
          KEY_NAME: ${{ secrets.GCP_KEY_NAME }}
          GCP_ADC_CREDENTIALS_STRING: ${{ secrets.GCP_ADC_CREDENTIALS_STRING }}
        run: |
          python your_deployment_script.py

📝 Example Deployment Script

import os
import json
from web3_google_hsm.accounts.gcp_kms_account import GCPKmsAccount
from web3_google_hsm.config import BaseConfig
from web3_google_hsm.types.ethereum_types import Transaction

def deploy_contract():
    # Initialize with both config and credentials
    config = BaseConfig.from_env()  # Uses environment variables
    credentials = json.loads(os.environ["GCP_ADC_CREDENTIALS_STRING"])

    account = GCPKmsAccount(config=config, credentials=credentials)

    # Your deployment logic here
    print(f"Deploying from address: {account.address}")

    # Example transaction
    tx = Transaction(
        nonce=0,
        gas_price=2000000000,
        gas_limit=1000000,
        to="0x...",
        value=0,
        data="0x...",
        chain_id=1
    )

    signed_tx = account.sign_transaction(tx)
    # Send transaction...

if __name__ == "__main__":
    deploy_contract()

🔑 Required Secrets for CI/CD

Set these secrets in your CI/CD environment:

• GCP_PROJECT_ID: Your Google Cloud project ID
• GCP_REGION: The region where your KMS resources are located
• GCP_KEYRING: The name of your KMS key ring
• GCP_KEY_NAME: The name of your KMS key
• GCP_ADC_CREDENTIALS_STRING: Your service account credentials JSON as a string

For more information see the following links.

📚 Documentation: https://ankvik-tech-labs.github.io/web3-google-hsm/

💻 Source Code: https://github.com/Ankvik-Tech-Labs/web3-google-hsm

hatch run test

hatch run lint

hatch version patch

hatch version minor

hatch version major

hatch run docs-serve

📖 Further Reading

• Google Cloud KMS Documentation
• Ethereum Key Management Best Practices
• Web3.py Documentation

📜 License

This project is licensed under the terms of the BSD license.