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
• azure_key_vault: Azure Key Vault signer
• cdp: Coinbase Developer Platform signer

Network Compatibility Matrix

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

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.

{
  "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:

Azure Key Vault Signer Configuration

Uses Azure Key Vault for secure EVM signing operations with secp256k1 keys.

{
  "id": "azure-key-vault-signer",
  "type": "azure_key_vault",
  "config": {
    "auth_type": "client_secret",
    "tenant_id": {
      "type": "env",
      "value": "AZURE_TENANT_ID"
    },
    "client_id": {
      "type": "env",
      "value": "AZURE_CLIENT_ID"
    },
    "client_secret": {
      "type": "env",
      "value": "AZURE_CLIENT_SECRET"
    },
    "vault_url": "https://your-key-vault-name.vault.azure.net",
    "key_name": "your-secp256k1-key-name",
    "key_version": null
  }
}

Configuration fields:

Azure-specific requirements:

• The signer currently supports EVM networks only
• Use a secp256k1 key in Azure Key Vault
• Ensure the chosen identity can read key metadata and perform signing operations

CDP Signer Configuration

Uses CDP’s secure key management infrastructure.

{
  "id": "cdp-signer",
  "type": "cdp",
  "config": {
    "api_key_id": "your-cdp-api-key-id",
    "api_key_secret": {
      "type": "env",
      "value": "CDP_API_KEY_SECRET"
    },
    "wallet_secret": {
      "type": "env",
      "value": "CDP_WALLET_SECRET"
    },
    "account_address": "your-cdp-evm-or-solana-account-address"
  }
}

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

Azure Key Vault authentication failures

• Verify the configured auth_type matches your Azure deployment
• Check that tenant, client, secret, or workload identity values are present for the selected auth mode
• Ensure the chosen identity has permission to read key metadata and sign with the Azure Key Vault key
• Confirm the Key Vault URL, key name, and optional key version are correct

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.