Using an Ethereum Node

For operations that require an ethereum provider for transaction signing and broadcasting, either a local or remote ethereum node may be used. For general background information about choosing a node technology and operation, see

Local Ethereum Node

This is the typical configuration for a locally operated trusted ethereum node. For detailed information on using the geth CLI and Javascript console, see

Assuming you have geth installed, to run a geth node in fast syncing mode:

$ geth

and to run a Geth node in light syncing mode:

$ geth --syncmode light


--syncmode light is not 100% stable.

If you want to use your hardware wallet, just connect it to your machine, and you’ll see something like this in logs:

INFO [08-30|15:50:39.153] New wallet appeared      url=ledger://0001:000b:00      status="Ethereum app v1.2.7 online"

If you see something like New wallet appeared, failed to open in the logs, you need to reconnect the hardware wallet (without turning the geth node off).

If you don’t have a hardware wallet, you can create a software one. Whilst running the initialized node:

  • Linux:

    $ geth attach /home/<username>/.ethereum/geth.ipc
    > personal.newAccount();
    > eth.accounts
  • MacOS:

    $ geth attach /Users/<username>/Library/Ethereum/geth.ipc
    > personal.newAccount();
    > eth.accounts

Where 0x287a817426dd1ae78ea23e9918e2273b6733a43d is your newly created account address and <username> is your user.


The Geth console does not return EIP-55 compliant checksum addresses, and instead will output the lowercase version of the address. Since Nucypher requires EIP-55 checksum addresses, you will need to convert your address to checksum format:

> web3.toChecksumAddress(eth.accounts[0])

Run Geth with Docker

Run a local geth using volume bindings:

docker run -it -p 30303:30303 -v ~/.ethereum:/root/.ethereum ethereum/client-go

For alternate geth configuration via docker see: Geth Docker Documentation.

Remote Ethereum Node

Nucypher supports remote ethereum providers such as Alchemy, Infura, Public Remote Node, but an external transaction signing client is needed separate from the broadcasting node.

External Transaction Signing

In conjunction with an ethereum provider, an external transaction signer can be specified and operated 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

Two external signers are currently supported:

  1. Signing with Clef

  2. Signing with Local Keystore


External signing support is an experimental feature and under active development.

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

We’ll quickly walk through setup steps below, but additional in-depth documentation on Clef can be found in the source repository.

Clef is typically installed alongside geth. 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!

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.

  • <CHAIN ID> - 1 is specified to ensure Clef signs transactions with the network ID of ethereum mainnet.

 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


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


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

Signing with Local Keystore


Can only be used for Worker (Ursula) operations.

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 Goerli testnet, /Users/<username>/Library/Ethereum/goerli/keystore).


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.