Skip to main content

Start EthSigner with a single signer

For file-based signing, EthSigner requires a V3 keystore key file and a password file.


EthSigner also supports signing transactions with a key stored in an external vault (for example, HashiCorp Vault), or using multiple V3 keystore key files.



The Ethereum client used in this documentation is Hyperledger Besu but EthSigner can be used with any Ethereum client.

Start Besu

Start Besu, setting the:

besu --network=dev --miner-enabled --miner-coinbase=0xfe3b557e8fb62b89f4916b721be55ceb828dbd73 --rpc-http-cors-origins="all" --host-allowlist="*" --rpc-http-enabled --rpc-http-port=8590 --data-path=/Users/<>/Datadir

EthSigner requires a chain ID to be used when signing transactions. The downstream Ethereum client must be operating in a milestone supporting replay protection. That is, the genesis file must include at least the Spurious Dragon milestone (defined as eip158Block in the genesis file) so the blockchain is using a chain ID.

Create password and key files

Create a text file containing the password for the V3 keystore key file to be created (for example, passwordFile).

Use the web3.js library to create a key file where:

  • <AccountPrivateKey> is the private key of the account with which EthSigner will sign transactions.

  • <Password> is the password for the key file being created. The password must match the password saved in the password file created previously (passwordFile in this example).

const Web3 = require("web3");

// Web3 initialization (should point to the JSON-RPC endpoint)
const web3 = new Web3(new Web3.providers.HttpProvider(""));

var V3KeyStore = web3.eth.accounts.encrypt("<AccountPrivateKey>", "<Password>");

Copy and paste the example JS script to a file (for example, createKeyFile.js) and replace the placeholders.

Use the JS script to display the text for the key file:

node createKeyFile.js

Copy and paste the text to a file (for example, keyFile). The file is your V3 keystore key file.

Start EthSigner

Start EthSigner with options specified as follows:

  • chain-id is the chain ID specified in the Besu genesis file.

  • downstream-http-port is the rpc-http-port specified for Besu (8590 in this example).

  • key-file and password-file are the key and password files created above.

Start EthSigner
ethsigner --chain-id=2018 --downstream-http-port=8590 file-based-signer --key-file=/mydirectory/keyFile --password-file=/mydirectory/passwordFile

If using a cloud-based Ethereum client such as Infura, specify the endpoint using the --downstream-http-host and --downstream-http-path command line options.

ethsigner --chain-id=5 \
--downstream-http-path=/v3/d0e63ca5bb1e4eef2284422efbc51a56 --downstream-http-port=443 \
--downstream-http-tls-enabled file-based-signer --key-file=/mydirectory/keyFile \

Confirm EthSigner is up

Use the upcheck endpoint to confirm EthSigner is running.

curl -X GET

Confirm EthSigner passing requests to Besu

Request the current block number using eth_blockNumber with the EthSigner JSON-RPC endpoint (8545 in this example):

curl -X POST --data '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":51}'

You can now use EthSigner to sign transactions with the key stored in the V3 keystore key file.