Skip to content
You are reading EthSigner development version documentation and some displayed features may not be available in the stable release. You can switch to stable version using the version box at screen bottom.

Start EthSigner with a single signer

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

Tip

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

Prerequisites

Note

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:

Example

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

Important

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).

Example

1
2
3
4
5
6
7
8
const Web3 = require('web3')

// Web3 initialization (should point to the JSON-RPC endpoint)
const web3 = new Web3(new Web3.providers.HttpProvider('http://127.0.0.1:8590'))

var V3KeyStore = web3.eth.accounts.encrypt("<AccountPrivateKey>", "<Password>");
console.log(JSON.stringify(V3KeyStore));
process.exit();
1
2
3
4
5
6
7
8
const Web3 = require('web3')

// Web3 initialization (should point to the JSON-RPC endpoint)
const web3 = new Web3(new Web3.providers.HttpProvider('http://127.0.0.1:8590'))

var V3KeyStore = web3.eth.accounts.encrypt("0x8f2a55949038a9610f50fb23b5883af3b4ecb3c3bb792cbcefbd1542c692be63", "password");
console.log(JSON.stringify(V3KeyStore));
process.exit();

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.

Example

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.

Example

ethsigner --chain-id=5 --downstream-http-host=goerli.infura.io \
--downstream-http-path=/v3/d0e63ca5bb1e4eef2284422efbc51a56 --downstream-http-port=443 \
--downstream-http-tls-enabled file-based-signer --key-file=/mydirectory/keyFile \
--password-file=/mydirectory/passwordFile

Confirm EthSigner is up

Use the upcheck endpoint to confirm EthSigner is running.

Example

curl -X GET http://127.0.0.1:8545/upcheck
I'm up

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}' http://127.0.0.1:8545

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

Questions or feedback? You can discuss issues and obtain free support on EthSigner Discord channel.
For paid professional support by Pegasys, contact us at support@pegasys.tech