Skip to main content
Clique is a proof-of-authority system where new blocks can be created by authorized ‘signers’ only. The initial set of authorized signers is configured in the genesis block. Signers can be authorized and de-authorized using a voting mechanism, thus allowing the set of signers to change while the blockchain operates. Signing blocks in Clique networks classically uses the “unlock” feature of the Parallax client so that each node is always ready to sign without requiring a user to manually provide authorization. However, using the --unlock flag is generally a highly dangerous thing to do because it is indiscriminate, i.e. if an account is unlocked and an attacker obtains access to the RPC api, the attacker can sign anything without supplying a password. Clef provides a way to safely circumvent --unlock while maintaining a enough automation for the network to be useable.

​
Prerequisites

It is useful to have basic knowledge of private networks and Clef. These topics are covered on our private networks and Introduction to Clef pages.

​
Prepping a Clique network

First of all, set up a rudimentary testnet to have something to sign. Create a new keystore (password testtesttest)
Create a genesis with that account as a sealer:
Initiate the Parallax client:
At this point the Parallax client has been initiated with a genesis configuration.

​
Prepping Clef

In order to make use of clef for signing:
  1. Ensure clef knows the password for the keystore.
  2. Ensure clef auto-approves clique signing requests.
These two things are independent of each other. First of all, however, clef must be initiated (for this example the password is clefclefclef)
After this operation, clef has it’s own vault where it can store secrets and attestations.

​
Storing passwords in clef

With that done, clef can be made aware of the password. To do this setpw <address> is invoked to store a password for a given address. clef asks for the password, and it also asks for the master-password, in order to update and store the new secrets inside the vault.
At this point, if Clef is used as a sealer, each block would require manual approval, but without needing to provide the password.

​
Testing stored password

To test that the stored password is correct and being properly handled by Clef, first start clef:
then start the Parallax client:
The Parallax client will ask what accounts are present - enter y to approve:
After this, the Parallax client will start asking clef to sign things:
And indeed, after approving with y, the password is not required - the signed block is returned to the Parallax client:
This mode of operation offers quite a poor UX because each block to be sealed requires manual approval. That is fixed in the following section.

​
Using rules to approve blocks

Clef rules allow a piece of Javascript take over the Approve/Deny decision. The Javascript snippet has access to the same information as the manual operator. The first approach, which approves listing, and returns the request data for ApproveListing, is demonstrated below:
In order to use a certain ruleset, it must first be ‘attested’. This is to prevent someone from modifying a ruleset-file on disk after creation.
which returns:
And clef can be started, pointing out the rules.js file.
Once the Parallax client starts asking clef to seal blocks, the data will be displayed. From that data, rules can be defined that allow signing clique headers but nothing else. The actual data that gets passed to the js environment (and which the ruleset display in the terminal) looks as follows:
To create an extremely trustless ruleset, the raw_data could be verified to ensure it has the right rlp structure for a Clique header:
However, messages could also be used. They do not come from the external caller, but are generated inernally: clef parsed the incoming request and verified the Clique wellformedness of the content. The following simply checks for such a message:
Attest the ruleset:
returning
Run clef:
Run the Parallax client:
And clef should now happily sign blocks:

​
Refinements

If an attacker find the Clef “external” interface (which would only happen if you start it with http enabled), they
  • cannot make it sign arbitrary transactions,
  • cannot sign arbitrary data message,
However, they could still make it sign e.g. 1000 versions of a certain block height, making the chain very unstable. It is possible for rule execution to be stateful (i.e. storing data). In this case, one could, for example, store what block heights have been sealed and reject sealing a particular block height twice. In other words, these rules could be used to build a miniature version of an execution layer slashing-db. The clique header 2 [0xae525b65bc7f711bc136f502650039cd6959c3abc28fdf0ebfe2a5f85c92f3b6] line is split, and the number stored using storage.get and storage.put:
Running with this ruleset:
This might be a bit over-the-top, security-wise, and may cause problems if, for some reason, a clique-deadlock needs to be resolved by rolling back and continuing on a side-chain. It is mainly meant as a demonstration that rules can use Javascript and statefulness to construct very intricate signing logic.

​
TLDR quick-version

Creation and attestation is a one-off event:
The normal startup command for clef:
For the Parallax client, the only change is to provide --signer <path to clef ipc>.

​
Summary

Clef can be used as a signer that automatically seals Clique blocks. This is a much more secure option than unlocking accounts using the Parallax client’s built-in account manager.
Adapted from Clique signing in the go-ethereum documentation, © The go-ethereum Authors. See the third-party notices.