Signers Configuration

Overview

Signers are responsible for cryptographically signing transactions before they are submitted to blockchain networks. OpenZeppelin Relayer supports multiple signer types to accommodate different security requirements and infrastructure setups.

Each signer is referenced by its id in relayer configurations.

Configuration Structure

Example signer configuration:

"signers": [

    "id": "my_id",
    "type": "local",
    "config": {
      "path": "config/keys/local-signer.json",
      "passphrase": {
        "type": "env",
        "value": "KEYSTORE_PASSPHRASE"

    }
  }
]

Supported Signer Types

OpenZeppelin Relayer supports the following signer types:

• local: Keystore file signer
• vault: HashiCorp Vault secret signer
• vault_transit: HashiCorp Vault Transit signer
• turnkey: Turnkey signer
• google_cloud_kms: Google Cloud KMS signer
• aws_kms: Amazon AWS KMS signer

Network Compatibility Matrix

The following table shows which signer types are compatible with each network type:

Network-specific considerations:

• EVM Networks: Use secp256k1 cryptography. Most signers support EVM networks with proper key generation.
• Solana Networks: Use ed25519 cryptography. Ensure your signer supports ed25519 key generation and signing.
• Stellar Networks: Use ed25519 cryptography with specific Stellar requirements. Limited signer support due to network-specific implementation requirements.
• AWS KMS: Currently optimized for EVM networks with secp256k1 support.
• Google Cloud KMS: Supports both secp256k1 (EVM) and ed25519 (Solana) key types.
• Turnkey: Supports EVM and Solana networks with appropriate key management.

Common Configuration Fields

All signer types share these common configuration fields:

Local Signer Configuration

The local signer uses encrypted keystore files stored on the filesystem.

  "id": "local-signer",
  "type": "local",
  "config": {
    "path": "config/keys/local-signer.json",
    "passphrase": {
      "type": "env",
      "value": "KEYSTORE_PASSPHRASE"
    
  }
}

Configuration fields:

HashiCorp Vault Signer Configuration

Vault Secret Signer

Uses HashiCorp Vault’s secret engine to store private keys.

  "id": "vault-signer",
  "type": "vault",
  "config": {
    "address": "https://vault.example.com",
    "role_id": {
      "type": "env",
      "value": "VAULT_ROLE_ID"
    ,
    "secret_id": 
      "type": "env",
      "value": "VAULT_SECRET_ID"
    ,
    "key_name": "relayer-key",
    "mount_point": "secret"
  }
}

Configuration fields:

Vault Transit Signer

Uses HashiCorp Vault’s Transit secrets engine for cryptographic operations.

  "id": "vault-transit-signer",
  "type": "vault_transit",
  "config": {
    "address": "https://vault.example.com",
    "role_id": {
      "type": "env",
      "value": "VAULT_ROLE_ID"
    ,
    "secret_id": 
      "type": "env",
      "value": "VAULT_SECRET_ID"
    ,
    "key_name": "relayer-transit-key",
    "mount_point": "transit",
    "namespace": "production",
    "pubkey": "your-public-key-here"
  }
}

Configuration fields:

Turnkey Signer Configuration

Uses Turnkey’s secure key management infrastructure.

  "id": "turnkey-signer",
  "type": "turnkey",
  "config": {
    "api_public_key": "your-api-public-key",
    "api_private_key": {
      "type": "env",
      "value": "TURNKEY_API_PRIVATE_KEY"
    ,
    "organization_id": "your-org-id",
    "private_key_id": "your-private-key-id",
    "public_key": "your-public-key"
  }
}

Configuration fields:

Google Cloud KMS Signer Configuration

Uses Google Cloud Key Management Service for secure key operations.

For EVM transaction signing, ensure your Google Cloud KMS key is created with:

• Protection level: HSM
• Purpose: Asymmetric sign
• Algorithm: "Elliptic Curve secp256k1 - SHA256 Digest"

This provides secp256k1 compatibility required for Ethereum transactions.

  "id": "gcp-kms-signer",
  "type": "google_cloud_kms",
  "config": {
    "service_account": {
      "project_id": "your-gcp-project",
      "private_key_id": {
        "type": "env",
        "value": "GCP_PRIVATE_KEY_ID"
      ,
      "private_key": 
        "type": "env",
        "value": "GCP_PRIVATE_KEY"
      ,
      "client_email": 
        "type": "env",
        "value": "GCP_CLIENT_EMAIL"
      ,
      "client_id": "your-client-id"
    },
    "key": 
      "location": "us-west2",
      "key_ring_id": "relayer-keyring",
      "key_id": "relayer-key",
      "key_version": 1
    
  }
}

Configuration fields:

AWS KMS Signer Configuration

Uses Amazon Web Services Key Management Service for cryptographic operations.

  "id": "aws-kms-signer",
  "type": "aws_kms",
  "config": {
    "region": "us-west-2",
    "key_id": "arn:aws:kms:us-west-2:123456789012:key/12345678-1234-1234-1234-123456789012"
  
}

Configuration fields:

Security Best Practices

File Permissions

• Set restrictive permissions on keystore files: chmod 0500 config/keys/*
• Ensure configuration directories are properly secured
• Use environment variables for sensitive data like passphrases and API keys

Key Management

• Use HSM-backed keys for production environments when available
• Implement proper key rotation policies
• Never commit private keys or sensitive configuration to version control
• Use dedicated service accounts with minimal required permissions

Environment Separation

• Use different signers for different environments (development, staging, production)
• Implement proper secrets management in production deployments
• Consider using cloud-native key management services for enhanced security

Troubleshooting

Common Issues

Invalid keystore passphrase

• Verify the passphrase environment variable is correctly set
• Check that the keystore file is not corrupted
• Ensure the keystore format is compatible

Cloud KMS authentication failures

• Verify service account credentials are valid and properly formatted
• Check that the service account has necessary permissions for KMS operations
• Ensure the KMS key exists and is in the correct region/project

Vault connection issues

• Verify Vault server address and network connectivity
• Check AppRole credentials and permissions
• Ensure the secret/transit engine is properly mounted and configured

For additional troubleshooting help, check the application logs and refer to the specific cloud provider or service documentation.