Transaction Signing

In conjunction with an ethereum provider, an transaction signer operates independently of the provider/broadcaster. This separation allows pre-signed transactions to be sent to an external (possibly remote) ethereum node and is particularly desirable when interacting with an untrusted ethereum node.

For example, external signers can be used with:

  • Infura/Alchemy/Etc.

  • Local ethereum node

  • Remote ethereum node

The following signers are currently supported:

  1. Hardware Wallet (recommended for Stakers)

  2. Local Keystore (recommended for Workers)

  3. Clef

Signing with Hardware Wallet

A hardware wallet stores private keys on a physical device. Storing private keys offline keeps them out of reach of attackers and therefore provides a high level of security.

Note

Currently, nucypher only provides native support for Trezor. Work is underway to natively support other hardware wallets such as Ledger. In the meantime, other hardware wallets can be used in conjunction with Clef.

Trezor

A Trezor signer can be specified either through the CLI (--signer) or API (nucypher.blockchain.eth.signers.Signer.from_signer_uri), using the URI trezor.

Signing with Local Keystore

Important

For operational security, the Keystore signer is not recommended for Staker operations. An exception can be made for testnets, but Staker operations should be performed using a hardware wallet.

Local keystore signing utilizes eth-account to sign ethereum transactions using local ethereum keystore files. By default on Linux, the keystore directory path is ~/.ethereum/keystore (on MacOS for Rinkeby testnet, /Users/<username>/Library/Ethereum/rinkeby/keystore).

Usage

Specify the local keystore signer either through the CLI (--signer) or API (nucypher.blockchain.eth.signers.Signer.from_signer_uri), using the URI keystore://<PATH TO LOCAL KEYSTORE>.

The path provided can either be a directory of keystore files or an individual keystore file. In the case of a directory, it is scanned and each of the keystore files contained are processed.

Signing with Clef

Clef enables applications to connect to an ethereum node and send locally signed transactions to be broadcasted. More information about Clef can be found here. Clef can use hardware wallets (Ledger and Trezor) over USB, or geth formatted private keys by specifying the keystore directory path.

Clef Setup

Clef is typically installed alongside geth.

Important

Geth version 1.9.22 or higher is required.

If you already have geth installed on your system you may already have Clef installed. To check for an existing installation run:

$ clef --version
Clef version 0.0.0

If clef was not found, upgrade geth to the latest version and try again.

Next, initialize Clef with your chosen password to encrypt the master seed:

$ clef init
...
The master seed of clef will be locked with a password.
Please specify a password. Do not forget this password!
Password:

Running Clef

$ clef --keystore <PATH TO KEYSTORE> --chainid <CHAIN ID> --advanced
  • <PATH TO KEYSTORE> - The path to the directory containing geth-formatted private key files; the default path for Linux is ~/.ethereum/keystore. No need to specify if using a hardware wallet.

  • <CHAIN ID> - 1 is specified to ensure Clef signs transactions with the network ID of ethereum mainnet (4 for the ibex testnet on rinkeby).

 Enter 'ok' to proceed:
 > ok
...

 ------- Signer info -------
 * extapi_version : 6.0.0
 * extapi_http : n/a
 * extapi_ipc : <CLEF IPC PATH>
 * intapi_version : 7.0.0

where <CLEF IPC PATH>:

  • Linux: /home/<username>/.clef/clef.ipc

  • MacOS: /Users/<username>/Library/Signer/clef.ipc

Clef Rules

By default, all requests to the Clef signer require manual confirmation. To overcome this, Clef allows the configuration of rules to automate the confirmation of requests to the signer. In particular, we recommend that users of a Clef signer with nucypher define the following rules file (rules.js), which simply approves the listing of accounts:

function ApproveListing() {
    return "Approve"
}

The sha256 digest of this particular 3-line file is 8d089001fbb55eb8d9661b04be36ce3285ffa940e5cdf248d0071620cf02ebcd. We will use this digest to attest that we trust these rules:

$ clef attest 8d089001fbb55eb8d9661b04be36ce3285ffa940e5cdf248d0071620cf02ebcd

WARNING!

Clef is an account management tool. It may, like any software, contain bugs.

Please take care to
- backup your keystore files,
- verify that the keystore(s) can be opened with your password.

Clef is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
PURPOSE. See the GNU General Public License for more details.

Enter 'ok' to proceed:
> ok

Decrypt master seed of clef
Password:
INFO [04-14|02:00:54.740] Ruleset attestation updated    sha256=8d089001fbb55eb8d9661b04be36ce3285ffa940e5cdf248d0071620cf02ebcd

Once the rules file is attested, we can run Clef with the --rules rules.js flag, to indicate which are the automated rules (in our case, allowing the listing of accounts):

$ clef --keystore <PATH TO KEYSTORE> --chainid <CHAIN ID> --advanced --rules rules.js

Usage

Once clef is running, specify the Clef signer either through the CLI (--signer) or API (nucypher.blockchain.eth.signers.Signer.from_signer_uri), using the URI clef://<CLEF IPC PATH>.